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Editor’s  Preface 


This  hefty  book  contains  the  complete  editorial  contents  of  Dr.  Dobb's  Journal  of 
Software  Tools  for  one  year— its  eleventh  year,  1986.  It  was  the  year  we  added  "Software 
Tools"  to  the  magazine's  name,  jolting  the  lifetime  subscribers  as  we  made  the  magazine's 
lifetime  charter  more  explicit. 

Software  tools  can  mean,  among  other  things,  technical  tips.  In  1986,  DDJ  continued  to 
be  the  best  source  of  technical  information  for  PC/MS-DOS  programmers,  with  articles 
and  columns  on  undocumented  DOS  features,  problems  of  protected  mode,  speeding  DOS 
execution,  direct  control  of  video,  assembly  language  tricks,  and  DOS  resources.  But  DDJ 
also  expanded  its  68000  coverage  in  1986,  and  dealt  with  such  general  programming 
techniques  as  sorting,  code  compression,  data  hiding,  procedure  overloading,  data 
encryption,  and  graphics  algorithms. 

Knowledge  is  the  most  powerful  tool.  In  1986,  DDJ  gave  its  readers  knowledge  in  such 
important  and  timely  areas  as  80386  programming,  graphics  coprocessors,  parallelism,  and 
concurrency.  DDJ  also  summarized  the  new  programmer's  tools  of  1986  and,  in  addition  to 
the  highly  respected  annual  C  compiler  review,  turned  its  programmer's  eye  on  Prolog. 

You'll  find  in  this  volume  a  number  of  tools  for  scientific  and  engineering  applications, 
including  programs  and  algorithms  for  function  minimization  and  fast  math:  that's  part  of 
the  DDJ  software  tools  charter,  too. 

But  chiefly  DDJ  focused  in  1986,  as  it  has  throughout  its  history,  on  the  code:  serious 
code  for  serious  programmers.  You'll  find  herein  a  kernel  for  a  real-time  operating  system, 
a  kernel  for  a  multi-tasking  operating  system,  and  a  Unix-like  shell  for  MS-DOS.  You'll 
find  Lisp  and  Prolog  and  C  and  Pascal  code,  and  Modula-2  and  Ada  and  Forth,  and 
assembly  code  for  any  of  the  major  microprocessors.  Not  checkbook  balancers,  but  useful, 
deep  programs  and  routines — serious  stuff. 

And  you'll  find  the  programming  community  itself.  For  over  a  decade  DDJ  has  provided  a 
forum  for  programmers  to  discuss,  sometimes  vociferously,  the  programming  issues  of 
the  day.  All  the  columns,  letters,  viewpoints,  online  transcripts,  harangues,  and  debates 
from  1986  are  here  intact,  including  one  remarkable  essay  in  which  a  professional 
programmer  redesigned  the  user  interface  of  another  programmer's  commercial  product 
right  out  in  the  open  on  the  pages  of  DDJ. 

OK,  I  guess  I  have  to  admit  that  we  have  some  fun  in  DDJ.  But  it's  serious  fun, 
understand? 
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Blum  Signs  Off 

Dear  DDJ, 

Being  a  part  of  DDJ  for 
practically  three  years  has 
been  an  incredible  experi¬ 
ence.  Even  though  I  won't 
be  writing  a  regular  col¬ 
umn  anymore,  I  don’t  feel 
that  1  am  losing  a  thing. 
The  many  new  friend¬ 
ships  that  I  now  enjoy  and 
the  experiences  that  I 
shared  will  last  a  lifetime. 

Of  particular  impor¬ 
tance  to  me  has  been  your 
feedback.  The  many  let¬ 
ters  I  received,  even  when 
critical,  were  a  delight  to 
read  and  helped  guide  me 
in  preparing  material 
meaningful  to  you. 

Even  though  I  won’t  be  a 
regular  participant  in  fu¬ 
ture  issues  of  DDJ,  I  have  a 
number  of  CP/M  projects 
under  way  that  1  hope  will 
be  accepted  for  publica¬ 
tion  in  the  future. 

In  closing  for  the  last 
time,  allow  me  to  invite 
you  to  continue  to  visit  my 
bulletin  board  system  and 
to  again  thank  each  of  you 
for  looking  in  on  the  CP/M 
Exchange  each  month. 

Bob  Blum 

5536  Colbert  Trail 

Norcross,  GA  30092 

Bob  Blum's  RCP/M  system 
is  available  for  your  use  24 
hours  a  day,  7  days  a  week. 
Beach  it  by  dialing  (404) 
449-6588. 

Dear  DDJ, 

I  have  been  searching 
(with  no  success)  for  the 
address  and  subscription 


cost  for  DTACK  Grounded. 
Would  you  or  any  of  your 
readers  have  this 
information? 

Thank  you  for  your 
time. 

Calvin  Dodge 

4490  Yukon  Ct.,  »2A 

Wheatridge,  CO  80033 

DTACK  Grounded,  one  of 
the  best  newsletters  on  pro¬ 
gramming  and  the  indus¬ 
try,  ceased  publication  with 
Issue  45  to  allow  its  editor, 
Hal  Hardenberg,  to  devote 
more  time  to  software  de¬ 
velopment.  His  company, 
Digital  Acoustics,  is  healthy 
and  is  mailing  subscription 
refunds  to  subscribers. 
Back  issues  are  still  avail¬ 
able  from  Digital  Acoustics, 
1415  E.  McFadden,  Ste.  F, 
Santa  Ana,  CA  92705. — ed. 

Editors 

Dear  DDJ, 

Mark  Edwards  is  to  be  con¬ 
gratulated  for  his  review 
of  editors  in  the  November 
1985  issue  of  Dr.  Dobb’s. 
Anyone  who  ventures  into 
this  highly  personalized 
field  takes  his  life  in  his 
hands,  and  to  attempt  a 
survey  of  ten  editors  is 


chutzpah  indeed.  To  do  it 
with  taste,  relative  com¬ 
pleteness,  and  fairness  is 
no  mean  task. 

As  Mr.  Edwards  notes, 
EC  is  in  a  high  degree  of 
flux,  but  I  would  note  that 
my  version  (probably  later 
than  his,  given  the  lead 
time  it  requires  for  an  arti¬ 
cle)  can  do  backward 
searching  and  does  not 
suffer  the  poor  error  han¬ 
dling  he  referred  to.  An 
important  aspect  of  any 
software  is  that  of  support, 
and  I  would  just  like  to 
comment  that  I  have 
found  the  authors  of  EC  su¬ 
perlative  in  that  aspect. 

A  very  nice  feature  of  EC 
(among  many  others)  is  its 
maintenance  of  the  DOS 
commands  in  a  buffer.  In 
all  my  editing  I  use  APX 
Core,  which  offers  multi¬ 
ple  DOS  partitions.  EC  did 
work  with  APX  but  lost  the 
ability  to  maintain  the  DOS 
command  buffer  under  it. 
I  called  Gene  Brown,  the 
principal  author  of  EC, 
and  informed  him  of  this 
and  also  gave  him  the  ad¬ 
dress  of  APX.  Much  to  my 
surprise  and  delight,  I  re¬ 
ceived  three  (count  them, 


3)  copies  of  the  final  ver¬ 
sion.  One  was  the  stan¬ 
dard,  and  the  other  two 
were  potential  solutions  to 
the  APX  compatibility 
problem.  They  all  worked, 
and  the  solutions  did  so 
beautifully.  How  many 
companies  will  give  such  a 
response? 

I  have  an  additional 
comment  with  respect  to 
the  relevance  of  the  com¬ 
patibility  of  editors  with 
such  “enhancers”  as  Side- 
Kick.  My  experience  has 
been  that  in  the  long  run 
the  side  effects  of  these 
programs  are  less  desir¬ 
able  than  their  offerings. 
Even  more  to  the  point, 
though,  XyWrite,  BRIEF, 
and  EC  (and  probably  oth¬ 
ers  in  the  review  also)  are 
sufficiently  internally 
complete  that  you  really 
do  not  need  such  en¬ 
hancers.  BRIEF,  with  its 
powerful  macro  capabili¬ 
ty,  allows  you  to  create 
these  enhancements  for 
the  most  part,  as  does 
XyWrite  for  those  it  does 
not  have;  EC  has  most  of 
them  built-in,  and  the  few 
it  doesn’t,  you  can  create. 
Communications  are  ac¬ 
cessible  by  any  of  these 
editors  because  you  can 
exit  to  DOS,  so  you  have  the 
advantage  of  no  overhead 
and  no  potential  side  ef¬ 
fects.  With  BRIEF,  I  even 
wrote  a  perpetual  calen¬ 
dar  to  mimic  that  aspect  of 
SideKick. 

Because  people  tend  to 
use  editors  for  short  corre¬ 
spondence,  a  relatively  im¬ 
portant  aspect  is  their  "re¬ 
formatting”  speed  as  most 
editors  do  not  (understand¬ 
ably)  maintain  word  wrap 
for  text  insertion  after  a 
line  has  been  entered.  One 
of  the  problems  I  found 
with  EDIX  was  its  intoler¬ 
ably  slow  reformatting — in 
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this  respect  VEDIT  and  EC 
are  lightning  fast,  and 
BRIEF  (with  its  free  refor¬ 
mat  macro)  is  only  slightly 
faster  than  EDIX.  XyWrite 
of  course  does  it  like  any 
respectable  word 

processor. 

I  enjoyed  reading 
"Wired  Tales"  in  Dave  Cor- 
tesi's  column  in  the  De¬ 
cember  issue  and  offer  the 
following.  I  recently  decid¬ 
ed  to  upgrade  my  PC  with 
a  larger  power  supply  (64 
watts  to  135  watts)  and,  be¬ 
ing  relatively  frugal,  or¬ 
dered  one  from  a  mail-or¬ 
der  house  for  $89.  When  it 
arrived  I  (foolishly)  started 
to  install  it:  removed  my 
old  power  supply,  put  the 
new  one  in,  and  started  to 
make  the  connections.  To 
my  dismay,  it  turned  out 
that  the  connectors  were 
poorly  constructed  and  I 
could  not  get  a  good  fit.  I 
decided  to  return  the  sup¬ 
ply  for  credit,  not  wanting 
to  chance  a  repeat  perfor¬ 
mance.  It  took  me  about 
$15  worth  of  phone  calls  to 
finally  talk  to  someone 
who  was  authorized  to  is¬ 
sue  an  RA,  and  that  same 
person  informed  me  that 
there  was  a  10  percent  re¬ 


stocking  fee.  Adding  in  the 
cost  of  the  UPS  shipment 
back,  I  wound  up  paying 
$30  for  some  futile  labor  in 
taking  out  and  replacing 
my  power  supply  losing  a 
nontrivial  amount  of  time 
in  the  process. 

Finally  I  offer  a  poser.  I 
recently  purchased  an  un¬ 
interruptible  power  sup¬ 
ply  (300  watts)  from  Qubie. 
When  it  was  delivered,  I 
tested  it  in  the  usual  way — 
I  pulled  the  power  plug — 
and  it  worked  fine.  Just  to 
be  doubly  sure,  I  also 
opened  the  main  circuit 
breaker  in  the  house,  and 
the  same  excellent  perfor¬ 
mance  repeated.  A  few 
days  ago,  we  had  our  first 
real  power  outage  while  I 
was  working  at  my  PC, 
and  much  to  my  surprise,  I 
lost  all  my  work.  When 
the  power  returned  about 
one  minute  later,  I  imme¬ 
diately  made  the  "pull  the 
plug"  test  and  it  worked.  I 
called  Qubie’s  technical 
department,  and  no  one 
could  offer  a  solution,  but 
the  company  did  offer  to 
send  me  a  replacement 
(which  I  accepted).  In  the 
meantime  I  have  been 
thinking  about  the  possi¬ 
ble  causes  of  the  loss  of  my 
work  and  believe  I  may 
understand  why  it  hap¬ 


pened,  but  I  would  love  to 
hear  from  others. 

Morton  F.  Kaplon 

11  White  Birch  Dr. 

Pomona,  NY  10970 

Dear  DDJ, 

Although  I  greatly  enjoyed 
Mark  Edwards'  editor  re¬ 
view  (DDJ,  November 
1985),  I  would  like  to  make 
a  correction  or  two  and 
point  out  a  problem  with 
this  kind  of  review.  I  think 
Mr.  Edwards  did  a  terrific 
job  given  the  difficulty  of 
trying  to  learn  about  ten 
text  editors,  much  less  try¬ 
ing  to  comment  intelli¬ 
gently  about  them  all.  I  use 
Pmate  (Version  3.37)  on  a 
daily  basis,  however,  and  I 
am  familiar  enough  with  it 
to  have  caught  a  couple  of 
errors  in  the  review. 

The  first  (and  smallest)  is 
that  Pmate  does  indeed  al¬ 
low  you  to  undo  the  dele¬ 
tion  of  a  single  character. 
What  it  will  not  allow  is 
the  retrieval  of  a  character 
you  have  backspaced 
away.  On  a  PC,  this  is  the 
difference  between  the 
Delete  key  and  the 
(backspace)  key.  The  dif¬ 
ference  can  be  annoying, 
but  it  is  frequently  more 
helpful  than  not  once  you 
are  aware  that  Pmate 
works  in  this  way. 

A  more  serious  error  is  in 
Mr.  Edwards'  Pmate  macro 
to  count  braces.  The  macro 
he  presents  does  indeed 
work,  but  it  is  terribly 
slow.  Trying  it  on  a  sample 
C  program  out  of  one  of 
my  working  directories  (on 
a  Compaq  Plus),  it  ran  for 
more  than  six  minutes  be¬ 
fore  I  aborted  it — unfin¬ 
ished.  There  is  a  much  bet¬ 
ter  Pmate  macro  for  brace 
counting,  which  I  present 
in  Table  1,  page  10.  This 
brace-counting  macro  fin¬ 
ished  the  same  piece  of 
code  as  above  in  less  than 
six  seconds  (and  is  slowed 
slightly  because  it  is  con¬ 
structed  to  work  with  a  file 


.  *  *  * 

;  *  *  *  Pmate  brace  counting  macro  program 
.  *  *  * 

Ovl 

;set  variable  1  to  0 

ua 

;go  to  top  of  file 

i 

;begin  loop 

e 

suppress  error  messages 

us{ 

;search  for  an  open  brace 

© 

T 

o 

;if  none  found,  exit  loop 

val 

else  increment  count  of  braces 

1 

;end  loop 

ua 

;return  to  top  of  file 

i 

;begin  loop 

e 

;supress  error  messages 

us} 

;search  for  closing  braces 

© 

T 

o 

1 

;if  none  found,  exit  loop 

-Ival 

;else  decrement  count  of  braces 

] 

t  ;end  loop 

b2e 

;go  to  buffer  2 

@1\ 

;put  the  result  in  buffer  2 

Table  1 


of  any  size  as  opposed  to 
one  entirely  in  memory). 
This  is  a  huge  difference 
from  the  results  reported 
in  the  review.  Because  of 
differences  in  the  test  files, 
it  is  impossible  to  say 
whether  this  performance 
is  better  or  worse  than 
BRIEF  or  EMACS,  but  it  is 
certainly  of  the  same 
order. 

It  is  worth  noting  that 
the  macro  presented  in  Ta¬ 
ble  1  works  in  much  the 
same  manner  as  the  BRIEF 
and  EMACS  macros  present¬ 
ed  by  Mr.  Edwards.  In  par¬ 
ticular,  it  allows  the  editor 
itself  to  search  for  the  char¬ 
acters  to  be  counted  rather 
than  stepping  through  the 
file  in  a  clumsy  character- 
by-character  fashion.  I  sus¬ 
pect  that  a  properly  rewrit¬ 
ten  macro  for  VEDIT  PLUS 
would  show  the  same  kind 
of  dramatic  speed  im¬ 
provement.  There  might 
even  be  some  hope  for  XTC 
if  the  proper  macro  formu¬ 
lation  were  used. 

This  in  turn  points  out  a 
serious  difficulty  in  bench¬ 
marking  editors.  A  user 
who  is  familiar  with  an  edi¬ 
tor  will  undoubtedly  be 
able  to  generate  a  better 
benchmark  than  one  who 
isn't.  I  would  never  have 
even  considered  writing  a 
brace-counting  program 
for  Pmate  in  the  way  Mr. 
Edwards  did.  The  way 
Pmate  works  guarantees 
that  his  macro  is  among  the 
slowest  possible  for  the 
task. 

Based  on  my  experi¬ 
ence,  I  would  tend  to  agree 
with  Mr.  Edwards’  com¬ 
ments  about  the  functiona¬ 
lity  and  features  of  each 
editor  he  reviewed.  Based 
on  my  findings  for  Pmate, 
though,  I  would  be  in¬ 
clined  to  disregard  the  en¬ 
tire  benchmark  table  ex¬ 
cept  for  items  A,  B,  F,  and 
maybe  C. 

Mr.  Edwards  has  cer¬ 
tainly  proved  that  it  is  im- 


Dr.  Dobb's  Journal,  January  1986 


10 

3 


JANUARY  1986 


CONTENTS 


VOLUME  11,  ISSUE  1 


Dr.  Dobb's  Journal  of 


Software  Tools 

FOR  THE  PROFESSIONAL  PROGRAMMER 


ARTICLES 


Is  it  C  or  is  it 
assembly? 
WordStar  on  an 
Atari  ST?  ► 


COMPILERS:  PL/68K  bv  Edward  K.  beam  20 

Tile  author  of  the  RED  editor  could  find  no  accep¬ 
table  compiler  for  the  68K,  so  he  wrote  one.  But 
PL/68K  is  not  like  other  compilers. 

SYSTEMS:  A  Simple  OS  for  Rt:al  Time  44 

Applications  by  Xick  T lirner 
In  setting  up  a  multiuser  system,  the  author  found 
ways  to  shave  many  machine  cycles  off  every  in¬ 
struction.  Here  he  explains  how  he  did  it  and  offers 
some  illustrative  code. 

HARDWARE:  Bringing  up  the  08000  OO 

by  Alan  K.  Wilcoy 

Here's  how  to  get  a  88000  running  very  quickly. 

PORTABILITY:  COM:  An  8080  Simulator  70 

for  the  MC08000  by  Jim  Cathey 
Besides  being  a  useful  tool,  this  program  contains 
some  insights  gained  in  the  process  of  developing  a 
68K  application.  The  author  also  shows  how  to  ex¬ 
tend  the  simulator  for  Z80  instructions. 


COLUMNS 


Mysterious  and 
dangerous 
programs 


C  CHEST:  A  Unix-like  Shell  for  MS  DOS 

by  Allen  Holub 

Allen  describes  how  the  shell  works  on  a  high  level 
and  includes  examples  of  some  often-used  functions 

16-BIT  TOOLBOX:  Trojan  Horse  Programs 

by  liav  Duncan 

These  mysterious  and  destructive  programs  are  ap¬ 
pearing  on  bulletin  boards.  What  can  be  done  to 
combat  them? 


18 


1  18 


FORUM 


What  C 
program  m  ers 
don 't  knoiv  can 
hurt  them.  ► 

DDJ  is  note  on  ► 
CompuServe. 


EDITORIAL:  The  New  l 
Cook  by  Michael  Swaine 
LETTERS:  Comment  t 
bv  our  readers 
CARTOON:  A  Word  on  I 
Formats  by  band  benfroe 
VIEWPOINT:  1< 

Inefficient  C 
by  Hal  Hardenberg 
DDJ  ON  LINE:  1 ' 

The  Electronic  Edition 
bv  Crank  Debose 


PROGRAMMERS' 

SERVICES 


PROFESSIONAL  124 

PROGRAMMER:  A 

little  library  of  books 
on  the  profession 
OF  INTEREST:  126 

New  products  of  interest 
to  programmers 
ADVERTISER  128 

INDEX: 

Where  to  find  that  ad 


Dr  DoMftfoumtlot 


Software  Tools 


i  PltOGBAMMiP 


Our  anniversary  cover  was 
designed  by  Shelley  Rae 
bocden,  who  also  is  respon¬ 
sible  for  the  new  look  of  the 
magazine.  Shelley  is  DDJ's 
Art  Director. 


This  Issue: 

The  Motorola  68000  chip  is, 
some  say,  a  programmer's 
processor.  The  instruction 
set  is  rich  and  logically  con¬ 
structed,  and  memory  access 
is  simple  and  capacious 
What  it  lacks,  others  say,  are 
a  standard  operating  system 
and  development  tools.  This 
month  we  focus  on  pro¬ 
gramming  tools  for  the  68K. 


Next  Issue: 

Next  month  we  ll  look  at 
si  ructured  programming 
anti  at  some  languages  that 
have  a  reputation  for  en¬ 
couraging  structured  design. 
We'll  publish  programming 
tools  in  Pascal.  Modula-2, 
and  Ada  We  ll  tell  you 
where  to  get  public-domain 
Ada  utilities  to  speed  Ada 
software  development,  anti 
we  ll  look  at  a  program  that 
ports  between  dialects  of 
Pascal. 
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lions:  Articles,  Re¬ 
views,  Columns,  Fo¬ 
rum,  and  Program¬ 
mers'  Services. 
Forum  contains  the 
editorial,  letters,  an 
editorial  cartoon, 
and  an  invited  view- 
this  month 


Late  1975  and 

saw  a  number  HMHpin 
of  new  magazines 
for  a  new  group  of 

readers  the  pioneer¬ 
ing  users  of  the  first 

Most  were  heavy  on 
hardw  are  because 

there  was  essentially 

no  software  to  write 
about  back  then.  In  January  1976,  a 
remedy  for  this  situation  appeared  in 
the  form  of  a  magazine  providing  the 
tools  needed  to  develop  software:  Dr. 
Dobb  s  Journal  of  Tiny  BASIC  Calis¬ 
thenics  it  Orthodontia. 

Ten  years  later,  DDJ  is  still  provid¬ 
ing  software  tools  for  serious  pro¬ 
grammers.  We've  replaced  "calis¬ 
thenics  and  orthodontia"  with  other 
metaphors  and  have  moved  upscale 
front  a  black-and-white  newsletter  to 
a  four-color  magazine,  but  we  still 
publish  the  only  pages  in  which  you 
can  find  compilers,  assemblers,  and 
programming  tools  reviewed,  de¬ 
signed,  analyzed,  and  source-listed, 
with  the  whole  process  watched 
over  by  the  most  knowledgable  read¬ 
ership  in  the  industry. 

Was  that  last  paragraph  excessive¬ 
ly  self-congratulatory?  Pardon  it,  but 
there  is  occasion  for  it:  This  month  is 
nt)J’ s  tenth  birthday.  This  birthday 
issue  features  articles  on  68000  pro¬ 
gramming,  leading  off  with  Edward 
Ream's  assembler  that  thinks  it's  a 
compiler.  In  a  more  overtly  festive 
act,  this  issue  also  unveils  the  new'  de¬ 
sign  for  DDJ. 

The  new  design  should  more  di¬ 
rectly  indicate  what  the  magazine 
provides:  programming  tools  in  the 
form  of  articles  and  listings,  reviews, 
columns,  a  forum  for  discussion  of 
programming  issues,  and  services 
such  as  product  listings.  The  title 
treatment,  while  harking  back  to  the 
original  cover  design,  makes  it  clear 
that  what  this  magazine  contains  are 
software  tools.  Inside,  we've  gath¬ 
ered  all  the  contents  into  five  sec- 


■  point 

by  68K  authority  Hal 
Hardenberg.  Pro¬ 
grammers'  Services 
will  grow;  this  month  it  contains  a 
section  of  information  on  the  profes¬ 
sional  side  of  programming.  No  room 
for  reviews  this  month. 

We  are  fortunate  to  have  some  ex¬ 
cellent  columnists  who  provide  a 
personal  view  along  with  useful  tips 
and  utilities.  Unfortunately,  two  of 
them  are  retiring  from  their  colum¬ 
nist  duties:  Dave  Cortesi  and  Bob 
Blum.  Bob  is  just  too  busy  to  keep  up 
a  monthly  column  and  to  do  as  good 
a  job  as  he  wants;  he'll  continue  to 
contribute  articles  and  to  maintain 
his  CP/M  bulletin  board.  He  has  writ¬ 
ten  a  sign-off  letter  that  appears  on 
page  8.  Dave  is  leaving  computer 
writing  for  the  writing  of  fiction. 
Both  were  longtime  contributors  and 
will  be  missed.  We  are  actively  if 
grudgingly,  seeking  replacements. 
Perhaps  you  know  a  candidate? 

Finally,  there's  the  electronic  com¬ 
ponent  we’ve  added  to  the  maga¬ 
zine.  By  the  time  you  read  this,  DDJ 
should  he  up  on  CompuServe.  See 
page  17  for  details.  ,  __ 
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LETTERS 

(Continued  from  page  10) 


possible  for  a  single  person 
to  learn  enough  about  ten 
different  editors  to  be  able 
to  compare  each  at  its  best. 
Brad  Chase 
P.O.  Box  705 
Exeter,  NH  03883 

Modula-2 

Dear  DDJ, 

While  perusing  your  oth¬ 
erwise  excellent  Novem¬ 
ber  issue,  I  felt  a  sudden 
stab  of  pain.  Looking  clos¬ 
er,  I  saw  the  source  of  my 
discomfort  was  "Bit  Ma¬ 
nipulation  in  Modula-2.”  1 
feel  an  overwhelming 
need  to  comment. 

"I  knew  from  the  outset 
that  it  was  impossible  to 
match  C’s  simplicity.”  This 
tells  me  that  the  author  is 
primarily  a  C  hacker.  Mo¬ 
dula-2  is  perfectly  capable 
of  matching  this  "simplic¬ 
ity,”  and  in  exactly  the 
same  manner.  (See  Table  2, 
below.) 

The  other  operations  are 
left  as  exercises  for  the 
reader. 

Lawrence  C.  Smith 
51  Lake  St. 

Nashua,  NH  03060 

C  Compilers 

Dear  DDJ, 

I  love  Dr.  Dobb's  and  have 
subscribed  for  years.  I  no¬ 
tice  a  trend  away  from  as¬ 
sembly,  CP/M,  8-bit,  and 
the  less  wealthy  user, 
though.  In  particular,  your 
issue  on  C  language  was  a 


disappointment.  The  fol¬ 
lowing  are  my  reasons, 
along  with  some  sugges¬ 
tions.  I  understand  your 
problems  in  appealing  to  a 
divergent  group,  howev¬ 
er,  and  appreciate  your 
willingness  to  listen  to  all 
our  suggestions. 

1.  The  main  article  on  C 
comparisons  told  me  more 
than  I  really  cared  to 
know  about  the  languages. 

I  would  have  trusted  the 
writers  if  they  had  sum¬ 
marized  their  results.  An 
article  this  long  and  de¬ 
tailed  should  have  a  sum¬ 
mary  at  the  beginning. 

2.  The  article  did  not 
state  which  of  the  lan¬ 
guages  examined  were 
available  on  either  S-100 
machines,  on  CP/M,  or  on 
8-bit  machines. 

3.  I  did  not  see  mention 
of  several  of  the  Cs  I  use — 
BDS  C,  Small-C,  or  Tiny  C  or 
any  mention  of  Lifeline's 
products — and  that  would 
have  been  important  to 
me.  I  am  sure  other  Cs 
could  have  been  found  as 
well — so  how  much  long¬ 
er  would  it  have  taken  to 
wait  a  bit  and  do  a  truly  de¬ 
finitive  review? 

Frederic  Schlamp 

2205  Meadowview  Rd. 

Sacramento,  CA  95832 

The  comparative  review  of 
C  compilers  in  our  August 
1985  issue  was  strictly  dedi¬ 
cated  to  MS  DOS-compatible 
compilers.  We  will  review 
C  compilers  for  other  envi¬ 
ronments,  including  CP/M, 


in  1986. — ed. 

Columns 

Dear  DDJ, 

In  your  July  1985  issue  the 
16-Bit  Software  Toolbox 
column  began  with  the 
line  "One  of  the  most  nov¬ 
el  features  added  in  Ver¬ 
sion  2  of  MS  DOS  is  the  con¬ 
cept  of  'installable  device 
drivers.’  ”  I  would  like  to 
say  that  this  concept  may 
be  new  and  novel  for  Mi¬ 
crosoft  and  MS  DOS,  but  it  is 
certainly  not  a  new  and 
novel  concept  for  other 
operating  systems  avail¬ 
able  for  microprocessors. 

The  OS-9  operating  sys¬ 
tem  has  had  the  concept  of 
user-installable  device 
drivers  since  its  initial  6809 
Level  1  release  in  1978.  In 
fact,  OS-9  is  totally  modu¬ 
lar  in  nature  and  allows 
the  user  to  add  new  device 
descriptors,  device  driv¬ 
ers,  and  new  file  managers 
if  required.  In  addition  to 
supporting  installable 
drivers,  OS-9  has  included 
the  "novel”  MS  DOS  con¬ 
cepts  of  hierarchical  direc¬ 
tor  structures  and  pipes. 
OS-9  also  gives  full  support 
to  I/O  redirection,  multi¬ 
processing,  and  multitask¬ 
ing — concepts  much  more 
akin  to  Unix. 

OS-9  may  not  be  as  well 
known  as  MS  DOS  is,  but  it 
does  have  a  large  and  rap¬ 
idly  growing  following  in 
the  6809  and  68XXX  world 
today.  MS  DOS  has  added 
nothing  novel  to  its  OS;  it  is 
adding  features  that  are 
expected  and  required  for 
an  OS  in  today's  world. 
These  features  have  been 
around  in  OS-9  and  OS-9/ 
68000  for  some  time. 

Tim  Harris 

Microware  Systems 
Corp. 

1866  N.W.  114th  St. 

Des  Moines,  IA  50322 

Dear  DDJ, 

"It  isn't  what  you  don't 
know  that  hurts  you,  it’s 


(*  assume  ch:=CHAR(255)  *)  (*  clearing  bits  *) 

(*  clear  bit  7  *); 

ch: =CHAR(BOOLEAN(ch)  &  BOOLEAN(07FH)); 

(*  result  is  ch=CHAR(127)  *) 

(*  assume  ch:=CHAR(15)  *)  (*  setting  bits  *) 

(*  set  bit  5  *) 

ch:  =  CHAR(BOOLEAN(ch)  OR  BOOLEAN(IOH)); 

(*  result  is  ch  =  CHAR(63)  *) 


Table  2 


what  you  know  that  ain’t 
so."  In  the  September  Of 
Interest  column,  the  au¬ 
thor  states  that  APL  on  the 
IBM  PC  requires  an  8087. 
This  is  only  true  for  IBM's 
own  APL,  not  for  the  other 
five  (STSC,  Sharp,  Portable 
Software,  Watcom,  and 
NIAL  Systems).  Most  of 
them  run  on  the  PCjr. 
Edward  M.  Cherlin 
6611  Linville  Dr. 

Weed,  CA  96094 

Dear  DDJ, 

I  was  interested  to  read  the 
portion  of  your  Dr.  Dobb's 
Clinic  (October  1985)  re¬ 
garding  the  intricasies  of 
manipulating  path  names. 
Some  time  ago,  we  at  POLY- 
TRON  also  had  the  pleasure 
of  figuring  out  how  to  do 
exactly  what  you  dis¬ 
cussed.  Our  solution, 
which  produced  some 
functions  that  are  more 
general  purpose,  might  in¬ 
terest  your  readers.  The 
primary  components  of 
our  solution  are: 

1.  A  function  to  deter¬ 
mine  if  a  given  path  name 
represents  a  directory — 
that  is,  it  is  a  drive  ID  or  an 
actual  director  but  not  a 
normal  file: 

int  is_dir(name) 
char  “name; 

2.  A  function  to  deter¬ 
mine  if  a  given  file  name 
contains  wildcard  charac¬ 
ters: 

int  is_wild(name) 
char  "name; 

3.  A  general-purpose 
function  for  generating  a 
new  file  name  given  an  ex¬ 
isting  file  name,  an  option¬ 
al  new  extension,  and  an 
optional  new  path: 

char  * 

bld_fnam(pathp, 
namep,  extp) 
char  *pathp; 
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/*  the  new  path  */ 
char  “namep; 

/*  the  original  name  */ 
char  *extp; 

/*  the  new  extension  */ 

This  returns  a  pointer  to 
allocated  memory  contain¬ 
ing  the  newly  constructed 
file  name.  The  original 
name  may  or  may  not 
have  a  path  or  extension.  If 
either  pathp  or  eytp  point 
to  a  null  string,  the  respec¬ 
tive  component  of  the 
original  name  is  omitted 
from  the  new  name.  If  ei¬ 
ther  pathp  or  eytp  is  a  null 
pointer,  the  respective 
component  of  the  original 
is  used  in  the  new  name. 

4.  A  wildcard  file  name 
expansion  function  with 
optional  ability  to  prepend 
the  path  of  the  wildcard 
name  to  each  matching 
name  is  shown  in  Table  3 
(below).  This  returns  a 
pointer  to  a  linked  list  of 
names  matching  the  wild¬ 
card  name.  Each  node  of 
the  list  is  contained  in  sep¬ 


arately  allocated  memory 
and  is  of  sufficient  length 
to  contain  the  matching 
name  beginning  at 
name[0]. 

5.  Functions  to  extract 
each  of  the  three  compo¬ 
nents  of  a  file  name — the 
path,  the  root,  and  the  ex¬ 
tension  are  shown  in  Ta¬ 
ble  4  (below).  These  func¬ 
tions  each  return  a  pointer 
to  allocated  memory  con¬ 
taining  the  respective 
component  of  a  file  name. 

Using  these  functions, 
you  can  do  just  about  any¬ 
thing  you  wish  with  file 
names.  In  fact,  they  are 
used  in  nearly  all  our 
products  and  continue  to 
be  used  in  new  develop¬ 
ment  work. 

These  functions,  along 
with  a  host  of  others,  are 
available  in  the  POLYTRON 
C  Library  1.  This  package 
contains  routines  that 
function  under  DOS  1.x, 
DOS  2.x  and  later,  and 
both/either.  The  functions 
are  provided  in  linkable 
form  (libraries),  as  well  as 
in  full  source  form  (C  and 
assembler)  for  the  IBM  PC/ 


XT/AT  and  compatibles. 

Donald  K.  Kinzer 

POLYTRON  Corp. 

PO.  Box  787 

Hillsboro,  OR  97123 

Dear  DDJ, 

Here  is  a  report  on  a  soft¬ 
ware  company  for  the  ben¬ 
efit  of  prospective  buyers.  I 
purchased  a  cross-assem¬ 
bler  from  2500AD  in  No¬ 
vember  1984.  What  they 
sent  me  was  a  nonfunc¬ 
tioning  program.  Soon  af¬ 
ter  receiving  the  program, 
I  sent  two  letters,  made  two 
phone  calls,  and  finally 
spoke  to  someone  who  said 
the  company  would  send 
me  a  good  copy  when  it 
had  fixed  the  program.  It 
has  been  a  year,  the  firm 
still  has  my  $200,  and  I 
have  not  yet  received  a 
functional  copy  of  the  pro¬ 
gram.  Even  JRT  Pascal  was 
functional,  and  look  at  the 
price  difference! 

For  the  record,  here  are 
the  defects  that  I  have 
found  (so  far): 

1.  The  assembler  and  the 
linker  are  incompatible. 
The  linker  makes  the 
wrong  assumptions  about 
the  relative  order  of  least/ 
most  significant  bytes, 
which  makes  it  impossible 
to  link  object  modules.  The 
only  way  to  get  an  execut¬ 
able  file  is  to  put  all  your 
code  into  one  module  and 
use  absolute  addressing 
(with  an  ORG  statement). 

2.  The  assembler  gives 
the  wrong  machine  code 
for  several  of  the  opcodes. 
This  makes  for  difficult 
debugging. 

3.  Some  of  the  pseudo¬ 
ops  listed  in  the  manual 
don't  exist  in  the  actual 
assembler. 

4.  Some  of  the  pseudo¬ 
ops  that  do  exist  do  not 
work  (at  least  one). 

5.  The  assembler  has  no 
provision  for  allowing  the 
programmer  to  specify  the 
short  forms  of  the  relative 


/'  element  of  a  linked  list  of  matching  names  */ 

struct  file _ list 

( 

struct  file _ list 

'next;  /*  ptr  to  next  node  */ 

char  name[1]; 

/*  a  file  name  */ 

/» 

struct  file _ list  * 

expand(wildname,  add_path) 

char  'wildname; 

/*  the  name  to  match  */ 

int  add_path; 

/*  non_zero  if  path  of  wildname  should  be 
prepended  to  matching  names  */ 

Table  3 

char  * 

path_of(name) 
char  'name; 
char  * 

/'  the  name  from  which  to  extract  the  path  */ 

root_of(name) 
char  'name; 
char  * 

/*  the  name  from  which  to  extract  the  root  */ 

ext_of(name) 
char  ‘name; 

/'  the  name  from  which  to  extract  the 

extension  V 

Table  4 


jump  and  call  instructions. 

6.  The  symbol  table  that 
is  printed  at  the  end  of  the 
listing  usually  contains  sec¬ 
tions  of  garbled  mess. 

7.  The  printed  symbol 
table  lists  all  intermediate 
values  of  labels  that  are  re¬ 
defined  many  times  with 
the  DEFL  statement. 

8.  Some  errors  in  the 
source  code  cause  the  as¬ 
sembler  to  crash  with  no 
error  message. 

9.  The  linker  crashes 
with  a  nonsense  error 
message  under  some  con¬ 
ditions  that  seem  to  have 
something  to  do  with  cer¬ 
tain  exact  lengths  of  files. 

Neil  R.  Koozer 

Kellogg  Star  Rt. 

Box  125 

Oakland,  OR  97462 

In  the  September  issue,  we 
ran  a  comparative  review 
of  PC  TEX  and  MicroTEX. 
At  that  time  only  PC  TEX  in¬ 
cluded  1NITEX,  but  we  stat¬ 
ed  that  MicroTEX  was  also 
scheduled  to  include  INITEX 
in  an  August  update.  As  of 
the  time  this  issue  went  to 
press,  MicroTEX  still  does 
not  include  full  INITEX  ca¬ 
pabilities.  We  have  been  in¬ 
formed  by  Addison-Wes- 
ley  that  a  new  version  of 
MicroTEX,  including  INI¬ 
TEX,  will  not  be  available 
until  January  1,  1986.  Check 
with  Addison-Wesley  be¬ 
fore  placing  an  order.  Both 
Addison-Wesley  and  Per¬ 
sonal  TEX  are  already  dis¬ 
tributing  the  Teytset  laser 
printer  and  screen  preview 
driver. — ed. 
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Inefficient  G 


This  column  is  adapted 
from  DTACK  Grounded, 
The  Journal  of  Simple 
68000/32801  Systems,  Issue 
42. 

It  has  been  apparent  to 
me  for  two  or  three 
years  now  that  complex 
programs  (as  opposed  to 
the  famous  but  simplistic 
'hello  world''  type)  writ¬ 
ten  in  C  consistently  run  a 
great  deal  slower  than  the 
same  complex  programs 
written  in  assembly.  Ex¬ 
amples  of  this  rule  can 
readily  be  found  in  the 
personal  computer  mass 
marketplace. 

It  is  true  that,  in  the  last 
year  or  two,  many  intelli¬ 
gent  and  experienced  pro¬ 
grammers  have  asserted 
that  C  has  little  or  no  high- 
level  language  (HLL) 
overhead. 

There  is  an  apparent 
conflict  here. 

Consider  the  complex 
problem  of  writing  a  BASIC 
interpreter.  You  can  break 
this  problem  down  into  a 
large  number  of  simple 
problems  that  can  then  be 
solved  in  assembly  or,  say, 
C.  The  speed  with  which 
each  of  the  simple  prob¬ 
lems  can  be  solved  de¬ 
pends  on  how  good  a 
match  can  be  made  be¬ 
tween  the  problem  and 
the  available  control  con¬ 
structs,  data  types,  and  so 
on.  In  some  cases  the 
match  with  the  constructs 
and  data  types  available  in 


by  Hal  Hardenberg 


C  is  as  good  as  the  best  that 
can  be  devised  using  as¬ 
sembly,  and  you  have  zero 
HLL  overhead.  In  fact, 
many  simple  problems  can 


be  solved  as  quickly  (or 
nearly  so)  in  C  as  in 
assembly. 

So,  the  C  supporters 
have  no  shortage  of  real- 
world  examples  of  simple 
problems  that  can  be 
solved  as  quickly  (or  nearly 
so)  in  C  as  in  assembly, 
which  leads  them  to  claim 
that  C  has  no  high-level 
overhead. 

Some  problems,  though, 
can  be  solved  easily  and 
quickly  in  assembly  and 
are  real  bears  in  C,  given 
the  restricted  range  of  op¬ 
erations,  constructs,  and 
data  types  available  to  C 
programmers.  The  large 
number  of  simple  prob¬ 
lems  that  comprise  a  BASIC 
interpreter  will  include 
some  C-easy  problems, 
some  C-not-so-easy  prob¬ 
lems,  and  some  C-bears. 
Therefore,  any  full-func¬ 
tion  BASIC  interpreter  writ¬ 
ten  in  C  will  always  be  a 
great  deal  slower  than  the 
same  interpreter  written 
in  assembly. 

You  need  not  look  for 
complex  ways  to  analyze 
the  HLL  overhead  of  C  (or 
any  high-level  language). 
The  fact  is,  all  high-level 
languages  greatly  restrict 
the  range  of  operations, 
control  constructs,  and 
data  types  available,  com¬ 
pared  to  assembly  lan¬ 
guage.  Thus,  HLL  program¬ 
mers  have  a  limited 
number  of  tools  available 
for  solving  the  large  num¬ 
ber  of  simple  problems 
that  comprise  any  solvable 
complex  problem. 

Obviously  the  program¬ 
mer  with  the  most  com¬ 
plete  set  of  tools  can  al¬ 
ways  produce  the  fastest 
code.  Real-world  evidence 
such  as  Microsoft's  MBASIC 
(written  in  assembly)  vs. 
DRl's  Personal  BASIC  (writ¬ 
ten  in  C)  confirms  this  rule. 


Why  then,  do  intelligent, 
experienced  programmers 
claim  that  C  has  little  or  no 
HLL  overhead  when  abun¬ 
dant  real-world  evidence 
contradicts  such  an 
assertion? 

Well,  suppose  you  have 
solved  a  complex  problem 
using  C.  Then,  keeping  the 
90-10  rule  in  mind,  you  go 
looking  for  ways  to  speed 
up  the  software.  Do  you  re¬ 
write  the  program  from 
scratch  in  assembly,  using 
the  greater  variety  of  avail¬ 
able  operations,  data  struc¬ 
tures,  and  control  con¬ 
structs?  No,  you  continue 
to  use  the  data  structures 
and  algorithms  that  you 
developed  in  C.  That  is, 
you  implicitly  restrict 
yourself  to  the  smaller 
toolkit  that  is  already  used 
by  C!  Not  surprisingly  the 
resultant  program  is  not 
much  faster  than  the  origi¬ 
nal.  Hence  you  announce, 
‘‘Hey,  guys,  I  tried  optimiz¬ 
ing  the  problem  using  as¬ 
sembly  and  got  little  or  no 
improvement  over  the 
original  C.  Obviously  C  has 
little  or  no  high-level 
overhead.” 

Obviously. 

HLL  inefficiency  is  ac¬ 
ceptable  in  many  environ¬ 
ments.  Where  HLL  ineffi¬ 
ciency  is  not  acceptable  is 
in  the  personal  computer 
mass  marketplace  wherev¬ 
er  an  efficient  alternative 
is  available.  DRl's  Personal 
BASIC  is  essentially  a  dead 
issue,  being  highly  uncom¬ 
petitive  with  Microsoft’s 
assembly-based  BASICS  in 
terms  of  speed.  In  turn,  the 
marketplace  is  widely 
avoiding  Microsoft's  Co¬ 
written  FORTRAN 
compiler. 

The  individuals  who 
make  up  the  mass  market¬ 
place  and  who  vote  with 
their  wallets  don’t  care 


how  hard  it  was  to  produce 
a  program  or  how  long  it 
took.  They  don't  care  about 
source  documentation  or 
maintainability  because 
they  never  get  to  see  the 
source  documentation  and 
somebody  else  maintains 
the  code.  They  vote  for 
those  programs  that  work 
both  swiftly  and  well  (Lo¬ 
tus  1-2-3,  original  WordStar, 
MBASIC,  or  GW-BASIC)  rath¬ 
er  than  those  that  run  well 
but  slowly  (Context  MBA, 
WordStar  2000,  or  DRI  Per¬ 
sonal  BASIC). 

The  folks  who  assert  that 
C  has  little  or  no  HLL  over¬ 
head  are  either  talking 
about  simple  problems  for 
which  C  is  in  fact  well  suit¬ 
ed,  or  they  are  observing 
that,  if  algorithms  written 
in  C  are  duplicated  in  as¬ 
sembly,  then  the  assembly 
versions  have  little  advan¬ 
tage.  To  reason  that  C 
therefore  has  little  HLL 
overhead  is  faulty  logic. 

Other  things  being  equal, 
the  more  complete  toolbox 
is  always  going  to  win  pro¬ 
vided  the  workman  knows 
how  to  use  those  tools. 
That's  why  good,  experi¬ 
enced  assembly  program¬ 
mers  cost  more  than  HLL 
coders. 
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DDJ  Goes 
Online 

On  January  1,  1986,  the 
Electronic  Edition  of  Dr. 
Dobb  s  Journal  will  appear 
on  CompuServe.  Through 
the  Electronic  Edition  DDJ 
will  offer  the  following: 

•  We  will  make  available  in 
our  data  libraries  all  the 
listings  that  appear  in  the 
articles  and  columns  of  Dr. 
Dobbs  Journal  every 
month.  We  will  also  offer 
selections  from  some  of 
our  more  popular  back  is¬ 
sues  and  run  articles  and 
listings  that  have  not  ap¬ 
peared  in  the  magazine. 

•  We  will  maintain  a  dis¬ 
play  area  where  Compu¬ 
Serve  users  can  read  ab¬ 


stracts  of  the  material  in 
the  current  issue.  The  dis¬ 
play  area  will  also  contain 
general  magazine  informa¬ 
tion,  such  as  our  editorial 
calendar,  writers'  guide¬ 
lines,  and  information 
about  advertising  rates. 

•  We  will  compile  compre¬ 
hensive  lists  of  the  com¬ 
mercial  software  develop¬ 
ment  tools  available  to 
microcomputer  program¬ 
mers  and  feature  compara¬ 
tive  reviews  of  products  in 
selected  categories.  We  will 
also  compile  selected  bibli¬ 
ographies  and  give  capsule 
reviews  of  newly  released 
books. 

•  We  will  provide  a  messag¬ 
ing  facility  with  columnists 
and  other  SIC.  members. 

•  We  will  stage  regular  on¬ 


line  teleconferences  with 
authors,  columnists,  and 
other  distinguished  guests. 

•  We  will  take  subscrip¬ 
tions  for  Dr.  Dobb's  Jour¬ 
nal,  the  magazine.  We  will 
also  provide  a  way  for 
readers  to  register  circula¬ 
tion  complaints. 

•  We  will  provide  com¬ 
plete  information  about 
other  DDJ  publications, 
such  as  back  issues,  bound 
volumes,  indexes,  Dr. 
Dobb's  Books,  and  Dr. 
Dobb's  Software.  We  will 
also  take  orders  for  these 
items. 

Please  watch  this  de¬ 
partment  for  further  an¬ 
nouncements  about  con¬ 
ference  schedules  or  the 
availability  of  listings  from 


back  issues.  Also,  if  you 
have  a  request  for  a  listing 
from  a  back  issue,  drop  us 
a  note  or  just  leave  a  mes¬ 
sage  in  the  DDJ  Electronic 
Edition  on  CompuServe.  If 
we  get  enough  requests 
for  a  specific  listing,  we 
will  try  to  make  it  avail¬ 
able. 

Some  of  these  services 
may  not  be  available  Janu¬ 
ary  1.  Most  will  be  free, 
but  some  will  involve  a 
small  charge. 

You  access  the  DDJ  Elec¬ 
tronic  Edition  by  typing  go 
DDJ  at  any  CompuServe 
system  prompt.  We  hope 
you  will  drop  by  and  have 
a  look.  See  you  soon! 
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C  CHEST 


A  Unix-like  Shell  for  MS  DOS 


Last  month  we  presented  a  few 
support  routines,  part  of  a  Unix- 
like  shell  for  MS  DOS.  This  month 
we're  going  to  continue  with  the  shell 
itself,  describing  how  it  works  on  a 
high  level.  Next  month  well  look  at  it 
at  a  lower,  functional  level.  The  code 
itself,  because  it's  so  long,  will  be 
spread  over  the  next  three  months. 

The  shell  described  here  includes 
functions  of  the  Unix  C  shell  that  I 
use  most  often,  such  as  aliases,  his¬ 
tory,  and  command-line  wildcard 
expansion  (more  on  all  this  in  a  mo¬ 
ment).  It  has  batch-file  capability  and 
will  permit  nested  batch-file  execu¬ 
tion  (unlike  MS  DOS,  which  lets  you 
chain  from  one  batch  file  to  another 
but  won’t  let  you  return  to  the  origi¬ 
nal  batch  file). 

It  supports  a  2,048-byte  command 
line  with  interactive  editing.  The 
long  command  line  is  passed  to  an  ex¬ 
ecuted  program  through  an  environ¬ 
ment  variable. 

Using  the  Shell 

Commands  are  entered  from  the 
command  line,  just  as  in  DOS.  (Note 
that  \  is  a  special  character  to  the 
shell,  so  use  slash  (/)  or  \  \  to  separate 
directory  names.)  DOS  wildcard  char¬ 
acters  ( *  and  ?)  are  expanded  before  a 
command  is  executed.  So  if  you  say 
echo  *.c,  the  *.c  will  be  expanded  to 
the  names  of  all  files  having  a  .c  ex¬ 
tension  before  echo  is  invoked.  Ex¬ 
panded  names  are  sorted.  Several 
semicolon-delimited  commands  may 
be  executed  from  a  single  command 
line.  For  example: 

cd  foo  ;  pwd  ;  Is 


by  Allen  Holub 


changes  the  current  directory  to  foo, 
prints  the  full  path  name,  and  then 
prints  a  list  of  the  files  in  the  current 
directory. 

Command-line  editing  (as  de¬ 


scribed  last  month)  is  supported.  To 
summarize: 

Cursors — moves  the  cursor. 

Home — gets  to  the  beginning  of  the 
line. 

End — gets  to  the  end  of  the  line. 
Ctrl-right  arrow  and  Ctrl-left  ar¬ 
row — get  to  the  next  and  the  pre¬ 
vious  word,  respectively. 

'H — is  a  destructive  backspace. 

Del — deletes  the  character  under  the 
cursor.  (Typed  characters  will  be 
inserted  at  the  current  cursor  lo¬ 
cation,  moving  all  characters  to 
the  left  of  the  cursor  over  one 
notch.) 

“X — deletes  the  entire  line. 

Esc — does  the  same  and  aborts. 
Return — causes  the  commands  to  be 
executed. 

There  are  several  built-in  com¬ 
mands: 

alias — creates,  modifies,  or  prints 
aliases  (see  below).  There  are  two 
syntaxes: 

alias 

alias  name  <val> 

The  first  prints  all  currently  de¬ 
fined  aliases,  and  the  second  cre¬ 
ates  an  alias  for  name  with  the  in¬ 
dicated  value.  <Val>  may  be 
anything  on  the  command  line, 
but  you  have  to  escape  (precede 
with  a  \)  any  character  that’s  spe¬ 
cial  to  the  shell  (or  surround 
<val>  with  double  quotes), 
cd — changes  a  directory  or  disk: 
cd  foo — changes  to  the  subdirec¬ 
tory  foo. 


cd.. — changes  to  the  parent 
directory. 

cd  a: — changes  to  the  current  di¬ 
rectory  on  the  a:  drive, 
cd  a:/foo — changes  to  the  /foo  di¬ 
rectory  on  the  a:  drive. 

Cd  must  be  used  to  change  disks, 
although  you  can  alias  a:  to  cd  a:  if 
you  like.  The  shell  checks  to  see  if  a 
disk  is  in  the  indicated  drive  before 
the  drive  is  logged  on. 
exit — terminates  the  shell.  Either  exit 
or  logout  must  be  used  to  leave  the 
outermost  shell.  Subshells  can  be 
terminated  with  a  “C. 

history — prints  the  history  list  (see 
below). 

logout — like  e?cit,  terminates  the 
shell;  however,  the  file  /logout- 
.bat  is  executed  before  exiting, 
pwd — prints  out  the  current  work¬ 
ing  directory  (same  as  chdir  with 
no  arguments  under  DOS), 
rem — does  nothing.  May  take  argu¬ 
ments  (which  will  be  ignored). 
This  command  is  here  only  for  DOS 
compatibility.  The  preferable 
method  for  commenting  a  batch 
file  is  to  start  comment  lines  with  a 
*  in  the  far  left  column.  Note  that 
rem  is  interpreted  as  if  it  were  a 
command;  that  is,  the  line  is  put 
into  the  history  list.  Moreover,  if  a 
line  starts  with  a  rem  but  has  a 
semicolon  on  it  as  well,  text  up  to 
the  semicolon  will  be  ignored  but 
the  semicolon  will  be  treated  nor¬ 
mally  and  any  text  following  the 
semicolon  will  be  treated  as  a  sec¬ 
ond  command  and  executed, 
set — creates,  modifies,  or  prints  a 
shell  variable  (see  below).  Its  syn¬ 
tax  is: 

set 

set  name  [=]  [value] 

The  first  form  prints  all  current 
shell  variables,  and  the  second 
creates  or  modifies  an  existing 
variable.  Both  the  equals  sign  and 
the  value  fields  are  optional.  If 
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you  omit  the  value,  the  alias  will 
expand  to  a  null  string, 
setenv — changes  or  creates  an  envi¬ 
ronment  variable.  Its  syntax  is: 

setenv  name  (  =  ]  [value] 

Both  the  equals  sign  and  the  value 
field  are  optional.  An  example: 

setenv  PROMPT  $p> 

sets  the  prompt  to  the  current  di¬ 
rectory  name  followed  by  >.  This 
command  is  very  similar  to  the 
DOS  set  command.  However, 
setenv  with  no  arguments  doesn’t 
print  the  environment.  Also,  the 
equals  sign  is  optional, 
shift — shifts  all  the  $<num>  argu¬ 
ments  in  a  batch  file  left  one 
notch.  For  example,  if  a  batch  file 
(foo.bat)  consisting  of: 

echo  $0  $1  $2 
shift 

echo  $0  $1  $2 
shift 

echo  $0  $1  $2 
is  executed  with  the  line: 
foo  first  second 

the  following  output  will  be  sent 
to  the  screen: 

echo  first  second 
first  second 
second 

l$0  expands  to  the  file  name.) 
unalias — removes  an  alias.  The  syn¬ 
tax  is  unalias  name. 
unset — removes  a  shell  variable.  The 
syntax  is  unset  name.  The  default 
variables  ( verbose ,  echo,  arg)  can’t 
be  removed. 

History 

The  history  functions  let  you  exam¬ 
ine,  edit,  and  reexecute  previous 
commands.  The  32  most  recently 
typed  commands  are  remembered 
in  a  history  list,  and  each  command 
has  a  history  number  associated  with 
it.  Once  the  history  list  is  full,  the  old¬ 
est  command  is  discarded  every  time 
a  new  command  is  added  to  the  list. 
The  easiest  way  to  see  how  this 
mechanism  works  is  with  an  exam¬ 
ple.  Assume  that  you’ve  typed  the 


following  five  commands: 
vi  prog.c 

cc  —  c  prog.c  >err 
vi  another.c 
cc  —  c  another.c  >err 
link  another + prog, prog, prog, c. 
lib  +  /lib/tools.lib 

As  you  type  the  commands,  they’re 
entered  into  the  history  list,  which 
can  be  examined  by  typing  history. 
The  following  will  be  printed: 

1:  vi  prog.c 
2:  cc  —  c  prog.c  >err 
3:  vi  another.c 
4:  cc  — c  another.c  >err 
5:  link  another+prog,„c.lib+/lib/ 
tools.lib 
6:  history 

Note  that  history  itself  is  also  added 
to  the  history  list.  The  numbers  are 
the  history  numbers  associated  with 
each  command.  A  command  can  be 
executed  again  by  typing  /■*',  where  * 
is  the  history  number.  Typing  15 
causes  the  link  command  to  be  exe¬ 
cuted  again.  12  will  reexecute  the  first 
cc  command.  You  can  also  type 
!<pat>.  In  this  case,  the  history  list 
will  be  searched  backward  for  a 
command  starting  with  <pat>.  So  !l 
or  [link  would  also  redo  the  link.  !cc 
would  be  the  same  as  !4  (because  the 
first  matching  command  is  used).  !! 
will  repeat  the  last  command  you 
typed.  In  the  above  example,  !!,  !6, 
and  !h  will  all  do  the  same  thing. 
Commands  are  added  to  the  history 
list  every  time  they're  executed, 
even  if  a  command  is  an  expansion 
of  a  history  request. 

Several  additional  non-Unix  his¬ 
tory  commands  are  supported. 
!>file  will  write  the  current  history 
list  to  the  specified  file.  If  no  file  is 
given,  /histlist  is  used.  The  comple¬ 
mentary  command  is  l<file,  which 
adds  the  commands  in  file  to  the  cur¬ 
rent  history  list.  The  commands 
aren't  executed,  they’re  just  added  to 
the  list.  Again,  if  file  isn't  specified, 
/histlist  is  used.  Neither  !>  nor  !< 
will  show  up  in  the  history  list  (they 
won’t  use  up  a  history  number, 
either). 

'  may  replace  !;  that  is,  the  com¬ 
mands  ",  ,  and  ~<pat>  may  be 

used  in  place  of  //,  l*,  and  !<pat>. 
The  '  commands  work  just  like  the  / 


commands  except  that  the  line  is 
brought  into  an  edit  buffer  that  you 
can  then  manipulate  in  the  normal 
way  (with  the  cursors,  etc.)  before  ex¬ 
ecuting  it.  Unlike  DOS,  the  command 
line  is  visible  while  you’re  editing  it. 
Note  that  Esc  will  abort  out  of  edit 
mode  without  executing  the  edited 
command  line. 

Environments,  Shell  Variables, 
and  the  Set  Command 

Shell  variables  are  macros.  They  let 
you  associate  a  body  of  text  with  a 
name,  and  when  that  name  is  used, 
the  corresponding  text  is  substituted. 
Shell  variables  are  created  with  the 
set  command  and  deleted  with  the 
unset  command.  They  work  some¬ 
thing  like  Unix  and  DOS  environ¬ 
ments  except  that  they  can’t  be 
passed  to  a  child  process.  Once  a  shell 
variable  is  created,  it  can  be  used 
anywhere  in  a  command.  For  exam¬ 
ple,  you  can  define  a  shell  variable  to 
represent  a  long  directory  spec  with: 

set  HOME  /usr/allen/src/shell 

You  can  then  use  it  on  the  command 
line: 

cd  SHOME 

Cd  $HOME  will  be  expanded  to  cd 
/usr/allen/src/shell  before  the  shell 
executes  the  line.  Note  that  $  must 
precede  all  uses  of  shell  variable 
names  but  must  not  be  in  the  defini¬ 
tions;  %  may  be  used  instead  of  $  if 
you  prefer.  There  are  several  prede¬ 
fined  shell  variables  (which  can't  be 
modified  with  the  set  command). 
These  are: 

$<num> — an  argument  to  a  batch 
file  ($0  is  the  file  name,  $1  the  first 
argument,  etc.). 

$’ — expands  to  all  $<num>  vari¬ 
ables  concatenated  together. 

Sp — expands  to  the  current  path 
name. 

$! — expands  to  the  current  history 
number. 

$s — expands  to  the  current  shell 
level. 

The  top-level  shell  is  0.  If  you  create  a 
shell  within  a  shell,  the  second  one 
will  be  at  level  1.  All  batch  files  are 
executed  in  their  own  shells. 

There  are  three  other  shell  vari¬ 
ables  that  can  be  modified  with  set 
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but  can't  be  expanded  with  $name. 
These  are  echo,  verbose,  and  cmd.  If 
echo  is  set  (with  either  a  set  echo  or  a 
set  echo  =  1),  then  commands  will  be 
echoed  to  standard  output  just  before 
they’re  executed.  The  default  is  echo 
off  (unlike  MS  DOS),  so  you  must  set 
echo  inside  a  batch  file  if  you  want  to 
see  what  the  batch  file  is  doing.  The 
echoed  line  will  show  all  macro  sub¬ 
stitutions  and  all  wildcard  expan¬ 
sions;  however,  it  will  be  truncated 
to  the  127  characters  permitted  by 
DOS.  You  can  use  this  feature  to  see  if 
the  command  line  has  been  truncat¬ 
ed  when  you're  invoking  a  program 
that  doesn’t  know  about  the  CMDLINE 
environment  (see  below). 

Verbose  shows  the  input  as  the 
shell  receives  it  (before  it's  interpret¬ 
ed).  If  cmd  is  set  (the  default),  then  an 
environment  variable  called 
CMDLINE  will  be  created  every  time  a 
file  is  executed.  CMDLINE  holds  the 
entire  2,048-byte  command  line 
(which  can't  be  passed  via  DOS).  If 
cmd  is  cleared,  then  CMDLINE  is  still 
created  but  will  have  no  contents. 
Echo,  verbose,  and  cmd  can  be 
cleared  with  set  <name>  =  0.  Note 
that  setting  echo  or  verbose  has  the 
same  effect  as  specifying  —  x  or  —  v 
on  the  command  line  used  to  invoke 
the  shell. 

Environment  variables  (or  strings) 
are  similar  to  shell  variables  except 
that  they  can  be  passed  to  a  child  pro¬ 
cess  (a  pointer  to  them  is  included  in 
a  child’s  PSP).  Many  compilers  (at 
least  the  Aztec,  Lattice,  and  Micro¬ 
soft)  have  a  getenv(name)  function  in 
their  libraries  that  returns  a  pointer 
to  the  environment  string  corre¬ 
sponding  to  name.  If  you  need  to 
write  your  own  getenvf  ),  a  good  de¬ 
scription  of  the  PSP  can  be  found  in 
The  Peter  Norton  Programmer's 
Guide  to  the  Norton  IBM  PC  (Bellevue, 
Wash.:  Microsoft  Press,  1985),  pp. 
260f. 

Environment  variables  can  be  set 
from  within  the  shell  with  the  setenv 
command.  Unlike  DOS,  they  can  be 
used  on  the  command  line  just  like  a 
shell  variable  (precede  the  name 
with  $  or  %). 

Special  Characters 

*  and  ? — have  the  same  significance 

as  in  MS  DOS.  They  are  expanded 

by  the  shell  to  matching  file 

names.  Expanded  names  are  sort¬ 


ed.  For  example,  echo  *.c  *.obj 
would  print  a  list  of  all  the  .c  files 
in  the  current  directory  (sorted) 
followed  by  all  the  .obj  files  (also 
sorted). 

; — is  used  to  separate  multiple  com¬ 
mands  on  a  single  command  line. 
Cdfoo;pwd  would  change  the  cur¬ 
rent  directory  to  foo  and  then  exe¬ 
cute  the  pwd  command. 

\ — is  used  to  take  away  the  signifi¬ 
cance  of  a  special  character.  For 
example,  V  can  be  used  to  pass  an 
asterisk  to  grep  (the  *  won’t  be  ex¬ 
panded).  \  ;  can  be  used  to  define  a 
multiple  command  alias  (see 
below).  \\  evaluates  to  a  back¬ 
slash.  The  \  will  be  stripped  from 
the  line  before  the  line  is  passed  to 
the  child  process. 

quotes — text  surrounded  by  double 
(")  or  single  (’)  quotes  won't  be 
modified  (wildcard  characters 
aren't  expanded,  semicolons 
aren't  interpreted  as  command 
delimiters,  etc.).  The  quotes  aren't 
removed  unless  the  —q  argument 
is  given  on  the  command  line.  Un¬ 
like  Unix,  there's  no  distinction 
made  between  single  and  double 
quotes. 

* — when  found  in  the  far  left  col¬ 
umn,  signifies  a  comment.  The  re¬ 
mainder  of  the  line  is  ignored,  and 
the  line  isn't  put  into  the  history 
list. 

Aliases 

Aliases  are  another  sort  of  shell- 
maintained  macro.  Unlike  shell  vari¬ 
ables,  a  $  is  not  needed  to  expand  the 
name;  rather  the  alias  is  expanded  if 
its  name  is  found  as  either  the  first 
word  on  a  line  or  the  first  word  fol¬ 
lowing  a  semicolon  on  a  multiple- 
command  line.  Aliases  have  two 
uses:  They  can  be  used  to  change  the 
name  of  a  command  and  they  can  be 
used  in  place  of  batch  files.  Aliases 
are  created  with  the  alias  command. 
Some  examples:  If  you  have  a  pro¬ 
gram  called  Is  that  prints  the  current 
directory  but  you  also  want  to  be 
able  to  type  dir  and  get  a  directory 
listing,  you  can  define  an  alias  for  dir 
as  follows: 

alias  dir  Is 

Thereafter,  when  the  shell  finds 
dir  as  the  first  word  on  a  line,  it  will 
substitute  the  string  Is  for  the  string 


dir,  and  the  program  Is  will  be  exe¬ 
cuted.  Only  the  first  word  of  a  com¬ 
mand  is  modified  so  dir  foo  bar  rat 
will  be  changed  to  Is  foo  bar  rat. 
Aliases  must  be  either  the  first  word 
on  a  line  or  the  first  word  following 
the  semicolon  when  there  are  sever¬ 
al  commands  on  one  line. 

Aliases  can  also  be  used  in  place  of 
batch  files,  provided  that  no  argu¬ 
ments  need  to  be  expanded.  Because 
aliases  are  memory  resident,  they 
will  execute  much  faster  than  a 
batch  file.  Similarly,  an  alias  doesn't 
execute  under  its  own  shell,  as  does  a 
batch  file,  so  much  less  core  is  need¬ 
ed  to  execute  an  alias  than  is  needed 
to  execute  a  batch  file.  A  simple  alias 
that  is  similar  to  a  batch  file  is: 

alias  shell  cd  /src/util/shell 
Now  you  can  type  the  single  word 
shell,  which  the  shell  will  expand  to 
cd  /src/util/shell  and  then  execute  to 
move  to  the  indicated  directory;  how¬ 
ever,  you  can't  expand  arguments. 
The  portion  of  the  command  line  that 
follows  the  alias  name  will  be  concat¬ 
enated  to  the  end  of  the  expanded 
alias.  Let's  look  at  an  example:  Poly¬ 
make  lets  you  specify  a  default  rules 
file  on  the  command  line  with  a  —  B 
option,  but  you  often  have  to  make  a 
target  name  as  well.  By  defining  the 
alias  m  with: 

alias  m  make  —  B  /lib/ 

builtins.mak 

you  can  then  type  m  foo.e^e  and  the 
shell  will  expand  it  to: 

make  —  B  /lib/builtins.mak 

foo.exe 

Because  you  can  have  multiple 
semicolon-delimited  commands  on 
one  line,  you  can  define  an  alias  that 
will  expand  to  several  commands. 
For  example: 

alias  m  rm  err  \;  make  —  B  /lib/ 

builtins.mak 

will  expand  to 

rm  err  ;  make  —  B  /lib/ 

builtins.mak 

thereby  both  removing  the  file  err 
and  executing  make.  Note  that  you 
must  escape  the  semicolon  (with  a  \) 
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in  the  alias  definition  so  that  the  shell 
won’t  intercept  it.  (You  could  also 
surround  the  definition  with  quotes.) 

Aliases  may  use  shell  variables. 
Two  such  aliases  are: 

alias  here  set  here  =  \$p 
alias  there  cd  \$here 

Here  will  set  the  shell  variable  here  to 
the  current  directory.  There  will  put 
you  in  the  directory  remembered 
with  a  previous  here  invocation.  Note 
that  $  has  to  be  escaped  to  prevent 
the  shell  from  expanding  it  when  the 
alias  is  defined. 

A  caveat  about  aliases:  Aliases  de¬ 
fined  in  terms  of  other  aliases  won't 
work.  For  example: 

alias  foo  echo  foo 
alias  bar  echo  bar 
alias  foobar  foo;bar 

won  t  work  (foobar  will  expand  to 
foo;  echo  bar).  However,  the  com¬ 
mand  line  foo;bar  will  work.  Also 
note  that  commands  are  added  to  the 
history  list  before  aliases  are 
expanded. 

Environments  and  Files 

The  default  command  line  prompt  is 
l$s,$!]  (which  prints  the  current  shell 
level  followed  by  the  current  history 
number).  You  can  specify  a  different 
prompt  with  the  PROMPT  environ¬ 
ment  variable  (use  either  the  DOS  set 
or  the  shell’s  setenv  command).  Any 
ASCII  character  may  be  used,  and  any 
of  the  $  arguments  will  be  expanded 
before  the  prompt  is  printed.  For 
example: 

setenv  prompt  $p  — > 

will  change  the  prompt  to  the  cur¬ 
rent  directory  name  followed  by  — 
and  >.  The  prompt  can  be  changed 
at  any  time  (it  doesn’t  have  to  be  set 
when  the  shell  boots).  The  SWITCHAR 
environment  variable  tells  the  shell 
what  character  signifies  a  command¬ 
line  switch  when  it's  the  first  charac¬ 
ter  in  a  command-line  argument  (the 
default  is  — ).  Because  environments 
are  inherited  by  the  child  process, 
SWITCHAR  is  also  available  to  a  pro¬ 
gram  if  it  chooses  to  use  it. 

The  CMDLINE  environment  holds 
the  complete,  2,048-byte  command 
line  (which  can't  be  passed  via  DOS).  It 


is  changed  every  time  the  shell  exe¬ 
cutes  a  command.  Note  that  the  com¬ 
mand  line  (truncated  to  127  charac¬ 
ters)  is  also  passed  to  a  child  process 
in  the  normal  way  (via  the  DOS  com¬ 
mand  line  buffer  at  offset  0x80  from 
the  child's  initial  code  segment). 
When  the  shell  spawns  a  subshell  to 
execute  a  batch  file,  it  uses  CMDLINE. 

The  SHLEV  environment  is  set  to 
the  current  shell  level.  The  outer¬ 
most  shell  is  at  level  0.  All  shells  cre¬ 
ated  from  within  another  shell  (in¬ 
cluding  those  used  to  execute  batch 
files)  will  have  higher  numbers,  de¬ 
pending  on  the  level  of  nesting. 

Several  files  are  used  by  the  shell. 
If  it  exists,  the  file  /shrc.bat  is  execut¬ 
ed  (in  a  manner  analogous  to  autoex¬ 
ec.bat)  every  time  a  shell  is  created. 
Because  batch  files  are  executed  in 
their  own  shells,  /shrc.bat  will  be  ex¬ 
ecuted  every  time  a  batch  file  is  exe¬ 
cuted.  A  second  file  /login.bat  is  exe¬ 
cuted  only  once,  when  the 
lowest-level  (level  0)  interactive  shell 
is  created.  Shrc.bat  is  executed  before 
login.bat,  and  both  files  are  executed 
before  the  environment  is  examined. 
My  own  login  file  is  shown  in  Table 
1,  at  right.  My  logout  file  is  simply  !> 
and  lets  me  leave  the  shell  without 
losing  the  current  history  list.  Note 
that  !<  in  login.bat  lets  me  reenter 
the  shell  without  losing  the  list.  You 
could  also  use  !<  (without  the  !»  to 
read  in  a  list  of  commonly  used  com¬ 
mands  when  the  shell  boots. 

Shell  Invocation  Syntax 

There  are  several  ways  to  get  into  the 
shell  from  the  command  line.  The 
easiest  way  is  to  type  sh  (with  no  ar¬ 
guments),  putting  you  into  interactive 
mode.  You  can’t  get  out  of  the  lowest- 
level  interactive  shell  with  a  "C.  Use 
either  exit  or  logout. 

sh  —  c  string — invokes  the  shell  in 
nonresident  mode.  It  will  execute 
the  command  contained  in 
<string>  as  if  it  had  been  entered 
from  the  command  line  and  then 
terminate. 

sh  filename  args  .  .  .  — executes  a 
batch  file.  $0,  if  found  inside  the 
batch  file,  will  be  expanded  to  the 
file  name.  The  arguments  can  be 
fetched  with  $1,  $2,  etc.  %  can  be 
used  instead  of  $  if  you  like. 

Four  other  command-line  switch¬ 


es  are  available: 

—  i — puts  the  shell  into  interactive 

mode  even  if  arguments  are  listed 
on  the  command  line.  Normally  if 
command-line  arguments  are 
present  and  —  c  isn't  specified,  the 
shell  will  try  to  execute  a  batch 
file,  sh  —i  arg . . .  arg  will  create 
an  interactive  shell,  putting  the  ar¬ 
guments  into  $1,  $2,  etc.  $0  will 
hold  the  string  —  i. 

—  q — causes  quotes  to  be  stripped 
from  commands  before  they're 
passed  to  a  child  process.  The 
quotes  will  still  protect  wildcard 
characters,  etc.,  from  expansion. 

—  v — verbose  mode,  commands  are 
echoed  to  stderr  as  they’re  read 
by  the  shell.  This  is  the  same  as  a 
set  verbose  command. 

—  x — commands  are  echoed  to  stderr 
just  before  they’re  executed.  All  $ 
arguments  and  wildcard  charac¬ 
ters  will  have  been  expanded  at 
this  point.  This  is  the  same  as  a  set 
echo  command. 

Redirection 

The  shell  itself  doesn't  support  redi¬ 
rection;  however,  because  com¬ 
mand. com  is  still  resident,  redirec¬ 
tion  is  available  if  you  need  it.  There 
are  two  ways  to  use  command.com 
for  redirection.  A  nonresident  shell 
can  be  invoked  from  DOS  with  a  line 
such  as: 

sh  —  c  grep  pattern  *.c  >foo 

Grep  will  be  executed,  and  the  shell 
will  expand  the  *.c  to  the  names  of 
all  files  in  the  current  directory  hav¬ 
ing  a  .c  extension  before  grep  is  in¬ 
voked.  Grep' s  output  will  be  redirect¬ 
ed  to  foo  in  the  normal  way.  Because 
this  command  is  executed  from  MS 
DOS  and  not  from  the  shell,  it  won’t 
be  added  to  the  history  list. 

The  second  method  also  lets  you 
enter  redirected  commands  into  the 
history  list.  From  inside  the  shell, 
type: 

command  /c  grep  pattern  *.c  >foo 

The  /c  argument  to  command.com 
works  like  the  —  c  argument  to  sh,  so 
it  will  execute  the  following  string  as 
if  it  had  been  typed.  The  *.c  will 
again  be  expanded  by  the  shell  be¬ 
fore  command.com  is  executed,  but 
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setenv  PR0MPT=[\$s:\$i] 

alias  a  alias 

a  h  history 

a  book 

cd  /text/book 

a  ddj 

cd  /text/ddj 

a  here 

set  here  =  \$p 

a  sclass 

cd  /src/ciass 

a  there 

cd  \$here 

a  tmac 

cd  /lib/tmac 

a  tools 

cd  /src/tools 

a  type 

cat 

a  m 

“rm  err;  make-B  builtins.mak” 

!< 

Table  1:  A  login.bat  file 

the  .>  will  be  interpreted  by  com¬ 
mand. com  (which  will  put  the  out¬ 
put  into  foo).  Be  careful  here  of  com¬ 
mand-line  truncation.  Because 
command.com  doesn't  know  about 
the  CMDLINE  environment,  it  has  no 
way  to  get  to  the  extended  command 
line,  so  it  will  work  on  only  the  first 
127  characters. 

Support  Routines 

In  order  to  minimize  the  size  of  the 
shell,  I've  tried  not  to  build  in  com¬ 


mands  that  aren’t  essential.  I’ve 
found  the  following  programs  to  be 
useful. 

cat.c — prints  (concatenates)  files  to 
stdout. 

cp.c — copies  a  file  to  another  file  or 
disk.  Copies  a  group  of  files  to  an¬ 
other  directory  or  disk, 
echo.c — echoes  command  line  to 
stdout. 

grep.c — searches  for  pattern  in  file, 
ls.c — lists  a  directory. 


mkdir.c — creates  a  directory, 
mv.c — renames  a  file  or  moves  a 
group  of  files  to  another 
directory. 

printenv.c — prints  the  current 
environment. 

rm.c — removes  a  file  or  group  of 
files. 

rmdir.c — removes  a  directory. 

Availability 

This  column  is  part  of  a  four-part  se¬ 
ries  describing  the  entire  shell.  A  re¬ 
print  of  all  four  parts  along  with  a 
disk  containing  the  listings  is  avail¬ 
able  for  $29.95  from  Dr.  Dobb's  Jour¬ 
nal,  2464  Embarcadero  Way,  Palo 
Alto,  CA  94303.  Please  direct  inquiries 
to  the  The  Shell.  Prepayment  is 
required.  nuj 

(Listing  begins  on  page  84) 
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ARTICLES 


PL/  68K 


68000 

Assembly  Language 


by  Edward  K.  Ream 


One  day  not 
long  ago,  I  be¬ 
came  em¬ 
broiled  in  an  old  de¬ 
bate  with  another 
programmer  named 
Charlie. .  . . 

"The  programming 
team  I  manage  is  about 
to  start  a  big  project,”  I 
said,  "and  1  must  de¬ 
cide  which  language 
to  use.” 

“Really?  Which  lan¬ 
guages  are  you  considering?” 

"C  and  68000  assembly  language.  The  product  will 
have  strong  competition,  and  great  performance  is  cru¬ 
cial,  so  it’s  reasonable  to  consider  assembly  language.  On 
the  other  hand,  C  is  so  much  easier  to  use.” 

"Why  don't  you  program  in  C  and  recode  in  assembly 
language  as  needed?”  Charlie  asked. 

"Of  course  I’ve  considered  that.  It  might  work  as  far  as 
execution  speed  is  concerned,  although  I’m  not  sure.  C 
doesn't  let  you  allocate  registers  globally,  and  that's  a  big 
handicap.  Speed  is  not  the  only  problem,  though.  The 
code  must  be  compact,  but  our  C  compiler  produces  code 
that  is  50  percent  larger  than  assembly  language.  No, 
there’s  no  doubt  about  it — eventually  the  program  will 
have  to  be  written  in  assembly." 


Copyright  ®  1 985  by  Edward  K.  Hearn,  1850  Summit  Ave., 
Madison,  Wl  53705;  (608)  231-2952 


"Do  the  initial  proto¬ 
typing  in  C.  That's  the 
right  way,”  Charlie 
persisted.  "When  the 
program  is  finished, 
recoding  in  assembly 
language  will  be  much 
easier." 

"Hmmm.  I'm  not 
convinced.  Recoding  is 
going  to  be  expensive; 
we'll  end  up  debug¬ 
ging  the  whole  pro¬ 
gram  twice.  There 
might  even  be  pressure  from  higher  management  not  to 
recode  and  come  out  with  an  inferior  product.” 

Charlie  just  snorted  and  walked  away,  muttering 
something  about  assembly  language  being  a  throwback 
to  the  Dark  Ages. 

Writing  in  Both  C  and  Assembly 

Fortunately,  my  friend  John  overheard  this  conversa¬ 
tion.  John  and  I  have  worked  together  for  15  years,  and 
we  enjoy  discussing  problems  that  come  up  on  the  job. 
John  laughed,  "Charlie  is  more  interested  in  being  right 
about  C  than  in  solving  your  problem.” 

"You  sound  more  sympathetic.” 

"Well,  your  choice  is  crucial.  Which  language  you  use 
determines,  to  a  large  extent,  how  your  project  will  turn 
out.” 

"Yes.  What  bothers  me  most  is  that  I’ve  got  to  choose 
now,  but  I  won  t  know  until  the  project  is  almost  over 
whether  the  choice  was  correct.” 


I  asked  myself,  suppose  the 
program  produced  by  the  C 
compiler  and  the  program 
produced  by  the  assembler  were 
semantically  equivalent?  Suddenly 
PL/68K  became  not  just  another 
assembly  language  but  a  new 
way  of  using  C. 
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"I  think  I  know  a  way  around  this  dilemma — it’s  a  lan¬ 
guage  I  invented  called  PL/68K.” 

"John,  my  only  options  are  C  and  68000  assembly  lan¬ 
guage." 

"Don’t  be  fooled  by  the  name.  PL/68K  isn’t  really  an 
independent  language  but  a  way  of  using  C  to  do  assem¬ 
bly-language  programming.’’ 

“John,  you  are  not  making  sense!” 

"Let  me  explain.  You  can  think  of  PL/68K  as  being  ei¬ 
ther  C  or  assembly  language — either/or.  But  in  fact,  you 
can  run  a  program  written  in  PL/68K  through  both  the 
PL/68K  assembler  and  any  standard  C  compiler.  PL/68K 
is  both  C  and  assembly  language  at  the  same  time." 

"Wait  a  minute.  You  are  going  much  too  fast,”  1  said. 
"First  of  all,  you  can't  possibly  compile  an  assembly-lan¬ 
guage  program  with  a  C  compiler!  Assembly  language 
doesn’t  look  anything  like  C — the  C  compiler  will  spit  out 
a  thousand  error  messages!” 

"PL/68K  doesn't  resemble  ‘traditional’  assembly  lan¬ 
guage.  Forget  what  assembly  language  usually  looks  like 
and  ask  yourself,  ’What  are  the  characteristics  of  assem¬ 
bly  language?'  ” 

"Go  on,”  I  replied.  "You  tell  me.” 

"First,  assembly  language  allows  full  access  to  all  ma¬ 
chine  resources — all  registers,  all  locations  in  memory 
(including  the  run-time  stack),  all  I/O  ports,  all  privilege 
modes,  and  all  machine  instructions.  Second,  there  is  a 
one-for-one  correspondence  between  the  source  code 
you  write  and  the  object  code  produced  by  the  assem¬ 
bler.  You  always  know  what  code  a  particular  assembly- 
language  construct  generates;  assemblers  neither  rear¬ 
range  code  nor  ‘optimize’  code  away  nor  add  anything 
extraneous.  Assemblers  are  very  literal-minded.  Thus,  as¬ 
sembly  language  ensures  zero  time  and  space  overhead.” 

"You’re  saying  that  assembly  language  gives  you  com¬ 
plete  control  over  the  machine,  without  a  compiler  get¬ 
ting  in  the  way." 

"Exactly.  Now,  suppose  we  say  assembly  language  is 
any  language  that  (1)  allows  complete  access  to  all  ma¬ 
chine  resources,  (2)  provides  a  clear  correspondence  be¬ 
tween  source  code  and  object  code,  and  (3)  imposes  zero 
time  or  space  overhead.  ” 

Semantic  Identity 

"Hmmm,”  I  mused.  "This  definition  doesn't  say  what  as¬ 
sembly  language  looks  like.  It  could  even  look  like  C.  But  1 
still  don’t  understand.  If  you  run  a  PL/68K  program 
through  an  assembler,  you  will  get  one  program.  If  you 
run  the  same  source  through  a  C  compiler,  you  will  get  a 
second  program.  The  two  programs  are  not  going  to  do 
the  same  things — similar  things,  maybe,  but  not  the  same 
things.  The  fact  that  the  source  code  is  the  same  doesn’t 
matter.  To  put  it  another  way  given  a  result  desired  from 
a  specific  PL/68K  program,  we  would  still  have  to  choose 
between  assembling  the  program  with  the  PL/68K  as¬ 
sembler  or  compiling  it  with  a  C  compiler.” 

"You’ve  stated  the  problem  very  well,”  John  said,  “but 
I  have  discovered  that  it’s  possible  to  design  PL/68K  so 
that  the  program  produced  by  the  PL/68K  assembler  will 
work  in  the  same  way  as  the  program  produced  by  the  C 
compiler.” 

"That  sounds  impossible!” 


"I  don't  think  so.  Let’s  turn  the  problem  around.  Sup¬ 
pose  we  design  PL/68K  according  to  what  might  be 
called  'the  principle  of  semantic  equivalence.’  This  prin¬ 
ciple  states  that  a  program,  when  assembled  by  the  PL/ 
68K  assembler,  must  work  in  the  same  way  as  when  it  is 
compiled  by  a  standard  C  compiler.  Now  let's  ask,  ‘What 
needs  to  be  eliminated  from  PL/68K  to  guarantee  seman¬ 
tic  equivalence?’  ”  (See  Figure  1,  page  40.) 

"Tell  me,”  I  said,  “how  much  of  C  is  left  after  the  prin¬ 
ciple  of  semantic  equivalence  takes  its  toll?” 

“Surprisingly  almost  all  of  it.  The  preprocessor  is  iden¬ 
tical  to  the  C  preprocessor.  All  declarations  and  structure 
statements  are  present.  Functions  do  not  return  values 
but  otherwise  are  unchanged,  as  are  Boolean  and  rela¬ 
tional  operators  and  expressions.  The  biggest  restriction 
is  that  arithmetic  operators  and  expressions  must  be  se¬ 
verely  curtailed  in  order  to  make  PL/68K  expressions 
mean  the  same  thing  as  C  expressions.” 

"You  keep  talking  about  PL/68K  being  assembly  lan¬ 
guage,”  I  said.  "How  is  it  possible  to  produce  code  the 
quality  of  assembly  language  from  a  language  that  is  a 
subset  of  C?” 

"I  haven't  shown  you  the  whole  language  yet.  Two 
other  rules  guide  the  design  of  PL/68K.  These  rules,  to¬ 
gether  with  the  principle  of  semantic  equivalence,  deter¬ 
mine  the  form  and  content  of  PL/68K.  The  two  rules  are 
the  code  selection  rule' — the  assembler  for  PL/68K  does 
no  code  selection,  and  all  arithmetic  operations  in  PL/ 
68K  correspond  to  unique  68000  machine  instructions; 
and  ‘the  register  allocation  rule' — the  assembler  for  PL/ 
68K  does  no  register  allocation,  and  all  operations  in  an 
assignment  statement  are  performed  in  the  location  spec¬ 
ified  by  the  left  side  of  that  assignment  statement. 

"In  short,  these  rules  say  that  an  assembler  for  PL/68K 
never  has  to  make  any  significant  decisions.  Because  the 
PL/68K  assembler  knows  how  to  select  code  and  allocate 
registers,  it  will  never  need  any  of  the  fancy  techniques 
used  by  optimizing  compilers,  but  it  will  be  able  to  pro¬ 
duce  code  that  is  just  as  good  as  assembly  language. 

"I  like  to  think  of  the  assembler  for  PL/68K  as  a  simple 
compiler,  consisting  of  a  parser  and  straightforward 
code  generator  and  possibly  a  peephole  optimizer.  The 
whole  job  should  take  about  a  year  to  complete  rather 
than  the  10  to  20  programmer  years  for  a  typical  optimiz¬ 
ing  compiler.  Using  compiler  technology  to  write  an  as¬ 
sembler  was  the  initial  idea  that  started  me  thinking 
about  PL/68K.” 

Now  that  I’ve  presented  the  general  ideas  behind  PL/ 
68K,  I’ll  drop  this  dialogue  format  and  these  fictional 
characters  and  look  at  the  details  of  the  language. 

Specifying  Registers 

Because  PL/68K  is  both  assembly  language  and  C,  some 
way  must  be  found  to  deal  with  assembly-language  con¬ 
structs  such  as  registers,  address  modes,  and  individual 
machine  instructions,  while  at  the  same  time  remaining 
compatible  with  C.  These  assembly-language  constructs 
are  represented  by  reserved  words,  shown  in  Table  1, 
page  29. 

As  for  the  registers  of  the  68000,  do  through  d7  stand 
for  the  data  registers,  aO  through  a7  for  the  address  regis¬ 
ters,  pc  for  the  program  counter,  ssr  for  the  status  regis- 
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ter,  and  ccr  for  the  condition  code  register,  which  is  the 
lower  byte  of  the  ssr. 

Standard  aliases  are  also  defined.  Register  a7  can  also 
be  called  sp,  ssp,  or  usp  to  denote  the  stack  pointer  (or 
system  stack  pointer  or  user  stack  pointer).  The  reserved 
words  rO  through  r7  are  synonyms  for  do  through  d7, 
and  the  names  r8  through  rl5  are  synonyms  for  registers 
aO  through  a7. 

All  registers  on  the  68000  are  32  bits  long  (except  the 
status  registers),  but  not  every  instruction  uses  all  32  bits 
of  a  register.  Besides  long  (32-bit)  operations,  byte-length 
(8-bit)  and  word-length  (16-bit)  operations  are  permitted 
on  data  registers,  and  word-length  operations  are  permit¬ 
ted  on  address  registers.  To  represent  the  length  of  an 
operation,  the  name  of  any  data  register  can  be  followed 
by  a  b  to  denote  byte  length  or  a  w  to  denote  word  length. 
Thus,  dO  stands  for  the  long  register  do,  dOw  stands  for 
the  word-length  register  dO,  and  dob  stands  for  the  byte- 
length  register  dO.  Address  registers  are  treated  in  a  simi¬ 
lar  manner,  except  that  byte-length  operations  are  not 
permitted. 

Address  Modes 

The  68000  has  12  different  address  modes,  or  means  of 
accessing  operands.  (See  Table  2,  page  29.)  The  address 
modes  are  represented  in  PL/68K  by  five  of  C’s  operators, 
namely  &,  *,  +  +, - ,  and  — >. 

Let's  look,  for  example,  at  the  Address  Register  Indirect 
with  Postincrement  address  mode.  (It’s  a  lot  easier  to  use 
than  to  say.)  This  mode  uses  the  contents  of  an  address 
register  as  the  address  of  an  operand.  After  the  operation 
is  performed,  the  address  register  is  incremented  by  1,  2, 
or  4,  depending  on  the  size  of  the  operation.  In  traditional 
assembly  language,  that  mode  applied  to  address  register 
aO  would  be  written  as  (a0)+.  In  PL/68K,  that  address 
mode  is  represented  by  *a0+  +.  For  example,  you  would 
write  d0b=*a0++;  in  PL/68K  instead  of  move.b 
(a0)+,d0b.  Constructions  such  as  *  +  +a0  are  not  allowed 
because  of  the  code  selection  rule.  The  68000  has  no  ad¬ 
dressing  mode  of  the  form  +(a0),  so  *  +  +a0  is  not  part  of 
PL/68K. 

The  word  primitive  denotes  what  is  called  an  effective 
address  in  machine-language  terms.  A  primitive  de¬ 
scribes  an  operand,  which  may  be  in  a  register,  on  the 
run-time  stack,  or  in  static  memory.  In  PL/68K,  the  valid 
forms  of  primitives  are  determined  by  the  address  modes 
I've  just  discussed. 

Declarations 

While  1  am  talking  about  operands,  I'll  say  a  few  words 
about  how  those  operands  are  declared.  Declarations  in 
PL/68K  are  just  the  same  as  in  C,  except  that  functions  do 
not  have  types.  If  you  think  about  it  for  a  moment,  this 
means  that  PL/68K  declarations  have  no  parentheses. 
Declarations  can  never  become  unreadable  as  they  can  in 
full  C. 

In  effect,  declarations  produce  DC  (define  constant)  and 
DS  (define  storage)  pseudo-operations.  (See  Table  3,  page 
29.)  Although  declarations  produce  no  executable  code, 
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they  determine  what  code  gets  produced  by  arithmetic 
operators.  For  instance,  if  a  is  an  integer,  the  assignment 
statement  a  ’=  b,  which  multiplies  a  by  b,  generates  a 
MULS  (signed  multiply)  machine  instruction,  but  if  a  is  an 
unsigned  integer  or  pointer,  the  assignment  statement 
generates  a  MULU  (unsigned  multiply)  instruction. 

As  another  example,  the  assignment  a  +  =  b,  which 
adds  b  to  a,  generates  an  ADD.B  (byte  length  add)  instruc¬ 
tion  if  a  is  a  char,  but  it  generates  an  ADD.W  (word  length 
add)  instruction  if  a  is  an  int  and  generates  an  ADD.L  (word 
length  add)  instruction  if  a  is  a  long  word  or  a  pointer. 

Assembly-Language  Instructions  and 
Pseudo-operations 

Reserved  identifiers  also  stand  for  68000  machine-lan¬ 
guage  instructions  and  pseudo-operations.  A  library  of 
pseudofunctions  must  be  linked  with  a  PL/68K  program 
when  it  is  translated  with  a  C  compiler.  This  library, 
called  the  ops  library,  contains  declarations  and  func¬ 
tions  that  allow  C  programs  to  simulate  the  effect  of 
68000  machine  instructions  and  pseudo-operations.  (See 
Table  4,  page  32.) 

The  pseudofunction  btst(  ),  for  example,  simulates  the 
BTST  (bit  test)  machine  instruction.  In  PL/68K,  you  would 
write  btst(l,d0b);  in  those  places  where  you  would  write 
btst.b  #l,d0  in  traditional  68000  assembly  language. 

Other  pseudofunctions  allow  PL/68K  programs  to  re¬ 
fer  to  assembly-language  pseudo-operations.  The  PL/68K 
assembler  translates  the  org(  ),  even (  ),  bss( ),  text!  J,  and 
data(  )  pseudofunctions  to  the  ORG,  EVEN,  BSS,  TEXT,  and 
DATA  pseudo-operations.  Similarly  the  PL/68K  assem¬ 
bler  translates  the  dcb(  ),  dcw(  ),  dcl( ),  dsb( ),  dsw(  ),  and 
dsl( )  pseudofunctions  to  the  DC.B,  DC.W,  DC.L,  DS.B,  DS.W, 
and  DS  L  pseudo-operations.  None  of  these  pseudofunc¬ 
tions  has  any  effect  when  a  C  compiler  translates  a  PL/ 
68K  program.  In  other  words,  the  corresponding  pseudo¬ 
functions  in  the  ops  library  do  nothing. 

You  may  be  wondering  why  I  keep  calling  these  rou¬ 
tines  pseudofunctions.  After  all,  they  are  perfectly  good 
functions  when  compiling  a  PL/68K  program  with  a  C 
compiler.  When  you  turn  the  program  through  the  PL/ 
68K  assembler,  though,  it  translates  pseudofunctions  di¬ 
rectly  into  68000  machine  instructions  or  pseudo-opera¬ 
tions. 

Expressions  and  Assignment  Statements 

I've  covered  the  components  of  low-level  assembly  lan¬ 
guage — registers,  address  modes  and  effective  addresses, 
machine  instructions,  and  pseudo-ops.  Now  let's  see  how 
you  put  these  components  together  to  make  expressions 
and  assignment  statements. 

Expressions  are  quite  restricted;  they  are  just  primi¬ 
tives  or  parenthesized  constant  expressions.  Assignments 
are  restricted  to  the  forms  primitive  aop  expression  or 
primitive  aop  (  assignment  ),  where  aop  stands  for  one  of 
the  assignment  operators  of  the  C  language,  namely,  =, 
+  =,  —=,  *=,  /=,  &=,  !=,  “=,  >>  =  ,  and  <  <  — .  The 
regular  arithmetic  operators  in  C,  namely,  +,  — ,  *,/,&,!, 
",  >>,  and  <<  are  allowed  only  in  constant  expres¬ 
sions,  which  must  be  parenthesized. 

You  are  probably  wondering  why  all  these  restrictions 
exist.  There's  a  short  answer  and  a  long  answer.  The 


Data  registers 

dO,  dOb,  dOw _ _  d7,  d7b,  d7w 

rO,  rOb,  rOw, . . . ,  r7,  r7b,  r7w 

Address  registers 

aO,  aOw, . . . ,  a7,  a7w 

r8,  r8w,  .  .  . ,  r15,  r15w 

sp,  spw,  usp,  uspw,  ssp,  sspw 

Status  registers 

ssr,  ccr 

Program  counter 

pc 


Table  1:  Reserved  words  corresponding  to  68000 
registers 


PL/68K 

Traditional  assembly  language 

123 

#123 

abc 

abc 

&abc 

#abc 

*(&abc+1) 

abc+#1 

abc.25 

abc  +  #25 

*(0x80) 

$80 

aO 

aO.I 

aOw 

aO.w 

dO 

dO.I 

dOw 

dO.w 

dOb 

dO.b 

*a0 

(aO) 

*a0+  + 

(aO)-f- 

* - aO 

-(aO) 

aO  —  5 

#5(a0) 

aO  —  dO 

#0(a0,  dO.I) 

aO  —  (dOw) 

#0(a0,  dO.w) 

aO  — (dO+5) 

#5(a0,  dO.I) 

aO  -*  (dOw+5) 

#5(a0,  dO.w) 

pc  -*  5 

#5(pc) 

pc  —  dO 

#0(pc,  dO.I) 

pc  —  (dOw) 

#0(pc,  dO.w) 

pc  —  (dO  +  5) 

#5(pc,  dO.I) 

pc  —  (dOw  +  5) 

#0(pc,  dO.w) 

Table  2:  Representing  the  address  inodes  of  the  68000 

Declaration 

Code  Generated 

char  abc; 

abc:  ds.b  1; 

char  cl  =  ’c’; 

cl:  dc.b  ’c’; 

char  *  cp; 

cp:  ds.l  1; 

long  xyz; 

xyz:  ds.l  1; 

char  a[]  =  “abc”;  a:  dc.b  ’abc’,0; 

int  a2  [25]; 

a2:  ds.w  25; 

struct  si  { 

long  si; 

char 

*s2; 

int 

s3; 

}; 

no  code  generated. 

struct  si  s2  [25]; 

s2:  ds.b  250; 

union  ul  { 

int 

ui; 

char 

uc; 

long  ul; 

}; 

ul:  ds.b  4; 

Table  3:  Code  generated  for  declarations 
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Pseudofunctions  corresponding  to  68000  machine  instructions 

abed,  add,  adda,  addi,  addq,  addx,  and,  andi,  asl,  asr 
bcc,  bes,  bchg,  beq,  bge,  bgt,  bhi,  ble,  bis,  bit,  bmi,  bne,  bpl, 
bvc,  bvs 

bchg,  bclr,  bra,  bset,  bsr,  btst 
chk,  clr,  emp,  empa,  empi,  empm, 

dbcc,  dbes,  dbeq,  dbf,  dbge,  dbgt,  dbhi,  dble,  dbls,  dblt,  dbmi, 
dbne,  dbpl,  dbt,  dbvc,  dbvs,  divs,  divu 
eor,  eori,  exg,  ext,  jmp,  jsr,  lea,  link,  Isl,  Isr 
move,  movea,  movem,  movep,  moveq,  muls,  mulu 
nbed,  neg,  negx,  nop,  not,  or,  ori,  pea 
reset,  rol,  ror,  roxl,  roxr,  rte,  rtr,  rts 

see,  scs,  seq,  sf,  sge,  sgt,  shi,  sle,  sis,  sit,  smi,  sne,  spi,  st,  sve, 
svs 

sbed,  stop,  sub,  suba,  subi,  subq,  subx,  swap 
tas,  trap,  trapv,  tst,  unlk 

Pseudo  functions  corresponding  to  assembly-language  pseudo 
operations 

deb,  dew,  del,  dsb,  dsw,  dsl 
org,  data,  text,  bss,  even 


Table  4:  Pseudofunctions 


Operator 

Generated  code 

a  +  =  b 

add 

b,  a 

(or  adda  or  addi  or  addq) 

a—  =  b 

sub 

b,  a 

(or  suba  or  subi  or  subq) 

a  *=  b 

muls 

b,  a 

(or  mulu) 

a  /=  b 

divs 

b,  a 

(or  divu) 

a  %=  b 

divs 

b,  a 

(or  divu) 

swap 

a 

a  >>  =  b 

asr 

b,  a 

(or  ror) 

a  <<=  b 

asl 

b,  a 

(or  rol) 

a  &=  b 

and 

b,  a 

(or  andi) 

al=  b 

or 

b,  a 

(or  ori) 

a  '  =  b 

eor 

b,  a 

(or  eori) 

a  +  + 

addq 

#1,  a 

(or  addi) 

a - 

subq 

#1,  a 

(or  subi) 

Table  5:  Code  generated  by  arithmetic  operators 


Boolean 

Generated  code 

if(Z) 

bnz 

false 

if  (a) 

tst 

a  (or  empa) 

bz 

false 

if  (a  <  b) 

emp 

b,a 

bge 

false 

if  (la) 

tst 

a 

bnz 

false 

if  (a  &&  b) 

tst 

a 

beq 

false 

tst 

b 

beq 

false 

if  (!(a  &&  b)) 

tst 

a 

beq 

true 

tst 

b 

bne 

false 

true: 

Table  G:  Code  generated  by  Boolean  expressions 


Signed  Comparisons 

Unsigned  Comparisons 

emp  c2,c1 

if  (cl  ==  c2) 

emp 

c2,c1 

bne  false 

bne 

false 

emp  c2,c1 

if  (cl  !=  c2) 

emp 

c2,c1 

beq  false 

beq 

false 

emp  c2,c1 

if  (cl  <  c2) 

emp 

c2,c1 

bge  false 

bcc 

false 

emp  c2,c1 

if  (cl  <  =  c2) 

emp 

c2,c1 

bgt  false 

bhi 

false 

emp  c2,c1 

if  (cl  >  c2) 

emp 

c2,c1 

ble  false 

bis 

false 

emp  c2,c1 

if  (cl  >=  c2) 

emp 

c2,c1 

bit  false 

bio 

false 

Table  7:  Code  generated  by  Boolean  comparisons 


Pseudo- 

Macro  Name 

function 

Meaning 

Z 

or 

EQ 

cc_z 

zero 

NZ 

or 

NE 

N 

c 

1 

o 

o 

not  zero 

C 

or 

CS 

CC_C 

carry 

NC 

or 

cc 

cc_nc 

no  carry 

V 

or 

vs 

o 

o 

1 

< 

overflow 

NV 

or 

VC 

cc_nv 

no  overflow 

GT 

cc_gt 

greater  than 

GE 

cc_ge 

greater  or  equal 

LS 

cc_ls 

less  than 

LE 

O 

O 

5T 

less  than  or  equal 

HI 

o 

o 

1 

zr 

high 

LO 

0 

1 

0 

0 

low 

Ml 

0 

0 

3 

minus 

PL 

cc_pl 

plus 

Table  S:  Condition  code  constants 


Syntax 

( 1 )  if  (  boolean )  {  statement  list } 

(2)  if  (  boolean )  {  statement  list  1 }  else  {  statement  list  2 } 

Code  generated  for  (1) 

$  Evaluate  boolean.  If  false,  jump  to  label  1  $ 

$  statement  list  $ 
label  1: 

Code  generated  for  (2) 

$  Evaluate  boolean.  If  false,  jump  to  label  1  $ 

$  statement  list  1  $ 
bra  Iabel2; 
label  1: 

$  statement  list  2  $ 

Iabel2: 


Table  9:  The  if  statement 
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is  valid  and  generates 

TST  A 
BEQ 

CMPI  5,  B 
BLT 

CMPI  20,  B 
BGT 

You  can  specify  condition  code  values  directly.  (See  Ta¬ 
ble  8,  page  32.)  For  instance,  the  statement  if  (Z)  tests  the 
current  value  of  the  zero  bit  in  the  condition  code  regis¬ 
ter  and  generates  the  BNZ  (branch  not  zero)  instruction.  Z 
is  a  macro  in  C,  defined  in  the  ops  library,  which  expands 
to  a  call  to  the  pseudofunction  cc_zf  ). 

Structure  Statements 

I  said  earlier  that  PL/68K  has  all  C's  structure  state¬ 
ments — if,  do,  while,  for,  and  switch.  They  look  exactly 
like  C  code,  but  curly  braces  are  required  surrounding 
statement  lists  in  structure  statements.  In  other  words, 
structure  statements  have  the  form 

iff  . .)  {statement  list} 

iff  . .)  {statement  list}  else  {statement  list} 

while!. . .)  {statement  list) 

do  {statement  list}  while  (.  .  .); 

for  (...)  {statement  list} 

switchf  . .)  {statement  list} 

In  my  opinion,  allowing  curly  braces  to  be  optional  is  a 
big  flaw  in  C.  In  this  example: 

if  (abc  <  5) 
xyz  =  5; 
if  (abc  <  6) 
xyz  =  6; 

the  indentation  is  misleading  and  will  probably  cause  a 
bug.  This  kind  of  error  can  be  extremely  difficult  to  find. 

Let's  see  what  code  PL/68K's  structure  statements  pro¬ 
duce.  In  the  accompanying  tables,  the  dollar  sign  denotes 
code  that  corresponds  to  some  language  construct.  For 
example,  $  statement  list  $  stands  for  whatever  code  is 
generated  for  the  statement  list.  The  statement  list  could 
be  arbitrarily  complicated — for  instance,  it  could  contain 
nested  structure  statements.  The  notation 

$  Evaluate  boolean.  If  false,  jump  to  labell  $ 

indicates  that  code  is  generated  for  the  Boolean  expres¬ 
sion  such  that  a  jump  to  labell  is  taken  if  the  Boolean 
expression  is  false.  Otherwise,  control  falls  through  to  the 
following  code.  Labels  are  indicated  in  the  usual  way  by 
identifiers  followed  by  colons.  All  generated  labels  are,  of 
course,  unique,  even  though  they  may  have  identical 
names  in  the  tables. 

Table  9,  page  32,  shows  the  if  statement.  When  an  if 
statement  contains  no  else  clause,  the  Boolean  expression 


Syntax 

(1)  while  (  boolean )  { statement  list } 

(2)  while  (1)  {  statement  list } 

Code  generated  for  (1) 

bra  continue_label; 
labell: 

$  statement  list  $ 
continue_label: 

$  Evaluate  boolean.  If  true,  jump  to  label  1  $ 
break_label: 

Code  generated  for  (2) 

continue_label: 

$  statement  list  $ 
bra  continue_label; 
break.Jabel: 


Table  lO:  The  while  statement 

Syntax 

(1)  do  {  statement  list }  while  (  boolean ); 

(2)  do  {  statement  list }  whilefl); 

Code  generated  for  (1) 

labell: 

$  statement  list  $ 
continue_label: 

$  Evaluate  boolean.  If  true,  jump  to  labell  $ 
break_label: 

Code  generated  for  (2) 

continue_label: 

$  statement  list  $ 
bra  continue_label; 
break_label: 


Table  11:  The  do  statement 


Syntax 

(1)  for  (  assignment  list  7;  boolean-,  assignment  list  2) 

{ statement  list } 

(2)  for  (  assignment  list  1 ; ;  assignment  list  2 )  {  statement  list } 

(3)  for  (  assignment  list  1 ;  7;  assignment  list  2 )  {  statement  list } 

Code  generated  for  (1) 

$  assignment  list  1  $ 
bra  labelO; 
labell: 

$  statement  list  $ 
continue_label: 

$  assignment  list  2  $ 
labelO: 

$  Evaluate  boolean.  If  true,  jump  to  labell  $ 
break_label: 

Code  generated  for  (2)  or  (3) 

$  assignment  list  1  $ 
labell: 

$  statement  list  $ 
continue_label: 

$  assignment  list  2  $ 
bra  labell; 
break_label: 

Table  12:  The  for  statement 
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is  evaluated,  and  control  either  falls  through  to  the  then 
clause  or  a  jump  is  made  to  the  end  of  the  statement. 

Similar  code  is  generated  when  the  if  statement  con¬ 
tains  an  else  clause.  The  Boolean  expression  is  evaluated, 
and  control  either  falls  through  to  the  then  clause  or  a 
jump  is  made  to  the  else  clause.  A  BRA  (branch  always) 
instruction  following  the  then  clause  skips  around  the 
else  clause. 

The  code  generated  for  the  while  statement,  shown  in 
Table  10,  page  34,  might  be  a  little  controversial.  The  first 
instruction  is  a  branch  to  the  end  of  the  loop  so  that  the 
loop  test  occurs  at  the  bottom.  This  produces  the  fastest 
code  unless  the  while  loop  is  executed  less  than  once  on 
average.  In  the  rare  cases  in  which  this  jump  is  unwant¬ 
ed,  the  programmer  must  simulate  the  loop  in  some  way. 

Notice  the  labels  called  continue— label  and  break— label. 
These  are  used  as  target  labels  for  the  break  and  continue 
statements.  In  other  words,  within  a  while,  do,  or  for 
statement,  the  effect  of  a  continue  instruction  is  to  gener¬ 
ate  a  branch  to  the  continue— label  defined  for  that  state¬ 
ment.  Similarly  a  break  statement  generates  a  jump  to 
the  appropriate  break— label.  As  in  C,  you  can  also  use  the 
break  statement  inside  a  switch  statement. 

The  while  statement  generates  different  code  if  the 
Boolean  expression  is  a  nonzero  constant.  This  is  a  com¬ 
mon  idiom  in  C,  and  the  definition  of  PL/68K  ensures  that 
there  is  no  time  penalty  for  using  it. 

The  code  for  the  do  statement,  shown  in  Table  11,  page 
34,  is  similar  to  the  code  produced  by  the  while  statement. 
The  code  for  the  for  statement  (see  Table  12,  page  34)  is 
more  interesting.  If  the  loop  test  in  a  for  statement  is  non¬ 
trivial,  the  code  for  it  appears  at  the  bottom  of  the  loop. 
Note  also  that  the  syntax  of  the  for  statement  is  more 
restricted  than  in  C. 

The  switch  statement,  shown  in  Table  13,  page  37,  gen¬ 
erates  a  jump  table — i.e.,  a  table  of  addresses.  Code  is  gen¬ 
erated  that  jumps  through  that  table  to  the  proper  case 
statement,  based  on  the  contents  of  a  register.  Note  that 
the  switch  statement  destroys  this  register. 

It  is  sometimes  better  to  generate  a  sequence  of  tests 
rather  than  a  table  jump,  but  the  case  statement  always 
generates  a  table  jump.  Remember,  each  language  con¬ 
struct  in  PL/68K  stands  for  a  particular  sequence  of 
code — if  you  want  a  sequence  of  tests,  use  a  sequence  of  if 
statements;  if  you  want  a  table  jump,  use  a  switch  state¬ 
ment. 

Many  compilers  generate  jumps  to  jumps  when  they 
translate  structure  statements,  but  the  definition  of  PL/ 
68K  requires  that  all  jumps  to  jumps  (and  jumps  to  return 
statements)  be  eliminated.  The  assembler  can  do  this  in 
several  ways.  For  instance,  if  the  assembler  creates  a 
parse  tree  for  an  entire  function  before  any  code  is  gen¬ 
erated,  it's  easy  for  the  code  generator  to  look  at  the  tar¬ 
get  of  any  jump  to  see  if  it  is  another  jump  or  a  return 
instruction.  Alternatively  the  assembler  can  use  a  stan¬ 
dard  peephole  optimizer. 

Function  Calls 

Functions  in  PL/68K  can  have  formal  parameters  and  lo 


cal  arguments,  just  as  in  C.  The  code  shown  in  Table  14, 
page  37,  is  generated  by  function  calls.  Code  is  generated 
to  push  all  arguments  on  the  stack,  a  JSR  (jump  to  subrou¬ 
tine)  instruction  is  generated,  and,  if  necessary  an  ADD 
instruction  is  generated  to  pop  arguments  off  the  stack. 
One  long  word  is  always  reserved  on  the  stack  for  the 
first  argument,  which  shortens  the  calling  sequence 
when  there  are  less  than  two  arguments. 

The  ADD  instruction  can  be  eliminated  by  having  the 
called  program,  instead  of  the  calling  program,  pop  the 
arguments  off  the  stack,  but  the  sequence  shown  in  Table 
14  is  the  fastest.  If  you  eliminated  the  ADD  instruction  and 
pushed  the  arguments  in  the  same  way  (that  is,  above  the 
return  address),  the  called  program  would  need  to  do 
much  more  work  to  pop  off  its  arguments.  You  could  also 
push  the  actual  arguments  below  the  return  address,  but 
that  way  actually  increases  the  length  of  the  calling  se¬ 
quence.  In  order  to  push  arguments  below  the  return 
address,  you  would  have  to  use  an  instruction  such  as 
move  arg,n(sp),  which  is  2  bytes  longer  than  move 
arg,  —  (sp). 

Unlike  standard  C,  PL/68K  does  specify  the  order  in 
which  arguments  are  pushed,  namely  in  reverse  order. 
Thus,  a  function  that  takes  a  variable  number  of  argu¬ 
ments — printf  )  for  instance — will  find  its  first  argument 
on  the  top  of  the  stack. 

Of  course,  it  is  often  best  to  pass  arguments  in  registers, 
but  PL/68K  doesn't  need  a  separate  mechanism  to  do  this. 
Suppose  you  have  a  function  called  g(  )  whose  two  argu¬ 
ments  are  passed  on  the  stack.  To  change  g(  )  so  that  it 
will  take  its  arguments  in  registers,  you  just  define  the 
following  macro 

^define  g(a,b)d0  =  a;  dl=b;  gl( ) 
and  changeg's  name  togf.  Notice  that  a  statement  such  as 

if  (.  .  .)  g(x,y); 

cannot  cause  problems  in  PL/68K  because  you  must 
write 

if  (. . .)  (g(x,y);} 

instead.  (If  braces  were  omitted,  after  macro  expansion, 
the  code  would  be 

if  (.  .  .)  d0  =  a;dl  =  b;gl(  ); 

and  only  the  assignment  d0=a  would  be  part  of  the  if 
statement.) 

This  macro  might  generate  redundant  code.  Suppose  it 
were  called  with  do  as  the  first  argument,  for  instance. 
The  macro  would  expand  to  d0=d0  and  generate  the  in¬ 
struction  move  do, do.  To  handle  that  problem,  the  PL/ 
68K  assembler  eliminates  redundant  moves.  If  you  must 
generate  such  a  redundant  move  for  some  reason,  use  a 
pseudofunction.  Pseudofunctions  are  never  second- 
guessed  by  the  assembler. 
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switch  (  reg )  { 

case  constant  1 :  statement  list  1 ; 
case  constant  2 :  statement  list  2 ; 


case  constant  n  :  statement  list  n ; 
default:  default  statement  list ; 

} 

Code  generated 

if  (reg  <  min  1 1  reg  >  max)  { 
goto  default_label; 

} 

else  { 

$  goto  the  routine  whose  address  is  at  table  [reg]  $ 

} 


Table  13:  The  switch  statement 


No  arguments 

jsr  function 

One  argument 

move  arg,  (sp) 
jsr  function 

Two  or  more  arguments 

move  argn,  (sp) 
move  arg^,— (sp) 

move  arg2>— (sp) 
move  arg,,— (sp) 
jsr  function 

add  #  size  of  all  arguments  except  argn,  sp 


Table  14:  Code  generated  for  function  calls 


Entry 

movem.l 

all— local.  .registers ,  —  (sp) 

link 

an,  #  —  size  of  local  auto  variables  —  4 

Exit 

unlk 

a„ 

movem.l 

(sp)+,  a//_  locaL.  reg  is  ters 

rts 

Table  IS:  Code  generated  for  entry/exit  of  An-based 
functions 
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Accessing  Variables  Within  Functions 

Now  that  I've  covered  the  passing  of  arguments  to  a  func¬ 
tion,  I’ll  explain  how  the  function  gets  hold  of  those  argu¬ 
ments.  This  is  a  complicated  subject,  so  before  getting  in¬ 
volved  in  some  messy  details,  let's  handle  the  easy  cases. 

First,  PL/68K  keeps  its  hands  off  all  registers  declared 
outside  any  function.  These  global  registers  can  be  ac¬ 
cessed  from  within  functions,  but  PL/68K  never  gener¬ 
ates  code  to  save  or  restore  them.  Consequently  you  can 
prevent  PL/68K  from  interfering  with  any  register  sim¬ 
ply  by  declaring  that  register  outside  a  function.  By  the 
way  the  register  keyword  is  not  valid  outside  functions, 
but  that  does  not  prevent  you  from  declaring  register 
variables  anywhere  you  wish,  either  in  C  or  in  PL/68K. 
For  instance,  you  can  declare  aO  to  be  global  simply  by 
saying  char  *  aO;  outside  any  function. 

Second,  except  for  these  global  registers,  all  registers 
used  in  a  function  are  saved  on  entry  and  restored  on  exit 
from  the  function.  The  assembler  uses  the  MOVEM.L 
(move  multiple  register,  long)  instruction  for  this  pur¬ 
pose.  Accessing  register  variables  declared  in  a  function 
is,  of  course,  easy. 

Third,  if  a  local  variable  is  declared  to  be  static,  memo¬ 
ry  is  allocated  to  that  variable  in  static  memory,  not  on 
the  stack.  No  extra  code  is  needed  to  access  that  variable, 
either  on  function  entry  or  exit. 

Static  internal  variables  are  not  very  useful;  because 
the  values  of  static  internals  are  retained  between  invo¬ 
cations  of  a  function,  static  internals  are  destroyed  by  re¬ 
cursive  function  calls.  Also,  on  many  machines  (including 
the  68000)  accessing  a  variable  in  static  memory  is  more 
expensive  than  accessing  a  “local  auto”  variable — that  is, 
a  local  stack  variable.  At  any  rate,  generating  code  for 
static  internal  variables  is  straightforward  and  is  not  af¬ 
fected  by  the  following  complications. 

Functions  need  to  access  two  kinds  of  nonregister  vari¬ 
ables:  formal  parameters  and  local  auto  variables.  Both 
types  are  allocated  on  the  stack.  You  have  three  choices 


If  one  or  more  functions  called  within  this  function 

Entry 

movem.l 

suba 

all_local  registers ,  —  (sp) 

#  size  of  local  auto  variables  +  4,  sp 

Exit 

adda 

movem.l 

rts 

#  size  of  local  auto  variables  +  4,  sp 
(sp)-l all— local— registers 

If  no  function  called  within  this  function 

Entry 

movem.l 

a//__ local,  registers ,  —  (sp) 

Exit 

movem.l 

rts 

(sp)+,  all_local— registers 

Table  1G:  Code  generated  for  entry/e?bt  of  sp-based 
functions 


for  how  PL/68K  generates  code  for  these  stack  variables. 
You  make  your  choice  using  one  of  three  pseudofunc¬ 
tions:  base(An),  base(sp),  or  nobase(  ).  If  none  of  these 
appears  in  a  function,  the  default  is  base(sp). 

First,  you  can  have  PL/68K  access  stack  variables  via  an 
address  register  that  is  different  from  the  stack  pointer, 
as  shown  in  Table  15,  page  37.  If  the  base(An)  pseudo¬ 
function  appears  anywhere  in  the  function  (where  An  is 
any  address  register  except  the  stack  pointer,  a7),  PL/68K 
generates  a  LINK  (link  and  allocate)  instruction  on  func¬ 
tion  entry  and  an  UNLK  instruction  on  function  exit.  All 
stack  variables  are  accessed  via  the  address  register 
named  in  the  base(An)  pseudofunction. 

Second,  you  can  have  PL/68K  access  stack  variables  via 
the  stack  pointer,  as  shown  in  Table  16,  page  38.  The  as¬ 
sembler  generates  this  kind  of  code  if  the  base(a7)  or  ba- 
se(sp)  pseudofunction  appears  anywhere  in  the  func¬ 
tion.  The  code  generated  for  sp- based  functions  is  more 
complicated,  but  more  efficient,  than  that  for  An-based 
functions.  If  an  sp-based  function  contains  no  function 
calls,  the  stack  pointer  is  not  incremented  on  function 
entry  and  local  auto  variables  are  accessed  using  positive 
offsets  from  the  stack  pointer.  If  the  function  does  con¬ 
tain  other  function  calls,  however,  space  is  reserved  for 
local  auto  variables  by  incrementing  the  stack  pointer  on 
function  entry,  and  local  auto  variables  are  accessed  us¬ 
ing  negative  offsets  from  the  stack  pointer. 

Third,  you  can  access  stack  variables  by  hand.  If  the 
noUbaset  )  pseudofunction  occurs  anywhere  in  the  func¬ 
tion,  no  code  is  generated  on  function  entry  or  exit,  decla¬ 
rations  of  stack  variables  are  ignored,  and  no  explicit  ref¬ 
erences  to  stack  variables  are  permitted.  The  no-Jbase(  ) 
pseudofunction  is  useful  when  you  must  play  some  kind 
of  game  with  the  stack. 

Sp-based  functions  are  somewhat  dangerous.  If  the 
stack  pointer  is  changed  using  a  pseudofunction,  the  off¬ 
sets  used  to  access  stack  variables  are  going  to  get  out  of 
sync.  To  handle  this  problem,  several  pseudofunctions, 
shown  in  Table  17,  page  38,  allow  you  to  indicate  that  the 
offsets  should  be  changed. 

The  push(arg)  and  pop(arg)  pseudofunctions  are  equiv¬ 
alent  to  the  movetarg,* - sp)  and  move(*sp+  +,arg) 

pseudofunctions,  but  in  addition,  they  tell  the  PL/68K  as¬ 
sembler  to  adjust  the  offsets  used  to  access  stack  variables 
in  sp-based  functions.  The  addsp(n)  and  subspfn )  pseudo¬ 
functions  are  equivalent  to  the  addi(n,sp)  and  subi(n,sp) 
pseudofunctions,  but  again  they  tell  the  assembler  to  ad¬ 
just  offsets.  Finally  the  adjsp(n)  pseudofunction  gener¬ 
ates  no  code  but  tells  the  assembler  to  adjust  the  offsets. 


Pseudofunction 

Meaning 

base(an) 

use  an  basing  for  stack  variables 

base(sp) 

use  sp  basing  for  stack  variables 

nobasef ) 

access  all  stack  variables  “by  hand” 

push(arg) 

move  arg,  — (sp)  and  adjust  stack  offsets 

pop(arg) 

move  (sp)-l-,  arg  and  adjust  stack  offsets 

addsp(n) 

adda  #n,  sp  and  adjust  stack  offsets 

subsp(n) 

suba  #n,  sp  and  adjust  stack  offsets 

adjsp(n) 

adjust  stack  offsets 

Table  17:  Pseudofunctions  for  stack  operations 
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These  pseudofunctions  have  no  effect  on  An-based  func¬ 
tions. 

Summary 

To  summarize  the  strengths  and  weaknesses  of  PL/68K, 
the  syntactical  restrictions  that  make  PL/68K  a  strict  sub¬ 
set  of  C  are  listed  as  follows: 

•  All  operand/operator  combinations  must  correspond  to 
an  instruction  in  the  68000  instruction  set. 

•  Functions  neither  have  types  nor  return  values. 

•  The  array  operator  /  ]  is  eliminated,  but  arrays  may  be 
declared. 

•  Assignment  statements  are  severely  restricted. 

•  Statement  lists  must  be  surrounded  by  curly  brackets. 

•  There  are  no  floating  points,  or  double  constants,  or 
operators. 

There  are  no  additions  or  changes  to  C  syntax.  PL/68K 
and  assembly  language  are  semantically  identical;  the  ad¬ 
vantages  of  PL/68K  over  assembly  language  are  all  syn¬ 
tactical: 

•  C  syntax  makes  programs  easier  to  read. 

•  C  syntax  eliminates  many  common  coding  errors. 

•  Far  fewer  visible  labels  are  required. 

PL/68K  is  not  the  successor  to  C  nor  is  it  superior  to  C 
for  most  programming  projects.  The  advantages  of  PL/ 
68K  over  C  apply  only  in  limited  circumstances,  but 
when  performance  is  paramount,  PL/68K  stands  out: 

•  All  machine  resources  and  instructions  are  available. 

•  Global  allocation  of  registers  is  possible. 

•  Total  control  over  generated  code  is  possible. 

•  Generated  code  is  smaller  and  faster. 

Figure  2,  page  42,  shows  the  relationship  between  PL/ 
68K  and  its  two  parent  languages.  PL/68K  is  only  a  subset 


of  C;  not  all  of  C  is  included.  On  the  other  hand,  C  must  be 
augmented  by  the  ops  library  in  order  to  simulate  all  the 
machine  resources  of  assembly  language. 

Listing  One,  page  101,  shows  an  example  of  a  PL/68K 
function.  This  function  finds  a  name  in  a  symbol  table 
and  returns  information  about  that  name  in  registers. 
Listing  Two,  page  101,  shows  the  code  generated  by  the 
PL/68K  assembler  for  that  function. 

Conclusion 

PL/68K  started  life  as  a  C-like  assembly  language  for  the 
68000  chip.  High-level  assemblers  are  not  new — a  paper 
by  Niklaus  Wirth  (.Journal  ACM  15,  January  1,  1968)  de¬ 
scribed  a  high-level  assembly  language  for  IBM  360 
machines. 

My  early  thinking  about  PL/68K  was  influenced  by 
Wirth's  paper  and  by  the  register  allocation  and  code  se¬ 
lection  principles.  At  that  stage,  I  was  interested  in  using 
compiler  technology  to  create  better  assemblers.  I  saw  no 
particular  reason  to  make  PL/68K  a  subset  of  C. 

1  felt  dissatisfied  with  the  initial  version  of  PL/68K;  it 
was  doomed  to  be  "just  another  computer  language.  ’Not 
wanting  to  add  another  minor  dialect  to  the  Babel  of 
computer  languages,  I  decided  to  make  PL/68K’s  syntax 
identical  to  C's.  This  was  a  lucky  decision. 

From  the  first,  PL/68K  had  to  be  able  to  name  all  ma¬ 
chine  resources,  including  machine  instructions  and  as¬ 
sembly-language  pseudo-ops.  Early  versions  of  the  lan¬ 
guage  allowed  "raw”  lines  of  assembly  code  to  be 
interspersed  with  C-like  lines  of  code.  Although  this  ap¬ 
proach  had  some  merit,  my  decision  to  make  PL/68K's 
syntax  compatible  with  C  convinced  me  to  use  functional 
notation  to  represent  assembly-language  features.  This 
change  was  also  fortunate. 

I  began  to  speculate  about  what  would  happen  if  a  PL/ 
68K  program  were  compiled  with  a  C  compiler.  1  asked 
myself,  suppose  the  program  produced  by  the  C  compil¬ 
er  and  the  program  produced  by  the  PL/68K  assembler 
were  semantically  equivalent?  Suddenly,  PL/68K  be¬ 
came  not  just  another  assembly  language  but  a  new  way 
of  using  C. 

The  principle  of  semantic  equivalence  guided  a  rede- 
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sign  of  the  language;  any  construct  that  violated  this  prin¬ 
ciple  had  to  go.  In  addition,  I  invented  the  ops  library  so 
that  C  programs  could  simulate  68000  machine  instruc¬ 
tions.  Along  with  the  ops  library,  the  concept  of  pseudo¬ 
functions  was  born,  and  the  language  was  complete. 

PL/68K  allows  me  to  sidestep  a  question  that  has  been 
haunting  me  ever  since  I  started  programming — wheth¬ 
er  to  program  in  assembly  language  and  accept  the  re¬ 
sulting  inconveniences  or  to  program  in  a  high-level  lan¬ 
guage  and  accept  a  final  product  that  is  larger  and  slower 
than  it  could  be.  PL/68K  solves  that  dilemma. 

You  can  design  and  write  a  program  in  C,  keeping  in 
mind  the  possibility  that  you  will  convert  it  to  PL/68K 
eventually.  You  can  write  difficult  parts  of  the  program, 
or  parts  of  the  program  that  will  not  appear  in  the  final 
version,  using  all  of  C's  features.  After  you  have  de¬ 
bugged  the  C  program,  you  can  produce  a  PL/68K  ver¬ 
sion  of  the  program,  if  desired,  by  rewriting  or  excluding 
those  parts  of  the  program  that  use  full  C.  You  then  test 
the  PL/68K  version  and  improve  its  performance  as 
much  as  you  require. 

PL/68K  hits  precisely  the  right  level  of  abstraction  for 
systems  programming.  All  the  features  of  C  allow  you  to 
design  and  code  programs  easily,  but  when  you  need  to 
do  low-level  work,  nothing  stands  in  your  way. 

A  final  thought — you  could  transfer  most  of  the  syntax 
and  all  the  design  rules  of  PL/68K  to  a  similar  language 
for  other  machines.  In  this  limited  sense,  PL/68K  is  a  ma¬ 
chine-independent  assembly  language— -PL/68K  pro¬ 
grams  are  much  more  portable  than  programs  written  in 
traditional  assembly  language. 


The  relationship  between  PL/68K, 
C  and  assembly  language. 


C  are  not  present  corresponding  to  simulate  assembly 

in  PL/68K.  assembly  language  language  features 

not  found  in  C. 


Figure  2 


Note 

A  compiler  for  the  PL/68K  language  is  available  from  the 
author. 

Appendix :  Why  Expressions  Are  Restricted 
in  PL/G8K 

The  outline  of  the  argument  is  as  follows.  The  register 
allocation  rule  conflicts  with  C’s  precedence  rules  (which 
govern  the  order  in  which  operators  are  applied)  and  C’s 
rules  for  converting  operands  from  one  type  to  another 
(known  as  the  "usual  arithmetic  conversions”  in  the  C  Ref¬ 
erence  Manual).  Thus,  by  the  principle  of  semantic  equiva¬ 
lence,  all  constructions  in  PL/68K  that  involve  C's  prece¬ 
dence  and  type  conversion  rules  must  be  eliminated. 

Consider  a  typical  C  expression,  such  as  a  =  (b  *  c )  +  (d 
*  e);.  The  register  allocation  rule  says  that  this  expression 
must  be  evaluated  in  location  a,  but  that  is  not  possible.  At 
least  two  separate  locations  are  required — one  to  hold 
the  subexpression  (b  *  c)  and  another  to  hold  (d  *  e).  In 
general,  any  expression  involving  parentheses  may  re¬ 
quire  more  than  one  location  to  evaluate. 

The  only  way  to  make  a  single  location  suffice  for  the 
evaluation  of  all  expressions  is  to  require  left-to-right  (or 
right-to-left)  evaluation  of  operators.  Alas,  this  changes 
the  precedence  of  operators,  except  in  cases  such  as  a  = 
Id  *  c  +  c;,  which  is  evaluated  left  to  right  in  C  anyway. 

Even  such  limited  expressions  cannot  be  allowed, 
though.  C’s  rules  for  type  conversions  state  that  conver¬ 
sions  are  made  during  the  evaluation  of  the  right-hand 
side  of  the  expression.  Only  after  the  right  side  is  com¬ 
pletely  evaluated  does  the  assignment  take  place.  PL/68K 
has  only  one  place  to  make  those  conversions,  howev¬ 
er — the  left-hand  side  of  the  expression.  The  operands 
themselves  cannot  be  converted  because  that  would 
change  their  value.  Thus,  only  one  operand  can  be  con¬ 
verted  and  only  one  operand  can  be  allowed  on  the  right 
side  of  an  assignment  statement. 
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ARTICLES 


A  Simple  Multitasking 
Operating  System 
for  Real-Time  Applications 


For  the  past  year,  we  at  Terra 
Nova  Communications  have 
been  involved  in  a  develop¬ 
ment  project  that  requires  a  simple, 
fast,  clean  32-bit  microprocessor  oper¬ 
ating  system.  After  a  great  deal  of  re¬ 
search,  we  were  unable  to  find  a 
commercial  system  that  met  our 
stringent  requirements  of  extremely 
fast  response  time  (even  under  a  load 
of  20  users),  low  price  (less  than 
$10,000  for  both  system  and  soft¬ 
ware),  compact  code  size  (we  wanted 
a  system  kernel,  including  all  the  util¬ 
ity  routines  discussed  in  this  article, 
that  required  less  than  20K  of  object 
code),  and  simple  programming  of 
applications.  After  some  brainstorm¬ 
ing,  we  created  a  68000  multitasking 
kernel  that  met  and  even  exceeded 
our  expectations  of  speed  and  com¬ 
pactness.  Released  from  hardware  re¬ 
quirements  by  our  decision  to  write 
the  kernel  ourselves,  we  decided  to 
use  the  VMEbus  hardware  configura¬ 
tion  because  of  its  standardization, 
complete  hardware  specification,  rel¬ 
atively  low  price,  ease  of  expansion, 
and  the  availability  of  lots  of  high¬ 
speed  hardware  devices.  We  were 
also  impressed  by  the  reliability  and 
ease  of  use  of  the  Eurocard  connec¬ 
tors  used  with  the  VMEbus. 

Why  Wot  Use  an  Existing  OS? 

Our  requirements  for  speed  and 
compactness  stemmed  primarily 
from  the  need  to  handle  a  large  num¬ 
ber  of  I/O  tasks  over  serial  lines  with- 


Nicholas  Turner,  10  McGranahan 
Court,  Boulder  Creek,  CA  95006,  (408) 
338-9510 


by  Nicholas  Turner 


The  instruction  set 
for  the  68000 family 
is  nearly  orthogonal. 
This  is  important  for 
a  system  on  which  a 
lot  of  assembly-lan¬ 
guage  development 
work  is  to  be  done. 


out  incurring  large  overheads  for  in¬ 
terrupt  handling,  disk  access,  and 
context  switching — that  is,  we  need¬ 
ed  to  be  able  to  do  significant 
amounts  of  I/O  without  slowing  the 
system.  Our  kernel  should  eventual¬ 
ly  be  able  to  handle  20  real-time  us¬ 
ers  over  serial  lines  at  1,200  bps,  in¬ 
cluding  full-speed  block  transfers, 
with  no  perceptible  response-time 
delay  and  only  minor  slowing  of  the 
byte-transfer  rates.  We  needed  a  sys¬ 
tem  that  would  degrade  gracefully; 
rather  than  pausing  in  midstream  as 
one  task  takes  over  the  system  for  an 
appreciable  fraction  of  a  second  or  as 
tasks  are  paged  in  and  out,  it  should 
slow  down  gradually  as  the  load  in¬ 
creases,  always  providing  steady  and 
uniform  output,  even  if  it's  at  a  re¬ 
duced  byte  transfer  rate.  None  of  the 
commercial  systems  we  examined 
had  this  property,  nor  were  they 
able  to  handle  the  load  required 
without  significant  degradation. 

Examination  of  the  code  used  in 
several  of  the  commercial  kernels 
we  sampled  showed  some  interest¬ 


ing  reasons  for  this:  Most  kernels 
contained  code  designed  to  handle 
all  sorts  of  unlikely  circumstances 
that  might  arise  in  an  environment 
where  you  don’t  know  what  sorts  of 
programs  might  be  running.  Not 
only  did  this  code  add  significantly  to 
the  size  of  the  kernel  but  it  also 
slowed  down  the  process  of  context 
switching  between  tasks  in  many 
cases.  We  needed  the  fastest  possible 
context  switch  in  order  to  guarantee 
that  minimum  system  time  was 
spent  on  this.  Fortunately,  we  knew 
exactly  which  applications  would  be 
running  on  our  system,  and  we  were 
able  to  design  a  complete  applica¬ 
tion/system  interface  to  make  appli¬ 
cation  coding  easy.  Because  we  knew 
that  all  application  code  running  un¬ 
der  our  kernel  would  be  "polite” 
(would  follow  all  the  rules  of  the  in¬ 
teraction  between  application  and 
kernel)  and  that  all  source  code 
would  be  available  for  debugging, 
we  were  able  to  dispense  with  a  lot 
of  the  error-handling  code  usually 
present  in  commercial  kernels. 

We  discovered  that  another  con¬ 
tributing  factor  to  the  time  required 
for  a  context  switch  was  the  magni¬ 
tude  of  the  context  that  was 
switched.  In  most  of  the  systems  we 
examined,  all  the  machine  registers 
were  saved  and  restored,  and  full  sta¬ 
tus  information  was  saved,  both  of 
which  took  up  a  significant  amount 
of  processing  time.  As  we’ll  explain 
later,  we  fixed  this  in  a  rather  unor¬ 
thodox  way. 

Further,  many  commercial  ker¬ 
nels  required  the  use  of  a  memory 
manager  chip  and  spent  significant 
amounts  of  time  paging  users  in  and 
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out  to  compensate  for  a  small  system 
memory.  We  opted  against  memory 
management,  mainly  because  it 
solved  no  problems  for  us.  We  didn't 
need  any  sort  of  memory  protection; 
in  fact,  one  of  the  most  important  cri¬ 
teria  was  that  all  tasks  must  be  able  to 
quickly  read  and  write  data  belong¬ 
ing  to  any  other  task  or  to  the  system 
itself.  Also,  our  memory  require¬ 
ments  were  not  large  (minimum 
512K,  expandable  to  several  mega¬ 
bytes)  and  because  of  the  amount  of 
code  sharing  between  tasks,  the 
structure  of  our  data  heap,  and  the 
heap’s  interaction  with  the  disk  sys¬ 
tem,  there  was  no  need  for  hard¬ 
ware  paging  of  memory. 

Why  Program  the  Kernel  in 
Assembly? 

It  was  clear  from  the  start  that,  in  or¬ 
der  to  get  the  kind  of  performance 
we  wanted  from  the  system,  the  in¬ 
ner  kernel  had  to  be  written  in  na¬ 
tive  code.  Even  compiled  C  or  Forth 
would  have  had  to  be  manually 
"tuned"  in  assembly  source  code 
form.  Further,  we  could  see  several 
difficulties  with  compiled  lan¬ 
guage — we  needed  to  do  so  many 
"tricky"  things  to  extract  the  last  few 
cycles  from  the  system  kernel  that 
writing  it  in  compiled  code  was  out 
of  the  question.  By  putting  the  entire 
kernel  in  machine  code,  we  simpli¬ 
fied  the  effort  required  to  make  ma¬ 
jor  changes  (it's  all  in  the  same  lan¬ 
guage)  and  made  possible  a  far  more 
complete  and  integrated  tuning. 

Eventually  we  expect  to  put  up  at 
least  a  C  compiler  and  a  Forth  inter¬ 
preter  for  faster  development,  but  for 
the  moment  all  development  is  in  as¬ 
sembly  for  speed  and  compactness. 
Because  assembly  was  the  language 
of  choice,  selection  of  the  target  pro¬ 
cessor  was  the  next  important  issue. 

Why  Vse  the  68000? 

The  eventual  goal  of  our  project  is  to 
provide  a  responsive  telephone  dial¬ 
up  system  that  is  able  to  support  up  to 
30  or  40  simultaneous  calls  without 
significant  performance  degradation. 
Such  a  task  requires  a  truly  powerful 
processor,  even  if  the  whole  system  is 
written  entirely  in  native  code.  For 
several  reasons,  we  have  chosen  the 
68000  family  of  processors  for  our 
base  hardware.  The  most  important 
reason  is  that  the  instruction  set  is  ex¬ 


tremely  versatile  and  powerful.  It  is 
in  many  ways  a  true  32-bit  instruction 
set,  although,  unless  you  are  using  a 
68020,  you  must  put  up  with  slightly 
slower,  memory  access  for  32-bit 
reads  and  writes  because  of  the  16-bit 
data  path. 

The  instruction  set  for  the  68000 
family  is  nearly  orthogonal — that  is, 
almost  every  instruction  can  be  used 
with  any  of  the  12  addressing  modes. 
This  is  important  for  a  system  on 
which  a  lot  of  assembly-language  de¬ 
velopment  work  is  to  be  done  be¬ 
cause  the  programs  become  much 
easier  to  generate,  read,  and  debug. 
Unfortunately  even  the  68000  is  not 
perfect.  Several  times  we’ve  encoun¬ 
tered  annoying  restrictions — for  ex¬ 
ample,  we’ve  often  cursed  our  inabil¬ 
ity  to  do  a  PC-relative  store. 

The  68000  also  has  another  advan¬ 
tage  for  assembly-language  program¬ 
mers:  The  memory  architecture  in 
its  native  mode,  without  the  extras 
added  by  a  memory  management 
chip,  is  perfectly  flat.  That  is,  the  ad¬ 
dress  space  is  completely  continuous 
from  $00  0000  all  the  way  to  $FF 
FFFF — or  $FFFF  FFFF  if  you  have  a 
68020.  For  an  assembly  hacker,  this  is 
far  more  desirable  than  the  segment¬ 
ed  architecture  required  with  the 
Z8000  or  80286  or  with  any  8-  or  16- 
bit  processor.  For  people  writing  in  a 
high-level  language,  this  is  not  an  is¬ 
sue  because  they  never  deal  directly 
with  the  memory  at  all.  But  for  us, 
it's  nice  to  be  able  to  chop  up  that  big 
address  space  in  any  way  we  like.  As 
I'll  explain  later  in  this  article,  we 
have  chosen  to  make  it  into  an  enor¬ 
mous  heap  and  virtual  disk  area, 
thus  making  the  fullest  possible  use 
of  each  and  every  byte. 

Finally,  after  it  became  clear  that 
the  VME  hardware  bus  was  the  best 
bet  for  our  needs,  the  68000  proces¬ 
sor  family  was  the  logical  choice  be¬ 
cause  of  the  large  number  of  68000- 
oriented  products  available  for  the 
VME  architecture. 

In  this  article  I'll  describe  briefly 
how  our  operating  system  fits  to¬ 
gether,  and  then  I'll  get  to  the  fun 
stuff:  the  tricks  and  shortcuts  we 
used  to  get  such  incredible  perfor¬ 
mance  out  of  the  68010  in  our  system. 
If  you  are  already  familiar  with  how 
a  multitasking  operating  system  fits 
together,  you  might  want  to  skim 
down  to  the  tricks  and  shortcuts. 


MULTITASKING  OS 


Memory  Structure 

RAM  memory  is  divided  into  two  ar¬ 
eas:  the  system  zone  and  the  heap,  as 
shown  in  Figure  1  (page  47).  The  sys¬ 
tem  zone  begins  at  memory  address 
0  with  the  68000  vector  list  and  con¬ 
tinues  up  from  there.  It's  quite  small 
and  contains  only  a  few  data  struc¬ 
tures.  Figure  2  (page  47)  diagrams  the 
structure  of  the  system  zone. 

The  68000  vector  list  contains  all 
the  hardware  vectors  required  for 
processing  of  interrupts  and  excep¬ 
tions.  It  requires  $300  bytes.  The  data 
in  the  vector  list  is  first  set  up  by  the 
initialization  section  and  modified 
thereafter  by  the  I/O  manager  as  de¬ 
vice  interrupts  are  added  or  deleted. 

Above  the  vector  list  is  a  small  zone 
containing  miscellaneous  system 
variables  and  pointers.  The  time  of 
day  and  date  are  kept  here,  along 
with  pointers  for  the  various  linked 
lists  maintained  by  the  kernel,  plus 
some  other  information  that  needs  to 
be  quickly  accessible  via  absolute 
short  addressing  (the  fastest  way  to 
get  at  a  memory  location  from  the 
68000).  Several  I/O  devices  also  have 
data  here,  where  it  can  be  accessed 
by  interrupt  routines  without  the 
overhead  of  following  pointers 
through  memory. 

Following  the  system  variable 
zone,  we  have  a  rather  strange  beast 
in  today’s  world:  an  old-fashioned 
jump  table!  This  table  contains  more 
than  100  absolute-long  address  mode 
JMP  instructions  at  the  moment — 
hundreds  more  are  planned. 

The  next  structure  in  the  system 
zone  is  the  task  control  buffer  (TCB) 
table,  which  is  an  array  of  data  struc¬ 
tures  that  are  linked  via  pointers  into 
several  doubly  linked  lists.  Each  task 
is  associated  with  one  TCB  in  the  TCB 
array.  When  a  task  releases  control 
to  the  next  task,  the  context  switcher 
reads  the  pointer  from  the  outgoing 
task’s  TCB  to  get  the  address  of  the 
next  task's  TCB.  This  prevents  unnec¬ 
essary  overhead  while  reading  TCBs 
belonging  to  inactive  tasks  in  the  ar¬ 
ray  because  they  are  not  part  of  the 
active  task  linked  list.  It  also  makes 
possible  an  extensible  TCB  array:  If 
the  primary  array  is  full  when  an¬ 
other  task  is  about  to  be  spawned,  the 
task  manager  can  allocate  a  nonrelo- 
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Entire  Memory  Space 

*FFFFFF- 


*00  0300- 
*00  0000- 


-I/O  mapped  addresses 

-Unused  RAM  space 

-The  Heap 

-System  Variables  &  Arrays 
-Interrupt  Sc  Trap  Vectors 


Figure  1:  Basic  organization  of  the  68000  memory  space 


The  System  Zone 


about- 
*00  1000 


*00  0300- 


*00  0000 


-Master  Handle  Array 

-TCB  Array 

-System  Jump  Table 
-Pointers  and  Variables 

Interrupt  &  Trap  Vectors 


Figure  2:  The  system  variables  and  arrays 


The  Heap 

(typical  configuration) 


End  of  RAM 
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1553 System  Kernel 
E3 Other  Code  Segments 
UTData  Items 
MDffil  Inter-task  Messages 
IteilDisk  Buffers 
LiU Task -allocated  Items 
\  ■■Miscellaneous 


eatable  item  in  the  heap  and  contin¬ 
ue  the  TCB  array  there. 

Another  extensible  array  follows 
the  TCB  table:  The  master  handle  ar¬ 
ray  contains  handles  to  relocatable 
heap  items.  (A  handle  is  the  address  of 
a  pointer.)  All  accesses  to  relocatable 
heap  items  must  be  dereferenced  (fol¬ 
lowed  through  the  handle  to  the 
pointer  to  the  actual  heap  item)  be¬ 
fore  a  task  can  use  the  item.  That 
way  if  an  item  is  relocated  by  the 
heap  munger  (see  description  of  the 
heap  munger,  later)  during  its  back¬ 
ground  heap-optimization,  any  tasks 
that  own  the  relocated  item  will  still 
be  able  to  find  it  because  the  heap 
munger  always  fixes  the  master  han¬ 
dle  so  it  is  correct  after  moving  a  heap 
item.  This  master  handle  is  often  lo¬ 
cated  in  the  master  handle  array  al¬ 
though  it  doesn't  need  to  be.  Wherev¬ 
er  it  is,  though,  it  must  be  in  a 
nonrelocatable  place  so  that  the  heap 
munger  can  follow  a  pointer  back 
from  the  heap  item  to  its  master 
handle. 

After  the  last  master  pointer  is  an 
end  mark.  At  the  next  32-byte  bound¬ 
ary  the  heap  begins. 

The  heap  (Figure  3,  page  47)  takes 
up  all  the  available  RAM  beyond  the 
system  zone.  It  is  a  single  data  struc¬ 
ture  composed  of  chunks  called 
items.  Every  single  byte  of  the  heap 
belongs  to  an  item  of  one  sort  or  an¬ 
other.  An  item  can  be  a  deletion,  or  it 
can  contain  actual  information.  Items 
that  contain  information  can  be  allo¬ 
cated  (owned  by  one  or  more  tasks)  or 
unallocated.  Unallocated  items  can  be 
purged  by  the  heap  munger  (see  later) 
if  it  needs  to  make  more  room  for  a 
memory  request  from  a  task.  For 
speed  and  ease  of  programming,  ev¬ 
ery  single  heap  item  begins  and  ends 
on  a  32-byte  boundary. 

Virtually  all  system  information 
that  doesn't  have  to  be  addressed  ab¬ 
solutely  is  stored  in  the  heap,  in  vari¬ 
ous  heap  items  owned  by  the  system 
kernel.  In  addition,  the  heap  contains 
all  executable  code,  including  the 
system  kernel  itself,  in  chunks  called 
code  items. 

Each  heap  item  contains  a  32-byte 
heap  header  record,  followed  by  zero 
or  more  32-byte  data  blocks.  The 
header  record  contains  the  informa¬ 
tion  necessary  for  the  heap  manager 
and  the  heap  munger  to  identify, 


Figure  3:  Typical  structure  of  the  heap 
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move,  and  validate  each  item.  The 
heap  is  organized,  like  much  of  the 
rest  of  the  system,  as  a  doubly  linked 
list.  As  the  heap  munger  scans 
through  it,  it  follows  the  pointers  for¬ 
ward  or  backward  to  verify  that  all  is 
in  order.  If  it  finds  anything  that  is  not 
completely  kosher,  it  immediately 
stops  the  system,  takes  over  the  sys¬ 
tem  console,  and  enters  the  debugger 
with  a  descriptive  error  message. 
When  a  bug  occurs,  it  is  often  the 
heap  munger  that  detects  the  prob¬ 
lem  (in  the  form  of  a  messed-up  heap 
header)  before  anything  else 
happens. 

Division  of  Labor 

The  kernel  is  divided  into  several  dis¬ 
tinct  blocks  of  code.  They  are  of  three 
types:  one-time  routines  (initializa¬ 
tion),  system  calls  (routines  available 
from  every  task),  and  discrete  tasks 
(self-contained  programs  that  run  un¬ 
der  the  context  switcher,  just  as  do 
application  tasks).  Some  of  the  system 
calls  we’ve  developed  are  listed  in  Ta¬ 
ble  1  (page  49).  This  is  not  intended  to 
be  a  complete  list,  only  to  give  some  of 
the  system ’s  flavor. 

The  initialization  section  is  the 
block  of  code  that  gains  control  be¬ 
fore  anything  else  happens.  It  starts 
with  a  brute-force  approach:  It  grabs 
control  from  whatever  operating  sys¬ 
tem  invokes  it,  and  then  it  sets  up  the 
bare-bones  data  structures  for  the  sys¬ 
tem.  I'll  go  into  greater  detail  about 
the  initialization  section  later,  when  I 
talk  about  tricks  and  shortcuts. 

The  most  important  low-level  code 
segment  is  the  context  switcher, 
which  is  the  routine  that  receives 
control  from  one  task  and  passes  it 
on  to  the  next.  It  is  extremely  small 
and  extremely  fast,  and  it  makes  a  lot 
of  assumptions  about  the  tasks  as  it 
does  its  job.  This  is  by  design:  By  mak¬ 
ing  assumptions  and  forcing  the 
tasks  to  adhere  to  them,  a  lot  of  over¬ 
head  is  eliminated.  Again,  I’ll  go  into 
detail  about  the  context  switcher  in 
the  section  on  tricks  and  shortcuts. 

The  task  manager  is  composed  of  a 
group  of  system  routines  available  to 
every  task.  They  allow  a  task  to  cre¬ 
ate,  destroy  and  manipulate  other 
tasks  or  itself. 

The  heap  manager  is  a  collection 
of  routines  that  allow  any  task  to  re¬ 
quest,  release,  lock,  enlarge,  or  other¬ 
wise  manipulate  heap  items. 


Call  name 

Description 

(Task  Manager  Calls) 

Spawn 

Create  a  new  task 

Kill 

Destroy  a  task  (by  task  number) 

Suicide 

Kill  the  calling  task 

(Heap  Manager  Calls) 

HeapGimme 

Allocate  an  item  in  the  heap 

HeapDel 

Release  (delete)  a  heap  item 

FilIZero 

Re-initialize  a  heap  item 

GetMaster 

Assign  a  master  handle  for  an  item 

(Message  Manager  Calls) 

Send  Msg 

Send  a  copy  of  a  block  of  memory  to  another  task 

DellMsg 

Delete  message  from  top  of  incoming  queue 

DelMsgs 

Delete  entire  incoming  message  queue 

TxtMsg 

Send  a  message  of  type  “TEXT” 

Get  Msg 

Fetch  next  message  in  queue 

HandleMsg 

Analyze  incoming  message  and  handle  if  standard  type 

(Character  I/O  Manager  Calls) 

DevReq 

Request  a  character  I/O  channel 

DevDemand 

Demand  a  character  I/O  channel  (usually  impolite) 

DevRel 

Release  a  character  I/O  channel 

PrToStd 

Select  this  task's  standard  character  I/O  device 

PrToMem 

Select  the  MemPrt  device  (see  text) 

(Text  Manager  Calls) 

GetCommand 

Input  a  command  line  and  parse  it,  passing  control  to  the  appropriate 
routine  based  on  the  command. 

AddCmdTab 

Add  a  set  of  commands  to  the  existing  command  set 

DoCommand 

Parse  and  execute  a  command  already  stored  in  memory 

GetPSW 

Input  and  encrypt  a  password  (to  be  compared  with  an  encrypted 
password  from  the  user  file) 

MoveString 

Move  an  ASCII  string 

Get  Line 

Input  a  line  of  ASCII  text  from  the  character  I/O  device 

PrLine 

Print  an  ASCII  string  on  the  character  I/O  device 

Print 

Print  a  line  of  text.  The  line  is  expected  to  immediately  follow  the  JSR 
Print  instruction. 

CompString 

Compare  two  ASCII  strings 

(Miscellaneous  System  Calls) 

Random 

What  system  would  be  complete  without  random  numbers? 

Sqrt 

Square  root  of  32-bit  integer 

Table  I:  Some  of  Terra  Nova's  system  calls 


TRAP-oriented  calls 
Instruction 

Cycles  used 

Description 

TRAP 

#n 

38 

call  the  system  routine 

MOVE.L 

2(SP),A0 

16 

point  to  word  argument 

MOVE.W 

(A0)  +  ,D0 

8 

fetch  the  argument 

MOVE.L 

A0,2(SP) 

16 

update  return  address 

(variable) 

(variable) 

decode  argument  word 
useful  code 

RTE 

24 

return  to  caller 

104  (+  decode) 

total  cycles  for  overhead 

JSR-oriented  calls 
Instruction 

Cycles  used 

Description 

JSR 

Label. W 

18 

call  low  memory  entry  point 

JMP 

Label. L 

12 

call  actual  routine 
useful  code 

RTS 

16 

return  to  caller 

46 

total  cycles  for  overhead 

Table  2:  Comparison  of  TRAP-  and  JSR-oriented  system  calls 
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The  message  manager  is  a  collec¬ 
tion  of  system  routines  that  make 
possible  a  clean  and  well-defined 
message-passing  protocdl  between 
tasks.  Simply  by  pointing  at  a  block 
of  memory  and  calling  a  system  rou¬ 
tine,  any  task  can  send  a  copy  of  any 
piece  of  data  to  any  other  task.  Read¬ 
ing  queued  messages  from  other 
tasks  is  similarly  easy. 

The  character  I/O  manager  is  a  set 
of  system  calls  and  interrupt  service 
routines.  Together  with  the  text 
manager,  it  makes  possible  a  simple 
I/O  structure,  in  which  each  task  can 
select  any  physical  or  logical  device 
for  I/O  by  passing  a  device  number. 
Serial  input  is  interrupt-driven,  and 
serial  output  is  polled.  Device  drivers 
can  be  added  or  removed  from  the  1/ 
O  manager  with  another  set  of  sys¬ 
tem  calls. 

The  text  manager  is  a  collection  of 
system  routines  that  ease  the  pro¬ 
cesses  involved  in  talking  to  humans. 
It  includes  powerful  routines  to  get 
and  parse  command  strings  as  well 
as  text-manipulation  routines  such  as 
case  conversion,  context-sensitive 
string  comparisons,  and  so  forth.  The 
powerful  parsing  calls  make  it  easy 
to  create  a  tiny  machine-language 
task  that  includes  a  complete  com¬ 
mand  interpreter  and  syntax  error 
handler.  This  is  very  important  if  a 
significant  amount  of  development  is 
to  be  done  in  assembly  language. 

The  trap  manager  handles  all  sys¬ 
tem  traps  except  I/O  interrupts, 
which  go  directly  to  the  I/O  manag¬ 
er.  Error  traps  always  cause  the  sys¬ 
tem  to  come  to  a  complete  standstill. 
This  is  important  to  us  because  of  the 
close  interaction  between  the  tasks, 
which  must  always  be  in  intimate 
communication  to  fulfill  the  purpose 
of  the  system.  When  an  error  trap  oc¬ 
curs,  all  task  switching  and  interrupt 
processing  stop  and  the  task  in 
which  the  error  occurred  takes  over 
the  system  console  and  enters  the  de¬ 
bugger.  The  human  in  charge  can 
then  take  corrective  action  and  re¬ 
start  the  system  with  minimal  dam¬ 
age.  Obviously  this  approach  would 
be  completely  unacceptable  in  a 
commercial  operating  system,  but 
for  us,  it  is  ideal  because  we  have  all 
the  source  code  for  the  entire  system 
and  can  often  correct  bugs  as  soon  as 
they  occur. 

No  assembly  language  develop¬ 


ment  system  is  complete  without  a 
debugger,  of  course,  especially  a  mul¬ 
titasking  one.  Our  debugger  is  a  com¬ 
mand  parser  that  any  task  can  in¬ 
voke,  either  automatically  (in 
response  to  an  error  trap)  or  directly. 
It  is  capable  of  running  alongside 
other  active  tasks,  even  multiple 
copies  of  itself,  and  it  allows  the  user 
full  manipulation  and  examination  of 
memory. 

The  heap  munger  is  a  distinct  task, 
always  present,  always  active, 
whose  original  job  was  to  survey  the 
contents  of  the  heap  continuously 
and  maintain  it  as  an  efficient  data 
structure  (by  using  a  background 
task  for  this,  we  avoided  many  com¬ 
plexities).  The  heap  munger  has 
turned  into  quite  a  bit  more  than  just 
a  trash  compactor,  however.  Its  re¬ 
sponsibilities  are  many  and  varied, 
from  checking  the  TCB  array  for  in¬ 
tegrity  and  waking  up  sleeping  tasks 
when  their  ships  come  in  to  respond¬ 
ing  to  messages  from  other  tasks  that 
want  to  know  what  the  system  load¬ 
ing  is  so  that  they  can  adjust  their 
own  CPU  usage  to  increase  the  over¬ 
all  performance  of  the  system.  In 
fact,  the  heap  munger  is  also  capable 
of  responding  to  text  messages  sent 
to  it  by  a  human  who  is  operating  a 
user  task,  in  which  case  it  responds 
by  sending  a  plain  English  message 
back  to  the  source  task,  which  then 
displays  it  for  the  human  to  read.  As 
a  general  rule,  the  heap  munger  per¬ 
forms  any  systemwide  activity  that 
must  be  performed  at  frequent,  reg¬ 
ular  intervals.  With  all  these  respon¬ 
sibilities,  it  is  the  largest  single  code 
segment  in  our  kernel,  weighing  in 
at  about  $A00  bytes. 

The  disk  munger,  like  the  heap 
munger,  is  a  distinct  task  that  is  al¬ 
ways  running  except  when  it's  wait¬ 
ing  for  an  I/O  completion.  Because  its 
structure  and  function  are  applica¬ 
tion  specific,  I  won’t  go  into  it  in  great 
detail  here.  I  would  like  to  point  out, 
however,  that  by  allocating  a  single 
task  to  handle  each  disk  device,  a 
large  number  of  problems  related  to 
data  contention  between  tasks  can  be 
avoided.  The  disk  munger  is  entirely 
message-driven:  As  each  task  re¬ 
quires  a  disk  access,  it  sends  a  mes¬ 
sage  to  the  disk  munger  for  the  de¬ 
vice  it  wants  to  access.  Each  I/O 
request  gets  added  to  a  queue  of  such 

Each  task's  TData  item  contains 


spaces  for  various  pointers  and  vec¬ 
tors  associated  with  its  current  char¬ 
acter  I/O  device,  if  any.  The  vectors 
include  various  standardized  rou¬ 
tines  such  as  InCheck,  which  checks 
to  see  if  a  character  is  available;  In- 
Wait,  which  waits  for  a  character 
and  returns  with  it;  OutCheck; 
OutWait;  plus  several  others.  The 
pointers  include  the  addresses  of  the 
destination  for  the  next  input  byte  (if 
any),  the  source  of  the  next  output 
byte,  and  so  forth. 

Character  input  is  generally  inter¬ 
rupt-driven.  Because  a  task  that  is 
awaiting  input  is  often  "asleep”  (not 
in  the  active  TCB  list),  it  is  necessary 
for  the  interrupt  routine  to  set  a  flag 
that  tells  the  system  to  wake  up  the 
owner  of  the  device.  Then,  after  the 
interrupt  has  been  handled,  the  heap 
munger,  which  is  always  awake  and 
active,  catches  the  set  flag  the  next 
time  it  gets  control  and  performs  the 
actual  manipulations  to  return  the 
task's  TCB  to  the  active  list.  In  order  to 
provide  an  input  time-out,  the  heap 
munger  also  awakens  each  task  once 
every  ten  seconds  so  that  the  task  can 
test  for  the  time-out. 

Each  task  may  request  to  be  as¬ 
signed  to  a  character  I/O  device.  If  a 
device  that  is  requested  is  currently 
assigned  to  another  task,  the  request¬ 
or  will  usually  have  to  wait  until  the 
device  is  available.  For  special  cases 
such  as  error  traps,  however,  there  is 
a  system  call  that  allows  the  task  to 
demand  to  be  connected  to  a  device. 
When  a  demanded  device  is  released, 
it  reverts  to  the  task  (if  any)  to  which  it 
was  attached  originally.  When  a  re¬ 
quested  device  is  released,  it  always 
becomes  available  (unattached)  again. 
Some  devices  can  be  attached  to  mul¬ 
tiple  tasks  at  the  same  time — for  ex¬ 
ample,  there  is  a  device  called 
MemPrt  that  reads  and  writes  to 
memory  as  if  it  were  a  character 
stream  from/to  a  serial  device.  This 
"virtual"  device  can  be  simultaneous¬ 
ly  active  for  different  tasks,  each  with 
its  own  set  of  pointers  in  the  TData 
item  for  reading  and  writing. 

I  won't  go  into  great  detail  about 
our  I/O  drivers  or  the  low-level  struc¬ 
ture  of  the  I/O  routines.  This  sort  of 
information  is  readily  available  in 
several  forms  in  computer 
bookstores. 
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The  Good  Stuff:  Tricks  and 
Shortcuts 

The  first  thing  our  operating  system 
does  when  it  gains  control  of  the  pro¬ 
cessor  is  to  deviously  remove  the  ex¬ 
isting  operating  system.  This  it  does 
by  using  a  trick  to  get  into  supervisor 
mode  (see  the  listing,  page  102).  First, 
it  shoves  a  new  address  into  the  priv¬ 
ilege  exception  vector,  which  is  in 
the  hardware  vector  table  in  low 
memory.  This  address  happens  to  be 
that  of  the  second  instruction  follow¬ 
ing  the  one  that  does  the  store  to  the 
vector.  The  next  instruction  is  a  privi¬ 
leged  but  otherwise  harmless  one. 
Thus,  when  it  tries  to  execute  it,  it 
traps  to  the  privilege  exception  vec¬ 
tor  and  thence  to  the  next  instruction 
in  the  program.  If  through  some 
quirk  we  happen  to  be  in  privileged 
mode  already,  the  processor  harm¬ 
lessly  executes  the  privileged  in¬ 
struction  and  falls  through.  Now  we 
are  in  privileged  mode,  and  we  can 
quickly  grab  the  rest  of  the  system. 

Next,  we  turn  off  all  the  interrupts 
in  the  system  as  quickly  as  possible.  It 
is  important  to  do  this  before  clear¬ 
ing  memory  because  a  stray  inter¬ 
rupt  might  happen  before  we  can 
turn  it  off  and  it  must  still  vector 
properly.  After  all  interrupts  are  out 
of  commission,  we  copy  our  own  set 
of  vectors  into  the  interrupt  table. 

The  jump  table  (discussed  later)  is 
next  moved  into  place  in  low  memo¬ 
ry.  It  is  read  from  a  section  of  object 
code  within  another  assembled  mod¬ 
ule.  It's  nothing  more  than  a  se¬ 
quence  of  more  than  a  hundred  ab¬ 
solute-long  JMP  instructions. 

Next,  we  clear  the  rest  of  memo¬ 
ry — except  the  kernel,  of  course — to 
zeroes.  This  is  both  a  general  safety 
measure  and  an  aid  in  debugging:  If  a 
chunk  of  memory  is  nonzero,  we 
can  be  certain  that  something  we  did 
caused  it  to  be  that  way.  Also,  it’s  nice 
to  be  able  to  assume  that  unused 
memory  is  always  zeroed  out;  it 
makes  for  much  faster  initializations 
later  on,  once  the  system  is  running. 

The  system  zone  requires  a  certain 
amount  of  initialization.  The  task 
control  blocks  must  be  set  up  and  the 
end  marks  for  the  TCB  and  master 
handle  arrays  must  be  set  in  place. 
The  values  in  the  miscellaneous  sys¬ 
tem  data  area  must  also  be  initialized. 

After  the  system  zone  is  in  place, 
the  heap  is  defined  from  the  next  32- 


byte  boundary  to  the  end  of  memo¬ 
ry.  Three  heap  items  are  initially  set 
aside:  a  deletion  from  the  beginning 
of  the  heap  to  the  start  of  the  kernel's 
code,  a  fixed  (immovable)  code  item 
for  the  kernel,  and  another  deletion 
from  the  end  of  the  kernel  to  the  end 
of  memory.  Soon,  the  other  tasks  will 
be  carving  up  the  big  deletions  for 
their  own  use. 

Each  time  a  task  is  spawned,  the 
task  manager  creates  a  new  TCB  and 
a  new  TData  item.  The  first  task  to  be 
spawned  is  the  system  console  man¬ 
ager.  The  system  task  manager  allo¬ 
cates  an  item  of  the  proper  size  from 
the  heap,  creates  a  TCB  for  the  new 
task,  and  adds  the  TCB  to  the  current 
linked  list  of  active  tasks’  TCBs. 

After  the  system  console  task  is 
spawned,  the  heap  munger  and  disk 
munger  are  also  spawned.  Note  that 
none  of  them  begins  to  execute  until 
the  initialization  code  jumps  into  the 
middle  of  the  context  switcher. 

We  discovered  that  one  of  the  big¬ 
gest  sources  of  “extra"  system  over¬ 
head  in  commercial  operating  sys¬ 
tems  is  the  need  to  manage  tasks  that 
might  possibly  get  out  of  hand  and 
take  over  the  system.  In  most  cases, 
such  "runaway”  tasks  are  avoided  by 
using  a  hardware  timer  to  assure  that 
any  given  task  will  only  be  able  to  run 
for  a  preset  time.  If  a  task  spends  too 
much  time  without  releasing  to  the 
system,  the  timer  interrupt  occurs 
and  vectors  the  CPU  through  to  the  su¬ 
pervisor  program.  This  program  then 
saves  the  existing  task’s  registers  and 
status  and  restores  those  of  the  next 
task  in  line,  which  then  is  off  and  run¬ 
ning  with  a  newly  reset  timer.  All  of 
this  requires  a  lot  of  tricky  and  com¬ 
plex  code  to  ensure  that  no  task  can 
"run  away”  and  lock  up  the  system. 
Also,  the  constant  saving  and  restor¬ 
ing  of  registers  and  status,  which  is 
necessary  because  the  context  switch 
is  interrupt-driven,  adds  measurably 
to  the  overhead  required  for  a  con¬ 
text  switch. 

We  debated  for  some  time  about 
the  best  way  to  reduce  this  overhead. 
Finally  we  settled  on  the  answer: 
We  developed  our  kernel  as  a  non- 
preemptive  task  controller.  This 
means  that  there  is  no  hardware  tim¬ 
er  to  interrupt  each  task  after  some 
preset  interval,  and  no  routines  are 
required  to  service  such  an  inter¬ 
rupt.  Instead,  we  use  a  simple  con¬ 


text  switcher,  one  that  doesn't  even 
bother  to  save  registers  or  the  previ¬ 
ous  task’s  status  bits.  It  is  the  task's  re¬ 
sponsibility  to  call  the  context 
switcher  often  enough  to  ensure 
smooth  system  operation  and  to 
make  sure  that  it  saves  any  registers 
that  it  needs  (other  than  A5  and  the 
stack  pointer).  For  our  application, 
this  is  perfect  because  most  of  our 
tasks  spend  most  of  their  time  wait¬ 
ing  for  input  or  output  in  the  inactive 
task  list,  during  which  time  the  other 
tasks  can  run  unhindered. 

When  a  task  has  finished  with  the 
CPU  and  is  ready  to  let  the  next  task  in 
the  active  list  run  for  a  while,  it  sim¬ 
ply  calls  the  context  switcher  as  a 
subroutine  using  a  JSB  instruction  to 
a  low-memory  JMP  instruction 
whose  address  is  fixed  regardless  of 
the  location  of  the  context  switcher. 
Even  with  the  added  overhead  of  the 
extra  JMP  instruction,  this  method  of 
calling  is  considerably  faster  than  a 
TBAP  instruction — the  usual  method 
of  calling  a  context  switcher. 

Once  the  switcher  has  control,  it 
checks  to  see  if  the  system  tasking  is 
stopped  (see  the  listing).  If  it  is,  then 
the  calling  task  immediately  gets 
back  control  through  a  simple  RTS. 
Otherwise,  it  gets  ready  to  call  the 
next  task. 

The  address  of  a  task's  TCB  is  in  its 
TData  area.  This  address  is  loaded 
into  AO.  Then  the  current  TData  base 
address  (in  register  A5)  is  subtracted 
from  the  stack  pointer,  yielding  a  rel¬ 
ative  displacement,  which  is  stored 
in  the  TCB.  Now  we  re  ready  to  move 
on  to  the  next  task. 

The  address  of  the  next  task  in  the 
circular  linked  list  of  active  tasks  is 
fetched  from  the  old  task’s  TCB  into 
AO.  Register  A5  is  set  to  point  to  the 
new  task's  TData  area  by  moving  its 
address  from  the  TCB,  and  the  stack 
pointer  is  restored  from  the  relative 
displacement  by  adding  A5  to  it. 
Then  a  simple  RTS  returns  control  to 
the  task. 

This  otherwise  trivial  scheme  has 
one  slight  complication:  Frequently, 
a  task  will  release  control  with  the 
intention  of  going  to  sleep  for  a 
while.  This  happens,  for  example, 
when  the  RAM  buffer  has  no  input 
characters  for  the  character  device 
attached  to  a  task  that  is  waiting  for 
input.  When  the  input  finally  hap¬ 
pens,  the  interrupt  routine  sets  a  flag 
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that  causes  the  heap  munger  to  wake 
up  the  task  when  it  next  checks  for 
such  a  situation.  The  problem  is  that 
the  context  switcher  I  have  just  de¬ 
scribed  has  no  provision  for  putting 
the  old  task  to  sleep:  It  assumes  that 
both  tasks  want  to  stay  awake. 

So,  we  created  an  alternate  context 
switcher  that  removes  the  outgoing 
task  from  the  active  list  before  calling 
the  new  one  (see  the  listing).  When  a 
task  wishes  to  go  to  sleep,  it  simply 
calls  the  alternate  context  switcher. 
The  primary  difference  is  that  be¬ 
fore  it  moves  on  to  the  next  task,  the 
alternate  switcher  does  some  stan¬ 
dard  and  fast  list  manipulation. 

Most  commercial  operating  sys¬ 
tems  use  one  or  more  of  the  TRAP  in¬ 
structions  to  perform  system  calls, 
usually  going  on  the  premise  that 
they  are  there  for  that  purpose  and 
that  the  TRAP  instructions  allow  pro¬ 
grams  to  be  more  general  and  more 
easily  relocated.  Unfortunately  TRAP 
instructions  on  the  68000  cause  a  ma¬ 
jor  problem:  They  take  a  long  time  to 
execute,  as  do  the  instructions  to  de¬ 
code  their  arguments.  The  RTE  in¬ 
struction,  which  returns  from  a 
TRAP,  shares  the  same  problem. 

We  could  understand  the  impor¬ 
tance  of  relocatable  programs,  cer¬ 
tainly  but  we  felt  the  long-lasting 
TRAP  instruction  was  too  much  to  ask 
of  an  ultra-fast,  real-time  system.  We 
therefore  designed  a  different,  faster 
way  to  call  system  routines:  the  JSR 
instruction  and  an  old-fashioned 
jump  table  in  low  memory  (see  Table 
2,  page  49,  for  a  timing  comparison). 
Instead  of  using  a  TRAP  instruction 
with  an  argument  following  in  the 
next  word,  we  simply  call  one  of 
many  entry  points  that  are  at  abso¬ 
lute  locations  in  low  memory.  Each 
entry  point  consists  of  a  single  JMP  in¬ 
struction  to  the  actual  system  call  en¬ 
try  point.  Not  only  do  we  save  the  ex¬ 
tra  time  required  for  the  TRAP  and 
RTE  instructions  but  we  also  avoid 
having  to  extract  the  argument  word 
from  the  bytes  following  the  TRAP  in¬ 


58 

32 


struction  and  having  to  add  two  to 
the  return  address  to  jump  around 
the  argument  because  the  argument 
is  implicit  in  our  choice  of  which 
routine  to  call.  (With  TRAP-based  sys¬ 
tem  calls,  an  argument  is  required  to 
specify  which  system  call  to  use  be¬ 
cause  there  are  only  16  traps.  With 
JSR  calls,  there  can  be  hundreds  of 
separate  entries,  so  no  argument  is 
required  to  specify  which  call  is  to  be 
used.)  By  using  subroutines  instead  of 
traps,  we  shaved  more  than  100  ma¬ 
chine  cycles  from  every  single  sys¬ 
tem  call,  which  makes  a  measurable 
difference  in  a  machine  that  uses  lots 
of  system  calls. 

Conclusion 

With  the  two  context  switchers  just 
described,  a  small  set  of  carefully  de¬ 
signed  system  routines,  a  somewhat 
unusual  system  calling  procedure, 
and  a  certain  amount  of  cooperation 
from  the  application  programs,  we 
have  vastly  increased  the  throughput 
of  our  system.  Our  approach  is  obvi¬ 
ously  not  well  suited  to  most  projects 
as  it  requires  a  considerable  amount 
of  skill  and  cooperation  on  the  part  of 
the  programmers.  Furthermore,  be¬ 
cause  of  its  nonstandard  nature,  it  is 
poorly  suited  to  any  applications  that 
are  written  for  commercial  sys¬ 
tems — at  least  until  we  get  a  C  compil¬ 
er  running!  If  you  need  an  extremely 
fast  multitasking  system  for  a  special¬ 
ized  real-time  application  and  are 
strapped  for  funds,  however,  this  ap¬ 
proach  can  turn  a  relatively  inexpen¬ 
sive  microcomputer  into  an  amazing¬ 
ly  powerful  system.  To  date  we  have 
done  just  that  for  four  different  hard¬ 
ware  configurations. 

I'd  be  happy  to  discuss  the  philoso¬ 
phy  and  tricks  in  greater  detail  with 
anyone  who  is  interested.  For  more 
information  on  our  operating  sys¬ 
tem,  write  to  Nick  Turner  at  the  fob 
lowing  address: 

Terra  Nova  Communications 

10  McGranahan  Ct. 

Boulder  Creek,  CA  95006 

Or  call  me  at  (408)  338-9510.  Terra 
Nova  Communications  is  a  consulting 
firm  specializing  in  small  multitask¬ 
ing  systems.  ddj 
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Bringing  Up  the  68000 

A  First  Step 


Adapted  by  permission  of  the  publish¬ 
er,  Prentice-Hall  Inc.,  from  the  forth¬ 
coming  book  Designing  and  Trouble¬ 
shooting  a  68000  Microcomputer 
System  by  Alan  D.  Wilcox,  available 
1986.  No  part  of  this  adaptation  may 
be  reproduced,  in  any  form  or  by  any 
means,  without  written  permission 
from  the  publisher. 

There  are  two  ways  to  bring  up 
a  new  68000  microcomputer 
system:  the  hard  way  and  the 
easy  way.  The  hard  way  is  to  use  the 
traditional  approach  of  designing  the 
hardware  and  then  using  a  develop¬ 
ment  system  along  with  test  software 
and  some  in-circuit  emulation.  Given 
enough  hours  of  testing  and  correct¬ 
ing  problems,  the  68000  system  has  a 
good  chance  of  running  successfully. 
In  contrast,  the  easy  way  is  to  design, 
build,  and  test  the  hardware  module 
by  module  using  the  68000  as  a  free- 
running  processor. 

The  impact  of  the  free-running 
technique  on  hardware  develop¬ 
ment  is  quite  startling.  The  68000  ker¬ 
nel  shown  in  Figure  1  (page  61)  can 
be  made  to  run  so  easily  that  a  logic 
probe  can  test  it.  You  don't  need  to 
use  sophisticated  digital  develop¬ 
ment  tools  such  as  a  logic  analyzer  or 
a  development  system  with  an  in-cir- 
cuit  emulator.  If  troubleshooting  is 
necessary,  you  need  only  a  common 
dual-trace  oscilloscope. 

Free  running  the  68000  means  that 
the  processor  is  allowed  to  execute  a 
do-nothing  instruction  continually. 
This  is  accomplished  by  breaking  the 
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normally  closed  loop  between  the 
68000  and  its  memory,  as  shown  in 
Figure  2  (page  61).  Instead  of  carrying 
program  instructions  from  memory, 
a  one-word  instruction  (call  it  a  NIL 
instruction)  can  be  jammed  onto  the 
data  bus.  (The  mnemonic  NIL  is  not 
part  of  the  68000  instruction  set  per 
se;  I  coined  it  as  a  simple  expression 
of  the  instruction  used  for  free  run¬ 
ning.)  Thus,  when  the  68000  reads 
the  data  bus  for  an  instruction,  it 
fetches  the  NIL  word,  executes  it,  in¬ 
crements  the  address,  and  reads  the 
next  NIL.  This  cycling  repeats  over 
the  entire  16-megabyte  address 
range;  when  the  processor  reaches 
the  end  of  the  16  megabytes,  it  sim¬ 
ply  starts  over  again. 

The  strategy  for  bringing  up  the 
68000  is  to  design,  build,  and  test  the 
68000  kernel  shown  in  Figure  2.  Next, 
design  and  build  one  additional  mod¬ 
ule,  connect  it  to  the  kernel,  and  test 
it  while  the  processor  is  free  run¬ 
ning.  Add  yet  another  module  and 
test  it  while  free  running.  You  can 
free  run  the  68000  all  the  way 
through  the  construction  of  a  com¬ 
plete  CPU  board.  In  fact,  if  a  processor 


board  fails,  you  can  usually  free  run 
it  to  help  speed  troubleshooting.  The 
only  part  of  the  system  that  you  can¬ 
not  test  easily  while  it  is  free  running 
is  the  data  bus  itself,  because  the  NIL 
instruction  is  forced  on  the  bus. 

The  Steps 

Several  steps  are  involved  in  bring¬ 
ing  up  the  68000  using  the  free-run¬ 
ning  technique.  The  intent  of  this  ar¬ 
ticle  is  to  describe  the  necessary  first 
step:  how  to  get  the  kernel  running. 
Once  you  have  the  kernel  in  opera¬ 
tion,  the  rest  is  fgirly  straightfor¬ 
ward.  Here  is  a  brief  overview  of  the 
entire  scenario  to  complete  a  work¬ 
ing  68000  CPU  board: 

1.  Bring  up  the  kernel.  Design, 
build,  and  test  the  power  system,  the 
68000  clock  and  drivers,  the  reset  and 
halt  module,  and  the  68000  module. 

2.  Add  a  wait  state  and  data  trans¬ 
fer  acknowledge  (DTACK*)  generator 
module. 

3.  Add  RAM  and  EPROM  decoding 
circuits,  connect  address  and  control 
bus  circuits. 

4.  Write  a  simple  looping  program 
for  a  pair  of  EPROMs.  Remove  the  NIL 
instruction  and  close  the  broken  loop 
between  the  EPROMs  and  the  68000 
data  bus.  The  processor  should  now 
be  able  to  read  its  stack  and  program 
counter  vectors  from  the  EPROMs 
and  execute  the  loop  program. 

5.  Add  the  RAM  connections  to  the 
data  bus.  If  the  68000  is  still  running 
successfully  with  the  simple  loop 
program,  add  more  code  to  include 
reading  and  writing  RAM.  If  the  code 
is  a  very  tight  loop,  an  oscilloscope 
will  synchronize  easily  and  you  can 
use  it  to  check  the  timing  of  the  vari¬ 
ous  control  lines  to  all  the  memory  in 
the  system  so  far. 
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6.  Modify  the  reset  and  EPROM-con- 
trol  circuits  so  that  the  EPROMs  do  not 
have  to  be  decoded  at  address  0  ex¬ 
cept  during  reset.  Normally  the  low 
memory  addresses  should  be  RAM  so 
that  exception  vectors  can  be  altered 
dynamically;  EPROMs  should  be  else¬ 
where. 

7.  If  at  least  4K  of  RAM  has  been  de¬ 
coded  starting  at  address  8,  and  the 
EPROMs  are  decoded  for  0  to  7  and 
$8000  to  $BFFF,  then  the  system  can 
use  the  Motorola  TUTOR  EPROM  set. 
When  you  restart  the  system,  assum¬ 
ing  that  it  does  not  halt,  you  can  use 
an  oscilloscope  to  see  the  activity  on 
the  various  processor  lines  while  the 
monitor  waits  for  a  console  key¬ 
stroke. 

8.  Add  a  6850  ACIA  decoded  at 
$010040  to  serve  as  a  console  port  and 
test  it  with  the  TUTOR  EPROM  set.  Run 
various  memory-testing  commands 
and  scope  loops  to  check  operation  of 
the  new  system. 

The  First  Step 

As  stated  earlier,  the  first  step  is  to 
bring  up  the  kernel  in  the  free-run¬ 
ning  mode.  It  seems  a  bit  over¬ 
whelming  when  you  first  try  doing 
it,  but  it  really  is  quite  simple.  Unless 
you  have  made  a  wiring  error,  the 
68000  is  virtually  guaranteed  to  come 
alive  and  begin  executing  the  NIL  in¬ 
struction.  To  bring  up  the  kernel, 
you  need  the  power  system,  the 
clock  and  drivers,  the  reset  and  halt 
module,  and  the  68000  module. 

The  size  of  the  power  supply  de¬ 
pends  on  the  nature  of  the  system 
and  what  loading  it  will  have  in  the 
final  configuration.  In  my  own  case, 
I  intended  to  use  the  68000  processor 
board  in  an  IEEE-696  (S-100)  system,  so 
I  needed  on-card  regulation  from  an 
8-volt  system  supply.  A  common 
7805  circuit  was  adequate  for  the 
processor  and  its  RAM  and  EPROMs;  I 
used  a  second  7805  circuit  for  the  rest 
of  the  LS-TTL  logic  on  the  CPU  board. 

Watch  the  Motorola  data  manual 
for  footnotes.  In  the  case  of  the  68000, 
although  the  data  indicates  a  power 
requirement  of  300  mA  or  so,  that  is 
not  the  whole  story.  The  fine  print  at 
the  bottom  of  one  page  casually  men¬ 
tions  that  the  68000  might  require  a 
peak  current  of  some  1.5  A.  Make 
sure  the  power  supply  can  handle 
the  peak  current  without  falling  out 
of  regulation.  Likewise,  power  and 


Address 

Data 

Program 

00  0000 

0000  0000 

ORI.B  #0,D0 

00  0004 

0000  0000 

ORI.B  #0,D0 

00  0008 

0000  0000 

ORI.B  #0,D0 

00  oooc 

0000  0000 

ORI.B  #0,D0 

00  0010 

0000  0000 

ORI.B  #0,D0 

FF  FFFC 

0000  0000 

ORI.B  #0,D0. 

Table  1 


Figure  Is  The  68000  kernel  is  the  essential  hardware  for  program  execution. 


Figure  2:  To  free  run  the  68000,  the  normal  feedback  path  from  memory  is 
disconnected,  and  a  NIL  (do-nothing)  instruction  is  substituted. 
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( Continued  from  page  61)  and  capacitors,  and  a  7404  or  similar;  tion;  only  after  1  had  finished  the  sys- 

-  doing  this  is  hardly  worth  the  effort,  tem  did  I  run  it  up  to  10  MHz  and 

ground  leads  to  the  68000  need  to  be  though.  For  prototype  work,  being  later  to  12  MHz. 

heavy,  say  » 24  wire  rather  than  #30  able  to  change  the  clock  frequency  Also,  you  will  use  both  the  clock  sig- 
wire-wrap  wires.  Locate  bypass  ca-  easily  without  redesigning  the  cir-  nal  and  its  complement  in  the  final 

pacitors  close  to  each  of  the  power  cuit  is  a  distinct  advantage,  so  using  a  circuit  design.  The  complement  clock 

and  ground  connections.  DIP  oscillator  is  appropriate.  I  used  a  could  be  derived  from  a  74LS04,  but 

You  can  design  and  build  the  clock  6-MHz  oscillator  in  my  S-100  proto-  that  would  introduce  a  skew  be- 


Figure  3:  Circuit  diagram  of  a  simple  power-up  and  reset  timer  circuit  for  a  68000  processor.  Note  the  use  of  open-col¬ 
lector  devices  on  the  bidirectional  HALT*  and  RESET*  controls  of  the  68000. 
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Figure  4:  Circuit  diagram  of  the  minimum  68000  system  for  free-run  test 
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Figure  S:  Power-up  performance  of  the  555  timer  circuit.  On  power-up,  the  555  timer  with  the  parts  given  in  the  sche¬ 
matic  provides  about  175  ms  PESET*  to  the  68000. 
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Figure  G:  Typical  free  run  starting  from  a  complete  PESET*  and  HALT*  asserted  low.  The  clock  is  running  at  6  MHz. 
DTACK*  is  grounded  in  this  example. 
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Figure  7:  Typical  free  run  with  the  DTACK*  circuit  enabled.  The  clock  is  6  MHz,  and  there  are  no  wait  states  inserted. 
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Figure  8:  'typical  free  run  with  DTACK*  enabled.  This  timing  shows  DTACK*  delayed  enough  to  cause  two  waits  in  each 
bus  cycle. 


Figure  9;  A  view  of  the  bus  activity  when  the  TUTOR  EPROM  set  runs  at  6  MHz.  The  CPU  board  was  set  for  eight  waits  on 
I/O  and  three  waits  otherwise. 


Figure  lO:  A  closer  look  at  the  bus  controls  when  TUTOR  executes  a  write  bus  cycle 
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tween  the  two  clocks  of  some  10  to  15 
ns,  depending  on  loading.  Although 
this  amount  of  skew  seems  slight,  it 
can  cause  severe  timing  difficulties 
when  the  clock  speed  gets  above  10 
MHz,  The  74265  quad  complemen¬ 
tary-output  element  with  a  worst- 
case  skew  of  3  ns  is  a  good  selection;  in 
my  12-MHz  prototype,  this  selection 
has  worked  out  well. 

The  reset  and  halt  module  has  two 
basic  functions.  One  task  is  to  hold 
the  68000  HALT*  and  RESET*  lines  low 
for  at  least  100  ms  on  power-up.  Its 
other  function  is  to  pull  the  same  two 
lines  low  for  at  least  ten  clock  cycles 
for  a  reset  button  press  at  any  time 
after  the  power  has  been  on. 

The  circuit  in  Figure  3  (page  62) 
provides  a  simple  and  reliable  reset 
function  for  the  68000.  It  provides  a 
reset  pulse  either  on  power-up  or 
whenever  you  press  the  reset  button. 
Open-collector  devices  are  required 
because  the  68000  HALT*  and  RESET* 
controls  are  both  bidirectional.  For 
example,  the  68000  can  itself  drive 
the  RESET*  line  to  reset  any  peripher¬ 
als  if  the  software  reset  instruction  is 
issued.  Also,  the  68000  can  force  the 
HALT*  line  low  if  the  system  cannot 
continue  processing.  A  single  "halt” 
LED  connected  as  shown  is  valuable 
in  helping  bring  up  the  processor  for 
the  first  time. 

The  last  module  in  the  minimum 
system  is  the  68000  processor  shown 
in  Figure  4  (page  66).  By  now,  you 
should  have  checked  the  power, 
clock,  and  reset  modules  for  proper 
operation  and  connected  them  ready 
for  the  68000.  If  the  processor  is 
wired  as  shown,  it  should  begin  free 
running  immediately.  On  power-up 
the  HALT  light  should  flash  briefly 
and  then  the  TEST  light  will  begin 
flashing  on  and  off. 

Earlier  I  referred  to  my  so-called 
NIL  instruction.  As  you  see  in  the  cir¬ 
cuit,  the  data  bus  is  completely 
grounded  so  the  NIL  has  an  opcode  of 
0000.  In  the  context  of  its  use  in  free 
running,  it  acts  like  a  no-operation  or 
NOP.  The  68000  does  have  a  NOP  op¬ 
code  ($4E71),  but  this  NOP  will  not 
work  as  a  free-running  instruction. 

A  critical  constraint  on  the  opcode 
precludes  using  the  NOP  instruction 
in  free  running:  Whatever  is  wired 


to  the  data  bus  for  the  68000  to  read 
upon  reset  must  be  even.  The  reset 
sequence  is  this:  The  68000  will  do 
four  16-bit  reads  to  get  the  initial  SSP 
and  PC  vectors;  then  it  will  fetch  its 
first  opcode  at  the  address  in  the  PC. 
If  the  PC  is  not  aligned  on  an  even 
address,  the  68000  detects  an  address 
error  and  immediately  begins  illegal- 
address  exception  processing.  It  tries 
to  push  its  status  on  the  stack  at  the 
beginning  of  the  exception,  but  the 
stack  is  also  an  illegal  address  (the 
same  noneven  number  as  in  the  PC). 
The  result  is  the  fatal  double  bus 
fault  that  stops  all  processing  and  as¬ 
serts  the  HALT*  output. 

The  opcode  0000  does  in  fact  corre¬ 
spond  to  a  real  instruction  in  the 
68000  set.  It  is  the  mnemonic  ORI.B 
#0,D0,  and  it  was  selected  for  free  run¬ 
ning  for  two  reasons:  first,  because  it 
was  even;  and  second,  because  con¬ 
necting  all  grounds  to  the  data  bus 
was  simpler  than  making  sure  one  or 
two  data  lines  had  a  logic  1  on  them. 
When  the  instruction  is  considered 
in  its  free-running  environment,  the 
appearance  of  its  memory  is  as 
shown  in  Table  1  (page  61). 

You  can  calculate  the  execution 
time  of  this  "program”  easily.  Each 
instruction  takes  eight  clock  cycles 
(two  read  bus  cycles),  so  for  a  6-MHz 
clock,  the  execution  time  is  8  X 167  ns 
or  approximately  1.33  microseconds. 
A  complete  sweep  through  the  en¬ 
tire  16  megabytes  of  the  68000  ad¬ 
dress  range  takes  1.33X4  megabytes 
or  about  5.59  seconds.  If  you  connect 
the  TEST  light  to  the  top  address  bit, 
A23,  it  will  be  on  for  2.8  seconds  and 
then  off  for  2.8  seconds.  I  connected 
the  TEST  light  to  A20  permanently.  It 
stays  on  for  0.35  seconds  and  off  for 
0.35  seconds — a  reassuring  flash  rate 
during  development  work  and  not 
nearly  as  unsettling  as  a  constant  red 
HALT  light. 

Results 

Figure  5  (page  68)  shows  the  perfor¬ 
mance  of  the  power-up  timer  circuit. 
The  top  plot  is  the  main  system 
power  as  it  comes  on  and  eventually 
regulates  at  5  volts  on  the  CPU  board. 
About  175  ms  after  the  supply  volt¬ 
age  is  valid,  the  RESET*  and  HALT* 
lines  go  high  to  successfully  com¬ 
plete  a  full  68000  reset. 

The  effect  of  this  reset  operation  is 
shown  in  Figure  6  (page  68).  The  last 
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two  lines  on  the  timing  diagram  are 
the  RESET*  and  HALT*  controls  for  the 
68000.  After  its  internal  start-up  time, 
the  68000  asserts  its  address  strobe 
(AS*)  and  its  data  strobe  lines  (UDS* 
and  LDS*)  in  the  first  read  bus  cycle. 
After  four  read  bus  cycles,  the  pro¬ 
cessor  PC  begins  execution  at  address 
0,  as  discussed  above. 

DTACK*  is  the  asynchronous  bus 
control  line  that  normally  comes 
back  from  memory  or  peripherals  to 
tell  the  68000  to  complete  the  current 
bus  cycle.  During  the  initial  free  run 
of  the  processor,  there  is  nothing 
connected  that  will  acknowledge  a 
data  transfer,  so  the  control  is 
grounded.  The  timing  diagram 
shows  this  line  at  a  logic  low.  The 
timing  diagram  also  shows  the  read/ 


68000 

(Continued  from  page  73) 

write  control,  R/W*,  as  constantly 
high  because  the  68000  only  does  a 
read  bus  cycle  when  it  is  free 
running. 

Figure  7  (page  68)  shows  the  free- 
running  processor  with  a  DTACK* 
generator  in  operation.  Notice  the  o 
and  x  markers  bracketing  a  single 
bus  cycle.  The  normal  read  bus  cycle 
has  a  total  of  four  clock  cycles.  If 
DTACK*  is  delayed  for  two  cycles,  as 
shown  in  Figure  8  (page  70),  then  the 
bus  cycle  is  lengthened  and  two 
"waits”  are  inserted  into  each  bus 
cycle.  When  you  interface  memory 
or  peripherals  to  the  68000,  you  can 
design  each  external  module  to  hold 
back  DTACK*  until  its  unique  timing 
requirements  are  met. 

As  an  example,  the  timing  diagram 
in  Figure  9  (page  70)  shows  the  sys¬ 
tem  while  not  free  running:  It  is  exe¬ 
cuting  the  monitor  program  (TUTOR) 
and  waiting  for  a  keystroke.  The  sys¬ 
tem  was  set  to  provide  eight  waits  for 
I/O  read  operations,  nine  for  writes, 
and  three  waits  otherwise.  Figure  10 
(page  70)  shows  a  close-up  look  at  the 
bus  cycles.  The  lower  timing  line, 
marked  sMl,  is  the  S-100  bus  status 
indicating  an  opcode  fetch. 

Summary 

Bringing  up  the  68000  using  the  free- 
running  technique  is  very  different 
from  the  more  traditional  approach¬ 
es  to  getting  a  processor  running. 
You  can  see,  though,  just  by  the  brief 
description  of  this  first  step  in  bring¬ 
ing  up  the  68000  kernel,  that  you  do 
not  need  sophisticated  equipment  to 
get  started. 

There  is  more  to  be  said  about  all 
the  steps  beyond  this  first  free-run¬ 
ning  processor;  no  doubt  many  ques¬ 
tions  remain  unanswered.  From  my 
experience,  though,  the  understand¬ 
ing  you  can  get  from  doing  a  free- 
running  68000  is  very  valuable,  and  it 
can  help  you  go  on  to  design  and 
build  a  complete  system  successfully. 

Availability 

The  TUTOR  firmware  is  available  di¬ 
rectly  from  the  author. 
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ARTICLES 


COM:  An  8080  Simulator 
for  the  MC68000 


After  I  bought  a  68000-based  S- 
100  system,  I  found  that  I 
needed  to  run  several  CP/M 
2.2  (alias  CP/M-80)  software  packages, 
none  of  which  were  available  in 
equivalent  forms  for  my  machine.  1 
was  faced  with  two  options — either 
buying  another  processor  board  so 
that  1  could  run  these  programs  or 
writing  an  8080  simulator.  The  soft¬ 
ware  approach  seemed  infinitely 
preferable.  This  also  seemed  like  an 
opportune  time  to  find  out  just  how 
fast  my  68000  really  was.  So  1  set  out 
to  write  an  8080  simulator  (which  1 
named  COM  because  it  interprets 
.com  files). 

In  principle,  writing  a  simulator  is 
simple.  You  just  set  up  a  set  of  fake 
registers  and  start  picking  up  opcodes 
and  interpreting  them.  Unfortunate¬ 
ly  it's  the  little  details  that  get  you. 
This  simulator  took  about  twice  as 
long  to  write  as  I  expected.  As  it  is,  it 
isn't  perfect.  In  fact,  it  would  slow 
down  considerably  if  it  were.  Howev¬ 
er,  most  programs  aren't  bothered  by 
the  imperfections,  and  the  speed  dif¬ 
ference  would  be  significant  because 
the  simulation  is  already  on  the  slow 
side  of  usable.  I  wrote  COM  to  run  as 
fast  as  possible. 

The  simulation  speed  is  approxi¬ 
mately  that  of  a  1.4-MHz  Z80  proces¬ 
sor  based  on  a  sample  assembly  with 
MAC.  (My  68000  system  is  an  8-MHz 
CompuPro/Morrow  single-user  hy¬ 
brid  running  CP/M-68K  1.2,  with  16 
bit  no-wait-state  memory.)  Simula¬ 
tion  time  can  vary  widely,  as  some 
8080  instructions  aren’t  easily  simu- 


Jim  Cathey,  ISC  Systems  Corp.,  TAF- 
C8,  Spokane,  WA  99220. 


by  Jim  Cathey 


Simulation  time  can 
vary  widely,  as  some 
8080  instructions 
aren't  easily  simulat¬ 
ed  with  the  68000. 


lated  with  the  68000.  MAC  was  cho¬ 
sen  as  a  typical  example  program. 
LU,  the  public-domain  library  utility 
is  one  of  the  worst  performers.  It 
spends  vast  amounts  of  time  calculat¬ 
ing  CRCs.  This  instruction  sequence 
isn’t  very  efficient  on  the  8080  (using 
a  C  arithmetic  library),  and  the  simu¬ 
lation  magnifies  any  inefficiencies.  I 
didn't  time  LU  for  comparison,  but  I 
thought  that  the  simulation  had 
crashed  because  nothing  seemed  to 
be  happening  for  long  periods.  An¬ 
other  poor  performer  is  WordStar.  I 
tried  simulating  it  because  it  is  so 
popular  and  because  it  gives  the  sim¬ 
ulator  a  thorough  workout.  The  sim¬ 
ulation  works,  and  it  does  so  at  an  ac¬ 
ceptable  performance  level  most  of 
the  time. 

About  the  Program 

The  program  source  is  broken  into 
four  files.  Listing  One  (page  104)  is  the 
first  file,  which  contains  the  start-up, 
command-line,  CP/M-2.2  simulation, 
and  trace  routines.  Listing  Two  (page 
112)  contains  opcode  simulation  sub¬ 
routines  and  flag  tables.  The  rest  of 
the  listings  will  be  continued  in  the 
March  issue. 

The  program  starts  out  by  prompt¬ 


ing  for  the  trace  end  points  if  that 
code  has  been  included.  (There  are 
several  conditional  assembly  trace 
features  in  COM.)  It  then  builds  the 
8080  environment  in  a  64K  buffer 
(biggest  TPA  yet!)  and  initializes  the 
68000  simulation  registers,  with  the 
8080’s  PC  set  to  100H  into  the  buffer. 
It  then  calls  a  subroutine  that  loads 
the  specified  .com  program  into  the 
buffer  and  transfers  the  68000’s  sec¬ 
ond  FCB  to  the  8080’s  first  FCB  and 
passes  the  remains  of  the  command 
tail  to  the  8080’s  DMA  buffer.  If  all 
goes  well,  the  program  then  enters 
the  main  loop  at  label  MLOOP.  Here  it 
fetches  the  next  8080  opcode  and 
uses  it  to  index  into  a  table  of  256 
68000  subroutines  (one  per  opcode — 
big,  but  fast)  and  jumps  to  the  select¬ 
ed  subroutine.  Each  opcode  subrou¬ 
tine  then  picks  up  what  parameters 
it  needs  and  plays  with  the  fake  reg¬ 
isters  appropriately.  Each  subroutine 
then  jumps  back  to  MLOOP,  which  re¬ 
peats  the  process.  This  continues  un¬ 
til  a  service  request  is  picked  up  or 
until  an  illegal  instruction  is  found. 

The  service  request  used  by  the 
simulation  is  the  HLT  opcode  ($76). 
HLT  is  followed  by  a  1-byte  parame¬ 
ter  telling  the  68000  which  action  to 
take.  All  BIOS/BDOS  functions  are  im¬ 
plemented  as  service  requests.  After 
the  service  is  performed,  execution 
continues  at  MLOOP  (or  at  the  byte  fol¬ 
lowing  the  parameter — it  depends 
on  your  point  of  view).  Refer  to  the 
8080  Environment  section  for  more 
details  on  how  service  requests  are 
used  by  the  8080's  BDOS/BIOS. 

Register  dumps  are  caused  by  ille¬ 
gal  opcodes  or  are  done  during  a 
trace.  They  are  easily  interpreted 
(registers  S0-S3  are  the  top  four  en- 
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tries  on  the  stack)  as  the  current  in¬ 
struction  is  also  disassembled.  Illegal 
opcodes  terminate  the  simulation  af¬ 
ter  the  register  dump. 

Flag  simulation  is  done  with  two  ta¬ 
bles.  Because  any  8080  logical  opera¬ 
tion  that  sets  the  parity  flag  also  clears 
the  carry  bit,  these  flag  results  are 
based  solely  on  the  value  in  the  accu¬ 
mulator.  The  simulator  uses  a  256- 
byte  flag  lookup  table  for  these  opera¬ 
tions.  Similarly,  anything  that 
conditionally  sets  carry  (an  arithmetic 
operation)  doesn't  need  to  set  the  pari¬ 
ty  flag  if  the  code  is  intended  to  run 
on  a  Z80.  (This  describes  all  CP/M-2.2 
software  I  was  interested  in.)  Another 
16-byte  table  can  therefore  be  used 
for  arithmetic  flag  results.  The  4-bit 
flag  field  of  the  68000’s  status  register 
is  used  as  the  index  for  this  second  ta¬ 
ble.  The  68000  does  have  an  overflow 
flag,  so  this  is  substituted  for  the  pari¬ 
ty  bit  of  the  8080  (exactly  as  in  the 
Z80).  This  causes  one  problem  that  is 
discussed  in  the  Known  Faults  sec¬ 
tion.  Treatment  of  the  half  carry  bit  is 
also  discussed  later  because  it  doesn't 
fit  into  either  of  the  tables. 

The  CP/M-80  environment  simula¬ 
tion  is  greatly  simplified  (to  my  great 
disappointment)  by  the  strong  re¬ 
semblance  of  CP/M-68K  to  CP/M-80. 
Most  of  the  calls  are  directly  translat¬ 
able.  There  are  a  few  exceptions, 
though,  and  they  require  the  bulk  of 
the  code. 

1.  Any  call  referencing  an  FCB  re¬ 
quires  that  the  byte  order  of  the  Ran¬ 
dom  Record  field  be  switched,  if  the 
call  uses  that  field. 

2.  CP/M-68K  can  t  open  a  file  in  any 
but  the  base  extent.  You  have  to 
change  such  requests  to  an  open  in 
the  base  extent  and  then  do  a  Ran¬ 
dom  Read  to  the  point  you  wanted. 

3.  Direct  console  I/O  (BDOS  *6)  un¬ 
der  CP/M-80  returns  a  null  flag  if  no 
character  is  available.  CP/M-68K 
waits  for  a  character.  A  status  check 
is  performed  first,  and  if  a  character 
is  ready,  it  is  fetched  and  returned  to 
the  simulation.  Otherwise  just  a  null 
status  is  returned. 

4.  Any  call  referencing  an  address 
(DMA  or  otherwise)  needs  to  have  that 
address  translated  to  point  into  the 
8080’s  code  buffer.  (This  is  a  problem 
inherent  to  the  simulation  because 
the  8080  buffer  cannot  be  placed  in 
system  memory  at  address  0.) 

Some  instruction  simulations  don’t 


do  what  you  think  they  might.  Spe¬ 
cifically  the  El  and  DI  instructions  do 
not  translate  to  the  equivalent  68000 
sequences.  The  object  of  using  DI/EI 
pairs  in  an  8080  program  is  to  pre¬ 
vent  time-critical  code  from  being  in¬ 
terrupted  or  to  prevent  resource  con¬ 
tention  between  interrupt  routines 
and  background  processes  that  share 
resources.  Because  there  are  no  8080 
“interrupts”  possible  under  COM, 
there  is  nothing  to  block.  (We  won't 
even  talk  about  simulating  time-criti¬ 
cal  code!) 


A  few  Z80  simulation  routines  are 
used  in  COM  because  of  the  overflow/ 
parity  flag  problem  discussed  below. 
These  are  just  an  extension  of  the  ta¬ 
ble  approach  used  for  the  8080 — a 
large  jump  table  and  a  bunch  of  sub¬ 
routines.  Extension  to  a  full  Z80  simu¬ 
lation  is  straightforward  but  would 
require  a  lot  of  code  if  the  present 
jump  table  technique  is  kept. 

Another  approach  to  simulating 
instructions  involves  dividing  the  op¬ 
codes  into  classes,  e.g.,  all  MOVs  han¬ 
dled  by  one  subroutine  that  figures 
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out  what  to  move  where  by  examin¬ 
ing  the  opcode  in  further  detail. 
Though  this  is  much  smaller  code¬ 
wise  than  having  the  63  similar  sub¬ 
routines  that  I  used,  it  also  suffers  a 
speed  penalty  that  I  just  couldn't  tol¬ 
erate.  I  didn’t  buy  a  68000  just  to  slow 
it  down! 

Known  Faults 

There  are  two  problems  with  the  sim¬ 
ulation  of  the  8080  s  flags.  The  first  is 
that  the  flags  are  more  like  those  of 
the  Z80  than  the  8080  in  that  the  pari¬ 
ty  flag  reflects  overflow  status  after 
arithmetic  operations  rather  than 
parity.  This  fools  some  dynamically 
selected  run-time  packages  such  as 
the  one  used  for  BDS-C.  There  is  mini¬ 
mal  Z80  support  in  COM  to  handle  the 
few  extra  instructions  that  BDS-C 
wants  to  use  (LDIR  and  LDDR)  so  that 
programs  compiled  by  it  will  run. 
(CPIR  was  also  required  by  another 
program  for  the  same  reason.)  This 
Z80  support  could  be  extended  as 
much  as  needed — up  to  and  includ¬ 
ing  full  Z80  simulation. 

The  other  flag  problem  is  with  the 
half  carry  bit.  Simulating  it  would 
take  a  lot  of  overhead  because  there 
is  no  similar  flag  in  the  68000.  There¬ 
fore,  assuming  the  only  need  for  the 
flag  is  for  the  DAA  instruction,  this  in¬ 
struction  is  treated  specially.  Instruc¬ 
tions  that  set  the  half  carry  bit  mean¬ 
ingfully  (adds,  ADCs,  and  INR  As)  have 
additional  code  to  store  away  the  two 
operands  and  CY  (if  used)  in  special 
locations.  The  DAA  simulation  then 
recreates  the  HCY  bit  out  of  these 
stored  values.  A  problem  can  arise 
when  the  flags  are  pushed  and  then 
pulled  before  the  DAA  is  executed — 
an  incorrect  HCY  is  created  if  another 
addition-type  operation  occurs  while 
the  flags  are  supposedly  saved.  In 
practice,  I  only  ran  into  this  problem 
when  using  the  8080  DDT  to  trace 
through  a  DAA  instruction.  Be  fore¬ 
warned.  If  required,  the  simulation 
could  be  extended  to  eliminate  this 
problem  by  proper  simulation  of  the 
HCY  bit,  but  this  would  slow  the 
arithmetic  routines  down  quite  a  bit. 

BIOS  calls  to  the  disk  drivers  aren’t 
allowed.  I  did  this  for  safety  reasons 
more  than  anything  else — I  didw't 
want  possibly  buggy  simulations 


playing  with  my  hard  disk  without 
the  protection  of  my  BDOS.  This  limi¬ 
tation  could  easily  be  removed. 

BDOS  call  *31  (Get  DPH  address)  isn't 
supported.  I  didn’t  need  this  for  any 
program  I  wanted  to  use  so  it  was  left 
out.  Including  it  would  involve  get¬ 
ting  the  table  from  the  68000,  copying 
it  to  somewhere  where  the  "8080” 
could  find  it,  and  then  returning  a 
pointer  to  this  copy  of  the  table.  Simi¬ 
larly  function  *27  (Get  ALLOC  vector) 
isn’t  supported  either.  Using  either  of 


these  calls  will  cause  an  abort  and  an 
appropriate  error  message. 

The  IOBYTE  and  LOGIN  vectors  at  3 
and  4  aren't  supported. 

Only  one  parsed  FCB  is  supplied  in 
the  8080’s  base  page.  The  normally 
present  second  name  at  $6C  isn't 
parsed.  (Note  that  CP/M-68K  parses 
two  full  FCBs  when  COM  is  invoked. 
The  first  is  the  name  of  the  .com  pro¬ 
gram  to  run,  and  the  second  is  used 
as  this  program’s  first  FCB.  CP/M-80’s 
second  "FCB”  isn't  one — it  is  only  an- 


WARMST: 


BDOS: 


BIOS: 


WBOOT: 


CONST: 


CONIN: 


CONOUT: 


LIST: 


ORGO 
JMP  BIOS 

ORG5 
JMP  BDOS 

ORG  0FF00H 
HLT 
DB  0 
RET 

JMP  WBOOT 
JMP CONST 
JMP  CONIN 
JMP CONOUT 
JMP  LIST 
JMP PUNCH 
JMP  READER 
JMP  HOME 
JMP  SELDSK 
JMP  SETTRK 
JMP  SETSEC 
JMP  SETDMA 
JMP READ 
JMP  WRITE 
JMP  LISTST 
JMP  SECTRN 

HLT 
DB  1 
RET 

HLT 
DB  2 
RET 

HLT 
DB  3 
RET 

HLT 
DB  4 
RET 

HLT 
DB  5 
RET 


;  Service  request. 

;  0  is  BDOS  call,  else  BIOS. 


;  Service  Request 
;  Passed  to  68K  BIOS  (BIOS  #1) 


;  BIOS  #2  (etc.) 


Table  1 
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other  name  field  in  the  first  FCB.  I 
didn't  find  anything  that  needed  it, 
so  I  didn't  go  to  the  trouble  of  picking 
another  name  out  of  the  68K's  com¬ 
mand  tail.) 

An  additional  complication  inher¬ 
ent  to  the  simulation  arises  when  you 
try  to  use  programs  running  under 
COM  to  drive  DMA  devices.  The  hard 
disk  controller  in  my  system  is  a  Mor¬ 
row  HD/DMA.  In  order  for  the  8080 
simulation  to  be  able  to  drive  this  con¬ 
troller,  all  addresses  passed  to  the 


Table  I 

79 
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board’s  DMA  circuitry  must  undergo 
translation  so  that  they  point  to  the 
buffers  in  the  "8080”  program  space, 
not  the  68000’s!  Handling  this  tends  to 
require  a  lot  of  code  specific  to  each 
device  supported,  but  it  can  be  done. 
(COM  was  originally  written  for  two 
reasons:  to  develop  firmware  for  the 
8085  used  in  my  system's  keyboard 
and  to  run  the  Morrow  FORMATMW 
[hard  disk  formatter]  program.  Trac¬ 
ing  this  program  pointed  out  the  er¬ 
ror  in  the  HD/DMA  documentation 


that  kept  my  own  formatting  pro¬ 
gram  from  working.)  There  is  a  condi¬ 
tional  assembly  flag  in  COM  to  include 
the  support  for  the  Morrow  control¬ 
ler.  You  probably  will  never  want 
this  option,  but  I  left  the  code  in  to 
serve  as  an  example  of  extending 
COM  to  support  a  DMA  device. 

SOSO  Environment 

The  8080  Environment  is  a  64K  buff¬ 
er,  of  which  all  but  512  bytes  are 
available  as  TPA.  This  is  probably  the 
only  real  advantage  of  the  simulation 
over  real  execution.  The  fake  BIOS/ 
BDOS  (FDOS)  starts  at  8080  address 
SFF00  and  is  in  the  form  of  a  jump 
table  followed  by  a  service  request  ta¬ 
ble.  The  warmstart  and  BDOS  jumps 
in  the  low  page  of  the  buffer  point  to 
these  tables.  There  is  no  CCP  because 
COM  takes  its  place.  The  8080  form  of 
the  FDOS  is  shown  in  Table  1  (page  78). 

The  service  request  handler  per¬ 
forms  a  BIOS  call  to  the  68000  if  the 
parameter  following  HLT  is  not  zero 
or  a  BDOS  call  if  the  parm  is  zero.  In 
either  case  the  appropriate  parame¬ 
ters  from  the  fake  8080  registers  are 
translated  (if  required)  and  passed  to 
the  68000  FDOS.  The  return  values  are 
then  translated  (if  required)  and 
stuffed  into  the  8080's  pseudoregis¬ 
ters,  and  the  simulation  is  continued. 

Using  COM 

CP/M-80  programs  are  run  by  insert¬ 
ing  the  word  COM  in  the  normal  com¬ 
mand  line.  Examples  of  use  are: 

A>COM  WS  TEST.ASM 
A>COM  MAC  TEST 
A>COM  LOAD  TEST 
A>COM  DDT  TEST.COM 
A>COM  LU  -O  JUNK  -A  TEST.COM 
A>COM  LDIR  JUNK 
A>COM  MBASIC  FFT.BAS 

COM  may  be  assembled  with  sever¬ 
al  optional  trace  facilities.  Normally  I 
create  a  separate  version  called 
COMT  because  the  presence  of  the 
trace  code  slows  down  the  simula¬ 
tion.  A  trace  is  specified  by  giving  the 
full  normal  command  line  and  then 
answering  the  prompts  for  the  start 
and  stop  trace  addresses.  COMT  will 
check  each  address  before  it  simu¬ 
lates  the  opcode  at  that  address  for  a 
match  with  either  of  the  two  limits 
and  turn  on  or  off  the  register  dump 
appropriately.  An  example  is  shown 
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(Continued  from  page  78) 

PUNCH: 

HLT 

DB  6 

RET 

READER: 

HLT 

DB  7 

RET 

HOME: 

HLT 

DB  8 

RET 

;  Normally  blocked  by 
;  the  simulation. 

SELDSK: 

HLT 

DB  9 

RET 

;  Ditto,  etc. 

SETTRK: 

HLT 

DB  10 

RET 

SETSEC: 

HLT 

DB  11 

RET 

SETDMA: 

HLT 

DB  12 

RET 

READ: 

HLT 

DB  13 

RET 

WRITE: 

HLT 

DB  14 

RET 

LISTST: 

HLT 

DB  15 

RET 

;  This  one  is  allowed. 

SECTRN: 

HLT 

DB  16 

RET 

END 

A>COMT  TEST 

Start  trace  at  >5 

Stop  trace  at  >ff02 

-AF-  -BC-  -DE-  -HL- 

-SP- 

-SO- 

-SI- 

-S2- 

-S3- 

-PC- 

-op- 

2300  4509  0200  0000 

FFFE 

0000 

0000 

0000 

0000 

0005 

C3 

JMP  FF00 

-AF-  -BC-  -DE-  -HL- 

-SP- 

-SO- 

-SI- 

-S2- 

-S3- 

-PC- 

-op- 

2300  4509  0200  0000 
Printed  by  BDOS  #9 

FFFE 

0000 

0000 

0000 

0000 

FF00 

76 

HLT 

-AF-  -BC-  -DE-  -HL- 

-SP- 

-SO- 

-SI- 

-S2- 

-S3- 

-PC- 

-op- 

2300  4509  0200  0000 

A> 

FFFE 

0000 

0000 

0000 

0000 

FF02 

C9 

RET 

8080  SIMULATOR 

(Continued  from  page  79) 


in  Table  2  (page  81).  The  tracing  ad¬ 
dresses  in  this  figure  will  trace  every 
BDOS  call  made  by  the  program. 

The  code  for  address  prompting  is 
rather  stupid — it  doesn't  use  line- 
buffered  I/O.  Because  I  almost  never 
use  tracing  now  that  COM  works,  I 
didn’t  bother  to  fix  this  up.  (The  code 
was  pulled  out  of  my  ROM  monitor, 
where  I  didn't  necessarily  have  any 
RAM  for  a  buffer,  which  explains  its 
strange  structure.) 

Other  tracing  code  may  be  includ¬ 
ed  in  COMT.  There  is  support  for 
dumping  (to  the  printer)  FCB  calls  to 
the  BDOS  and  for  including  a  register 
dump  at  this  time.  All  of  these  trace 
options  were  useful  in  debugging  the 
simulation.  You  probably  won  t  need 
them,  but  they  illustrate  one  advan¬ 
tage  of  the  simulation  over  the  real 
thing — you  can  monitor  events  at  any 
level  of  detail  you  want,  provided  you 
don’t  need  real-time  execution. 

Teaching  the  Assembler 
Tricks  (With  a  Hammer) 

This  section  describes  some  of  the 
tricks  I  used  to  make  the  ALCYON  as¬ 
sembler  (AS68)  that  is  distributed 
with  the  CP/M-68K  package  do  what  I 
wanted  when  writing  COM.  Also  de¬ 
scribed  are  some  other  tricks  that  I 
have  used  successfully  in  other  as¬ 
sembly  programs.  (AS68  is  also  the  as¬ 
sembler  distributed  with  the  Atari 
520ST  developer's  package.) 

At  the  beginning  of  Listing  One  are 
the  register  definitions  used  by  COM. 
The  form  of  these  definitions  was 
picked  out  of  the  AS68INIT  file  that 
you  use  the  first  time  you  run  AS68. 
These  definitions  allow  you  to  refer 
to  the  68000  registers  with  more 
meaningful  names  than  just  "D3”  and 
so  on.  The  only  real  disadvantage  of 
using  names  is  that  it  is  easy  to  forget 
which  registers  are  in  use  and  acci¬ 
dentally  use  one  as  a  temporary  that 
should  have  been  saved  first.  Proper 
documentation  helps  in  this.  You  also 
cannot  use  these  new  names  in  a 
Teg"  directive. 

One  problem  with  these  names 
(and  all  other  "equ”  defined  symbols) 
is  that  you  can't  define  them  as  glob¬ 
al  and  use  them  in  another  file.  The 
declarations  must  be  repeated  in 
each  source  file. 


Table  2 

Because  of  the  conditional  assem¬ 
blies  in  COM,  I  needed  to  place  some 
labels  on  lines  by  themselves,  partic¬ 
ularly  MLOOP,  the  main  looping  point 
of  the  opcode  simulation.  Though 
the  assembler  allows  this  (provided 
you  put  a  colon  after  the  label),  I  was 
unable  to  make  the  label  global  using 
the  ".globl”  directive.  However,  if 
you  do  something  like  this: 

.globl  mloop 
mloop: 

- mloop:  ;  Why?  I  don't  know! 

you  can  get  the  declaration  to  work. 
This  trick  was  found  by  examining 
the  code  produced  by  the  C  compil¬ 
er.  I  believe  that  if  the  label  is  in  up¬ 
percase  you  don’t  need  this  extra 
statement.  Note  that 

.globl  mloop 
mloop:  equ  * 

won’t  work  because  of  the  problem 
with  "equ”  described  earlier. 

The  "offset”  directive  is  extremely 
useful  for  generating  data  storage  ar¬ 
eas  to  be  used  with  indexing.  It  would 
have  been  useful  in  COM,  but  it 
doesn't  work.  "Equ”  must  be  used, 
and  the  programmer  must  count 
bytes  in  the  storage  areas  to  make 
sure  nothing  overlaps.  Grrrrr.  "Off¬ 
set”  wasn’t  accepted  by  the  CP/M-68K 
Release  1.1  assembler.  The  Release  1.2 
assembler  works  just  fine — but  nei¬ 
ther  linker  will  accept  symbols  de¬ 
fined  in  offset  sections.  Another  "fea¬ 
ture”  to  fix.  Doesn't  DRI  test  anything? 

Another  trick  that  may  be  useful  in 
68000  assembler  programming  is  us¬ 
ing  the  ".opd”  directive  to  generate 
your  own  opcodes.  These  are  partic¬ 
ularly  useful  as  stand-ins  for  less 
meaningful  ".dc.w  constant"  se¬ 


quences  when  generating  data  ta¬ 
bles,  although  you  may  define  in¬ 
structions  also.  COM  uses  this  trick  to 
define  the  68000's  BDOS  and  BIOS  trap 
instructions.  Look  at  the  file  AS68INIT 
for  more  examples  of  its  use.  The 
only  restriction  for  use  is  that  the 
new  opcode  must  follow  the  address¬ 
ing  rules  of  one  of  the  existing  68000  s 
instructions.  Oh,  for  a  true  macro 
assembler.  .  .  . 

The  C  preprocessor,  CP68,  may  be 
used  as  a  poor  man’s  macro  assem¬ 
bler.  If  the  assembly  file  (let's  say 
TEST.MAC)  looks  something  like  this: 

^include  "MACRO.H” 
label  testmac(l,2,3) 
end 

and  the  file  MACRO.H  looks  like  this: 

*  File  produced  by  using  CP68  as  a 
macro 

*  assembly  preprocessor  on  a  .MAC 
file. 

^define  testmac(x,yz)  dc.w  x  \ 

.dc.w  y  \ 

.dc.w  z 

and  if  the  files  are  processed  like  this: 
A>CP68  TEST.MAC  TESTS  ;  CP/M  1.1 
or 

A>CP68  -P  TEST.MAC  TESTS  ;  CP/M  1.2 

then  the  output  file  (TESTS)  will  look 
like  this: 

*  File  produced  by  using  CP68  as  a 
macro 

*  assembly  preprocessor  on  a  .MAC 
file. 
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<cr> 

<cr> 

<cr> 

label 

.dc.w  1 

.dc.w  2 

.dc.w  3 

end 

The  <cr>  lines  are  additional 
blank  lines,  one  for  each  of  the  lines 
of  a  ^define  in  the  .H  file. 

Notes 

The  principal  reference  for  the  8080 
model  was  the  MCS-80/85  Family  Us¬ 
er's  Manual  by  Intel  Corporation. 

This  program  is  released  to  the 
public  domain  with  the  stipulation 
that  it  be  used  for  noncommercial 
purposes  and  that  appropriate  credit 
be  given  in  any  upgrade. 

DDJ 

(Listings  begin  on  page  104) 

Reader  Ballot 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  5. 


C  CHEST  LISTING 


(Text  begins  on  page  18) 

1  finclude  <stdio.h> 

2  ^include  <dir.h> 

3  ^include  <process.h> 

4  ^include  <errno.h> 

5  ^include  <fcntl.h> 

6  ^include  <signal.h> 

7  tinclude  <dos.h> 

8 

SH.C:  A  shell  for  MSDOS . 


9  / 
10 
11 
12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 


Copyright  (C)  1985  Allen  I.  Holub.  All  rights  reserved. 


This  file  contains  an  MSDOS  shell  that  operates  in  conjunction 
with  command.com.  It  has  several  built-in  commands  (see  below) . 
It  recognizes  several  semi-colon  seperated  commands  on  a  line 
&  does  wild  card  expansion.  It  can  take  commands  interactively 
or  from  the  command  line  (but  command.com  will  intercept  the 
re-direction  if  you  have  any  on  the  command  line) .  It  supports 
simple  batch  files  and  will  expand  several  $  arguments. 

It  does  not  support  redirection  yet. 


Usage:  sh  [-cvx]  <args> 

Invocation: 


sh 

sh 


sh  -c  <string> 


shell  entered  in  interactive  mode.  If  -i  is  given 
any  command  line  arguments  that  follow  will  be 
assigned  to  $0  $1  etc.  $0  will  point  at  the 
leftmost  argument  following  the  -i . 

commands  are  read  from  string.  If  several  strings 
are  present  they  are  concatenated  together  before 
execution.  The  'c'  may  be  upper  or  lower  case. 

sh  <file>  args...  commands  are  taken  from  <file>.  Args  are  expanded 
to  correspond  to  $0  $1  etc  inside  the  file.  For 
DOS  compatability  %0  %1  etc  are  also  recognized. 

$0  will  be  <file>  itself. 

sh  -q  Strip  quotes  from  quoted  argument  strings.  Usually 

they're  left  in  so  that  a  spawned  process  can 
assemble  its  argv  correctly. 

sh  -v  Print  input  lines  to  the  shell  as  they  are  read 

(same  as  "set  verbose-1") . 

sh  -x  Print  lines  as  they  are  executed,  (same  as 

saying  "set  echo-1"  in  the  shrc.bat  file. 


Enviornment  variables : 


55 

* 

CMDLINE 

(set) 

Holds  the  complete,  2048  byte,  command  line 

56 

* 

that  can't  be  passed  via  MSDOS. 

57 

* 

PROMPT 

(used) 

Defines  the  prompt  string.  Any  character 

58 

* 

or  $<arg>  may  be  used.  Default  prompt  is 

59 

* 

[$s:$p] . 

60 

* 

SHLEV 

(set) 

Current  shell  level  (0  is  outermost) .  Remember 

61 

* 

that  batch  files  are  executed  in  their  own 

62 

* 

shell. 

63 

* 

SWITCHAR 

(used) 

Use  first  character  in  line  to  designate 

64 

* 

command  line  switches . 

65 

66 

67 

68 

69 

70 

71 


*  Files: 


/shrc.bat  Executed  every  time  a  shell  is  created. 

*  /login. bat  Executed  when  a  level  0  shell  is  created. 

*  /logout. bat  Executed  when  "logout"  command  is  executed 

*  _ _ _ — — _ _ _ 

*  Built  in  commands: 


72 

* 

alias 

[name  [wordlist]] 

73 

* 

cd 

<directory  name> 

74 

* 

exit 

75 

* 

history 

76 

* 

logout 

77 

* 

pwd 

78 

* 

rem 

79 

* 

setenv 

<name>  [-]  <value> 

80 

* 

set 

[ ( cmd | echo | verbose  I $arg ; 

81 

* 

shift 

82 

* 

unalias 

<name> 

83 

* 

unset 

<name> 

84 

* 

i  ii  ] 

!  <num>  !<pat> 

[-  val]] 


85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 


*  A  A  A  <num> 
!>  [name] 

!<  [name] 

* 


~<pat> 


Pre-defined  shell  variables  (may  use  either  %  or  $)  : 

$<num>  one  argument  in  batch  file.  $0  is  file  name. 

$*  All  the  $<num>s  concatantated  with  spaces  between  them. 

$p  Full  path  name  of  current  directory. 

$ !  Current  History  number . 

$s  Nesting  level  of  current  shell.  0  is  the  outermost 


99  *  Special  characters: 


100 

101 

102 

103 

104 

105 

106 


Used  to  delimit  two  commands  on  one  line. 

*?  Name  containing  these  is  expanded  to  matching  directory 

entry. 

Special  characters  aren't  recognized  in  quoted  strings  or 
when  preceeded  by  a  backslash. 

All  lines  with  *  in  the  left-most  column  are  ignored. 
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107  * - 

108  */ 

109 

110  extern  int  access  (char*,  int  ) ;  /*  in  stdio  library  */ 

111  extern  int  bdos  (int,  int,  int  ); 

112  extern  int  chdir  (char*  ); 

113  extern  int  errno; 

114  extern  FILE  *fopen  (char*,  char*  ); 

115  extern  int  fseek  (FILE*,  long,  int  ); 

116  extern  long  ftell  (FILE*  ); 

117  extern  char  *getenv  (char*  ); 

118  extern  char  *getcwd  (char*,  int  ); 

119  extern  char  *malloc  (unsigned  ); 

120  extern  int  putenv  (char*  ) ; 

121  extern  int  (  "signal  (int, int (*) () )  ) () 

122  extern  int  strlen  (char*  ) ; 

123  extern  char  *strpbrk  (char*,  char*  ) ; 

124 


125  /*  source  is  in:  */ 

126  extern  char.  *cpy  (char*,  char*  );  /*  /src/tools/cpy .c  */ 

127  extern  void  del_dir  (DIRECTORY  *  ) ;  /*  /src/tools/dir .c  */ 

128  extern  void  dir  (char*,  DIRECTORY*  );  /*  /src/tools/dir .c  */ 

129  extern  char  *efgets  (char*,  int,  FILE*);  /*  /src/tools/efgets .c  */ 

130  extern  DIRECTORY  *mk_dir  (int  );  /*  /src/tools/dir .c  */ 

131  extern  char  "next  (char**,  int,  int  );  /*  /src/tools/next . c  */ 

132  extern  char  *skipto  (int,  char*,  int  );  /*  /src/tools/skipto .c  */ 


133  extern  char  "strsave  (char*  );  /*  /src/tools/strsave . c  */ 

134  extern  int  unargv  (int, char**, char*, int, int) ;  /*  /src/tools/unargv.c  */ 

135 

136  extern  void  unsetvar (  char*  );  /*  ./var.c:  */ 

137  extern  int  setvar(  char*,  char*  ); 

138  extern  void  printalias ( ) ; 

139  extern  void  printvars(); 

140  extern  int  getvar (char**,  char**,  int*); 

141 

142  extern  void  print_hist (FILE* ) ;  /*  ./hist.c  */ 

143  extern  int  get_hnum(); 

144  extern  void  history (  char*,  int); 

145 

146  /* - */ 

147 

148  #ifdef  DEBUG 

149  static  int  Lev  -  -1; 

150  *  define  TRACE (p)  printf("%*s{  entering  %s\n"  ,++Lev  *  4,  p) 

151  t  define  END_TRACE (p)  printf ("%*s j  exiting  %s\n"  ,Lev —  *  4,  p) 

152  t  define  DIAG (f , a )  printf (f, a) 

153  telse 

154  t  define  TRACE (p) 

155  t  define  END_TRACE (p) 

156  #  define  DIAG (f, a) 

157  tendif 

158 

159 

160  tifdef  STR_CMDS 

161  t  define  PSTR(subr, str)  printf ("%s  <%s>\n",  subr,  str) ; 

162  telse 

163  t  define  PSTR( subr,  str) 

164  #endif 

165 


166  /* - */ 

167 

168  tdefine  VER  "1.0"  /*  Version  number  */ 

169 

170  tdefine  DOSMAXLINE  127  /*  Maximum  line  number  permitted  by  DOS  */ 

171  #define  MAXLINE  (2048+1)  /*  Largest  input  command  line  in  bytes  +1  */ 

172  tdefine  MAXDIR  128  /*  Largest  number  of  objects  on  cmd  line  */ 

173  tdefine  CNTL_Z  ( '  Z  '  —  "  ) 

174  tdefine  COMMENT  't'  /*  Deliniates  comments  */ 


175 

176  tdefine  ISQUOTE(c)  ((c)  — M"  ||  (c)  — *\") 

177  tdefine  ISWHITE(c)  ((c)  —  '  '  ||  (c)  — '\t') 

178  tdefine  SKIPWHITE(p)  while  (  ISWHITE(*p)  ){  p++;  ) 

179  tdefine  ISVAR(c)  (  (c)  — '$'  ||  (c)  — '  % ■  ) 

180 


181  /*  Possible  modes  in  which  shell  can  operate  */ 

182  tdefine  FILEMODE  0  /*  Get  input  from  a  file  */ 

183  tdefine  INTERACTIVE  1  /*  Get  input  interactively  from  stdin  */ 

184  tdefine  COMMAND  2  /*  Get  input  from  the  command  line  */ 


185 

186  tdefine  PMODEO  (  Mode — COMMAND  ?  "COMMAND"  :  \ 

187  (Mode— FILEMODE  ?  "FILE"  :  "INTERACTIVE")  ) 

188 

189  /* - 

190  *  Token  definitions  for  built-in  commands. 

191  */ 

192 

193  typedef  enum 

194  { 

195  ALIAS, 

196  CD, 

197  CMD, 

198  EXIT, 

199  HISTORY, 

200  LOGOUT, 

201  PWD, 

202  REM, 

203  SET, 

204  SETENV, 

205  SHIFT, 

206  UNALIAS, 

207  UNSET 

208  }  TOKEN; 

209 

210  /* - 

211  *  Global  variables: 

212  */ 

213 

214  static  char**  Numv  ;  /*  Vector  array  for  expanding  $<num>  vars  */ 

215  static  int  Numc  -  0;  /*  count  of  valid  entries  in  the  above  */ 

216  static  char  Ibuf (MAXLINE ] ;  /*  Input  buffer  */ 

217 

(Continued  on  nejct  page) 
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(Listing  Continued,  text  begins  on  page  18) 


218 

219 

220 
221 
222 

223 

224 

225 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 

239 

240 

241 

242 

243 

244 

245 

246 

247 

248 

249 

250 

251 

252 

253 

254 

255 

256 

257 

258 

259 

260 
261 
262 

263 

264 

265 

266 

267 

268 

269 

270 

271 

272 

273 

274 

275 

276 

277 

278 

279 

280 
281 
282 

283 

284 

285 

286 

287 

288 

289 

290 

291 

292 

293 

294 

295 

296 

297 

298 

299 

300 

301 

302 

303 

304 

305 

306 

307 

308 

309 

310 

311 

312 

313 

314 

315 

316 

317 

318 

319 

320 

321 

322 

323 

324 


static  int 
static  int 
static  int 
static  int 
static  int 
static  int 


Cmd 

Switchar 

Verbose 

Echo 

Noquotes 

Shlev 


static  char  ^Filename 


1  ;  /*  Generate  CMDLINE  env  with  spawned  proc  */ 
1 I*  Designates  command  line  switches  */ 

0;  /*  Print  input  lines  as  they're  read  -v  */ 

0;  /*  Print  commands  as  they're  executed  -x  */ 

0;  /*  Strip  "  or  '  from  quoted  args  -q  */ 

-1;  /*  Nesting  level  of  the  current  shell  */ 

0;  /*  Full  path  name  of  file  specified  in  */ 

/*  Filemode  input.  */ 


Set  up  input  mode  for  file  mode  processing.  Note  that  Last_posn  and 
Ateof  are  used  by  f ile_input ( ) . 


char 

static  int 
static  char 
static  long 
static  int 


*file_input  ()  ; 
Mode 

*  (*Ifunct)  () 

Last_posn 

Ateof 


-  FILEMODE 

-  file_input  ; 

-  0L  ; 

-  0  ; 


reset_fileinput  () 

{ 

Last_posn  -  0L 

Ateof  -  0 

Mode  -  FILEMODE 

Ifunct  -  file_input 

} 


Making  isdigit  into  a  subroutine  makes  processing  marginally 
easier  in  exp_vars  (below) . 


digit (c) 

{ 


return (  ' 0 ' <-  c  &  &  c  <-  ' 9 '  ) ; 


Input  functions: 


interactive_input () 
comma nd_in put ( ) 
file_input () 


Gets  input  from  keyboard 
Gets  input  from  cmd  line 
Gets  input  from  a  file. 


char 

{ 


Only  one  of  the  three  will  be  used  depending  on  the  way  that 
the  shell  was  invoked.  All  three  return  0  on  end  of  input,  a 
pointer  to  the  beginning  of  the  current  input  line  on  success. 
The  input  line  will  have  been  loaded  into  the  global  array 
Ibuf,  which  is  assumed  to  be  dimensioned  to  MAXLINE  characters. 


*interactive_input ( ) 
register  char  *rval  -  NULL; 

TRACE ("interactive_input") ; 

*Ibuf  -  0; 

if (  efgets ( Ibuf,  MAXLINE,  stdin)  ) 
rval  -  Ibuf  ; 

END_TRACE ("interactive_input") ; 
return  rval; 


char 

{ 


*command_input () 
static  int 


have  been  called  -  0  ; 

-  NULL 


char 

{ 


register  char  *rvaT 

TRACE (  "command_input"  ); 

if(  !have_been_called  ) 

{ 

unargv(  Numc,  Numv,  Ibuf,  MAXLINE,  '  1  ); 

rval  -  Ibuf  ; 

have  been  called++; 


END_TRACE (  "command_input"  ) ; 
return  rval; 


*  file_input () 

/*  Get  input  for  file  mode.  This  kludge  is  required  because 

*  a  child  process  will  close  any  open  files  when  it  exits. 

*  Consequently  we  open  the  file,  get  a  line,  remember 

*  the  position  within  the  file,  and  then  close  the  file 

*  on  each  call.  On  the  next  call  we'll  return  to  the 

*  position  we  remembered  in  the  previous  call. 


register  char 
register  FILE 


*rval 

*fp; 


TRACE (  "file_input"  ); 

if (  lAteof  ) 

{ 

if(  ! (fp  -  f open (Filename,  "r"))  ) 

fprintf (stderr, "Sh:  Can't  open  batch  file  <%s>\n" 

Filename) ; 
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48 


325 

326 

327 

328 

329 

330 

331 

332 

333 

334 

335 

336 

337 

338 

339 

340 

341 

342 

343 

344  ) 

345 

else  if(  ! fseek (fp,  Last_posn,  0)  ) 

{ 

/*  Get  a  line  from  the  buffer.  Note  that  if  the 

*  file  doesn't  have  it's  last  line  terminated 

*  with  a  carriage  return,  efgets  will  return 

*  true  even  though  we're  at  end  of  file 

*  thus  the  call  to  feof. 

*/ 

*Ibuf  -  0; 

rval  -  efgets (Ibuf,  MAXLINE,  fp)  ?  Ibuf  :  NULL  ; 
if(  ! (Ateof  -  feof (fp) )  ) 

Last_posn  -  ftell(  fp  )  -  1; 
fcloae(  fp  ); 

) 

> 

END_TRACE(  "file_input"  ); 
return (  rval  ) ; 

347 

348  int 

has  wild (  bp  ) 

349  register  char 

*bp; 

350  { 

351 

/* 

Return  true  if  the  string  has  a  *  or  ?  in  it 

352 

*/ 

353 

354 

for  ( ; 

*bp  ;  ++bp) 

355 

if(  *bp  —  '*'  II  *bp  —  ) 

356 

return  1; 

357 

358 

return 

0; 

359  ) 

360 

362 

363  int 

8trip( 

src  ) 

364  register  char 

*src; 

365  { 

366 

/* 

Take  care  of  special  characters  in  a  string  (*  and  ?) . 

367 

* 

368 

* 

Copy  src  onto  itself,  stripping  out  back-slashes.  If  a 

369 

* 

*  or  ?  which  isn't  preceeded  by  a  backslash  is  found 

370 

* 

return  1,  else  return  0.  If  the  first  character  in  the 

371 

* 

string  is  a  quote  then  *  and  ?  aren't  special. 

372 

*/ 

373 

374 

register  char  *dest  -  src; 

375 

int 

special  -  0; 

376 

377 

TRACE ( 

"strip") ; 

378 

379 

while ( 

*src  ) 

380 

( 

381 

if (  *src  —  ' \\ '  ) 

382 

{ 

383 

/*  Copy  the  char,  following  the  \  into 

384 

*  dest  and  then,  if  we  aren't  at  end  of 

385 

*  string,  advance  src  to  point  past  the 

386 

*  escaped  character 

387 

*/ 

388 

389 

*dest++  -  *++src; 

390 

if(  *src  ) 

391 

:-+src; 

392 

l 

393 

else  if (  ISQUOTE ( *src)  ) 

394 

{ 

395 

/*  Copy  a  quoted  string  verba turn,  removing 

396 

*  the  quotes  if  Noquctes  (-q)  was  given  on 

397 

*  the  command  line. 

398 

*/ 

399 

400 

if (  Noquotes  ) 

401 

++src  ; 

402 

403 

while (  *arc  U  ! ISQUOTE (* src)  ) 

404 

{ 

405 

if(  src[0]  --  ' \\ '  &&  src[l]  ) 

406 

*dest++  -  *src++; 

407 

408 

*dest++  -  *src++  ; 

409 

) 

410 

411 

if (  *src  )  /*  Then  *src  is  a  quote  */ 

412 

{ 

413 

if(  Noquotes  ) 

414 

src++; 

415 

else 

416 

*dest++  -  *src++  ; 

417 

) 

418 

) 

419 

else 

420 

{ 

421 

/*  Just  do  the  copy.  Set  special  to  true 

422 

*  if  we  copy  a  special  character. 

423 

*/ 

424 

425 

if (  *src  —  '*'  ||  *src  —  '?'  ) 

426 

special  -  1; 

427 

428 

*dest++  -  *src++; 

429 

) 

430 

) 

431 

432 

*dest 

-  ' \0 ' ; 

433 

434 

END_TRACE ( "strip") t 
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(Listing  Continued,  text  begins  on  page  18) 


435 

436 

437  } 

438 

439  /* - 

440 

441  char 

442  char 

443  { 

444 

445 

446 

447 

448 

449 

450 

451 

452 

453 

454 

455 

456 

457 

458 

459 

460 

461 

462 

463 

464 

465 

466 

467 

468 

469 

470 

471 

472 

473 

474 

475  } 

476 

477  /* - 

478 

479  int 

480  char 

481  { 

482 

483 

484 

485 

486 

487 

488 

489 

490 

491 

492 
4  93 
4  94 

495 

496 

497 

498 

499 

500 

501 

502 

503 

504 

505 

506 

507 

508 

509 

510 

511 

512 

513 

514 

515 

516 

517 

518 

519 

520 

521 

522 

523 

524 

525 

526 

527 

528 

529 

530 

531 

532 

533 

534 

535 

536 

537 

538 

539 

540 

541 


return (  special  ) ; 


‘nextarg (  lp  ) 

**lp; 

/*  Get  the  next,  space  delimited,  argument  from  the  string 

*  pointed  to  by  *lp.  Return  a  pointer  to  the  argument  and 

*  update  *lp  to  point  past  it.  Leading  white  space  is 

*  skipped. 

*/ 

register  char  ‘start,  ‘line  -  *lp; 

TRACE ("nextarg") ; 

SKIPWHITE (  line  ); 

if(  ! ‘line  ) 

start  -  (char  *)0  ; 

else 

{ 

start  -  line++; 

line  -  skipto (  ISQUOTE (* start )  ?  * start  :  '  ',  line  ,  'W'); 

if (  ISQUOTE (‘line)  ) 
line++; 

if(  ‘line  ) 

‘line++  -  ' \0 •  ; 

*lp  -  line; 

> 

END_TRACE ( "nextarg" ) ; 
return  start; 


exp_dir (  buf ,  maxcount  ) 

‘buf  ; 

/‘  Remake  buf,  expanding  any  wild  card  characters  into 

*  their  proper  names.  That  is,  if  buf  containg  the  string: 

*  "foo  *  bar"  and  the  current  directory  contains  the 

*  files  A,  B  and  C  then  on  exit,  buf  will  point 

*  at  the  string  "foo  a  b  c  bar".  Expanded  entries  are 

*  sorted.  Return  0  if  a  wild  card  that  couldn't  be 

*  expanded  was  found,  else  return  1. 


register  DIRECTORY  *dp  -  0  ; 
register  char  *arg,  *sbuf,  ‘p  ; 

int  i,  rval  -  1; 


TRACE ( "exp_dir") ; 

if (  1 (dp  -  mk_dir (MAXDIR) )  ) 
goto  abort; 


dp-> files  -  1; 

/* 

Get 

dp->dirs  -  1; 

/* 

and 

dp->path  -  1; 

/* 

and 

dp->sort  -  1; 

/* 

the 

all  files 
all  directories 

prepend  the  path  name  if  given 
list  should  be  sorted 


*/ 

*/ 

*/ 

*/ 


/‘  Get  the  arguemts  from  the  input  src,  one  at  a  time, 

*  putting  them  into  the  dirv  array  of  a  DIRECTORY  structure 

*  (one  argument  per  dirv  entry) . 

*  If  the  argument  has  special  characters  (‘  or  ?  not 

*  preceded  by  a  \  or  enclosed  by  quotes)  then  expand  to  a 

*  directory  using  dir(),  otherwise  just  put  the  argument 

*  into  the  dirv  array  directly. 

*  Buf  will  grow  larger  if  anything  is  expanded  but  it 

‘  won't  get  larger  than  maxcount. 

*/ 


for (  sbuf  -  buf;  (arg  -  nextarg (&buf) )  &&  dp->maxdirs  >0;  ) 

{ 

if(  strip(arg)  ) 

{ 

i  -  dp->maxdirs; 

dir(  arg,  dp  ); 

if (  dp->maxdirs  --  i  ) 

{ 

/*  dir()  didn't  do  anything  */ 

fprintf (stderr, "Sh:  Can't  expand  <%s>\n", arg) ; 
rval  -  0; 
goto  abort; 

) 

) 

else 

{ 

/‘  Add  a  command  to  dirv.  First  malloc  space 

*  for  it.  Then  copy  it  the  arg  into  the 

*  malloc ()ed  space  &  put  it  into  dirv. 

*  We  use  malloc  in  order  to  make  it  easier 

*  to  free  the  space  used  by  the  DIRECTORY 
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542 

543 

544 

545 

546 

547 

548 

549 

550 

551 

552 

553 

554 

555 

556 

557 

558 

559 

560 

561 

562 

563 

564  abort: 

565 

566 

567 

568 

569  ) 

570 

571  /“ - 

572 

573  char 

574  char 

575  { 

576 

577 

578 

579 

580 

581 

582 

583 

584 

585 

586 

587 

588 

589 

590 

591 

592 

593 

594 

595 

596 

597 

598 

599 

600 
601 
602 

603 

604 

605 

606 

607 

608 

609 

610 
611 
612 

613 

614 

615 

616 

617 

618 

619 

620 
621 
622 

623 

624 

625 

626 

627  } 

628 

629  /* - 

630 

631  int 

632  char 

633  { 

634 

635 

636 

637 

638 

639 

640 

641 

642 

643 

644 

645 

646 

647 

648 
64  9 

650 

651 

652 


structure . 


if  < ! (  p  -  malloc(  strlen(arg) +1  )  )) 

{ 

fprintf (stderr,  "Sh:  out  of  memory  !!\n"); 
goto  abort; 

} 

strcpy(  p,  arg  ); 

* (  dp->lastdir  ) ++  —  p  ; 

— (  dp->maxdirs  ) ; 

++ (  dp->nfiles  ) ; 

} 

} 

i  -  unargv(dp->nfiles+dp->ndirs,  (char  ““) dp->dirv, sbuf ,raaxcount, *  '); 

if (  dp->maxdirs  <-  0  | |  i  >-  maxcount-1  ) 

fprintf (stderr,  "Sh:  command  line  too  large,  truncating\n") ; 

if(  dp  ) 

del_dir (  dp  ) ; 

END_TRACE ( "exp_dir" )  ; 
return (  rval  ) ; 


“search (  fname,  ext  ) 

“fname,  “ext; 

/*  Search  for  fname. ext  in  the  current  PATH.  Return  a  pointer 
*  to  the  full  path  name  if  you  find  it  (0  if  you  don't) . 

*/ 

static  char  pathname [ 80 ] ,  pbuf[129]  ; 

register  char  “p  ; 

char  “paths  ; 

/“  Assemble  the  pathname  by  concatanating  fname  and  ext 


TRACE ("search") ; 

if (  strpbrk (fname,  ".")  ) 
ext  - 


/“  If  file  name  already  has  an  */ 
/*  extension  don't  add  another.  “/ 


sprintf(  pathname,  "%0 . 32s . %0 . 3s",  fname,  ext  ); 
04)  <  0  ) 


if (  access (pathname, 

{ 


The  file  doesn't  exist  in  the  current  directory. 
If  fname  contains  the  characters  \  or  /  or  if 
the  PATH  enviornment  isn't  set,  return  a  NULL, 
else  search  for  it  along  the  path,  strpbrk ( )  is 
a  microsoft  and  Lattice  library  function.  It'll 
return  true  if  fname  contains  a  /  or  a  \. 


if (  strpbrk (fname, "\\/") 
“pathname  -  1 \0 • ; 

else 

t 


! (p  -  getenv ("PATH") )  ) 


strncpy(  (paths  -  pbuf),  p,  129  ); 

while (  p  -  next(  fipaths,  -1  )) 

{ 

sprint f (pathname,  "%0.50s\\%0.20s.%0.3s", 
p,  fname,  ext) ; 

if(  access (  pathname,  04  )  >-  0  ) 
break; 

else 

“pathname  -  ' \0'; 


) 


} 

END_TRACE ("search") ; 
return (  “pathname  ?  pathname 


execute (  buf  ) 
“buf; 


Execute  a  command .  Return  the  programs  exit  status  or 
-1  if  the  program  didn't  execute.  This  routine  assumes 
that  buf  is  at  least  DOSMAXLINE  characters  long. 


register  int 
register  char 
static  char 


rval  -  0; 

“name ; 

envstr [MAXLINE+8]  -  "CMDLINE—"; 


TRACE ( "execute") ; 

PSTR (  "execute(l)  buf-",  buf  ); 

/“  Create  the  CMDLINE  environment  variable  if  Cmd  it  true 

*  (it  can  be  set  false  with  a  "set  cmd-0."  If  cmd  is  false 

“  then  generate  a  "CMDLINE-"  with  no  argument.  This  is 

“  necessary  because  MSDOS  doesn't  support  a  unset  command. 


if (  Cmd  ) 


(Continued  on  next  page) 
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653 

654 

655 

656 

657 

658 

659 

660 
661 
662 

663 

664 

665 

666 

667 

668 

669 

670 

671 

672 

673 

674 

675 

676 

677 

678 

679 

680 
681 
682 

683 

684 

685 

686 

687 

688 

689 

690 

691 

692 

693 

694 

695 

696 

697 

698 

699 

700 

701 

702  } 

703 

704  /* — 

705 

706  int 

707  char 


atrncpy(  &envstr[8],  buf,  MAXLINE  ); 

else 

envstr [8]  -  1 \0 '  ; 
setenv (  envstr  ,  0  )  ; 

/*  Truncate  the  command  line  itself  (not  the  enviornment 

*  variable,  at  127  characters  and  then  echo  it  to  the 

*  screen  if  Echo  is  set.  Then  extract  the  program  name 

*  portion  of  the  string  (with  the  next{)  call) . 

*/ 

buf [DOSMAXLINE-3]  -  '\0'; 

if (  Echo  ) 

puts (  buf  ) ; 

name  -  next(&buf,  1  ',  -1  ); 


/*  Now  try  to  spawn  a  new  process.  Suspend  the  shell  until 

*  task  returns. 

*/ 

if(  (rval  -  spawnlp (P_WAIT,  name,  name,  buf,  NULL))  <  0  ) 

/*  If  we  can't  find  a  .com  or  .exe  file  then 

*  see  if  we  can  find  a  batch  file  with  ole 

*  right  name.  Otherwise  print  an  error  message 

*  Note  that  we  have  to  modify  the  CMDLINE 

*  enviornment  string  so  that  the  leftmost 

*  argument  (will  be  argv[0]  in  the  child 

*  process)  is  the  string  "sh" 

*/ 

if (  errno  —  ENOENT  ) 

sprintf (envstr,  "CMDLINE-sh  %s  %s",  name,  buf); 
rval  -  spawnlp (P_WAIT,  "sh",  "sh",  name,  buf,  NULL); 

} 

if(  rval  <  0  ) 

{ 

printf("sh:  Can't  execute  %s  %s",  name,  buf); 
perror("  "); 

) 

) 

END_TRACE ( "execute" ) / 
return  rval; 


V 


exp_vars(  dest,  src,  maxcount,  mode  ) 
*dest,  *Brc ; 


708  { 

709 

710 

711 

712 

713 

714 

715 

716 

717 

718 

719 

720 

721 

722 

723 

724 

725 

726 

727 

728 

729 

730 

731 

732 

733 

734 
73  5 

736 

737 

738 

739 

740 

741 

742 

743 

744 

745 

746 

747 

748 

749 

750 

751 

752 

753 

754 

755 

756 

757 

758 

759 


/*  Copy  src  into  dest,  expanding  shell  variables  as 

*  appropriate.  Shell  variables  all  have  a  $  or  a  %  as  their 

*  first  character.  The  global  pointers  Numv  and  Numc  keep 

*  track  of  arguments  for  $<num>  variables. 

* 

*  If  mode  —  1  aliases  are  expanded 

*  If  mode  —  2  $arg s  are  expanded 

*  If  mode  —  3  both  are  expanded. 

* 

*  return  the  size  of  the  expanded  string. 

*  A  mode  1  or  3  call  will  return  with  the  high  bit  of  src 

*  set . 

*/ 

register  int  num.- 

register  char  *p  ; 

char  *start_dest  -  dest; 

TRACE ( "exp_vars" ) ; 

DIAG("exp_vars,  input  -  <%s>\n",  src  ); 


/*  Expand  aliases.  First,  remember  the  original  start  of 

*  the  target  array.  Then,  set  the  high  bit  of  *src  so  that 

*  getvar  will  look  for  an  alias.  Then  actually  expand  it, 

*  Then  clear  the  high  bit  of  the  first  character  of  dest 

*  (which  will  be  set  if  no  alias  was  found) . 

*  There  is  a  second-order  recursion  here  in  that  getvar () 

*  makes  a  mode  2  exp_vars  call. 

*/ 

if (  mode  f  1  ) 

{ 

*src  |-  0x80; 

getvar  (  fisrc,  idest,  fimaxcount  ); 

DIAG ("exp_vars,  expanded  aliases  <%s>\n",  start_dest); 

) 


/*  Now,  expand  shell  variables.  If  we  see  and  escaped 

*  character  copy  both  the  \  and  the  character  to  dest. 

*  else  if  the  character  isn't  a  shell  variable  (doesn't 

*  have  a  leading  $  of  %)  just  copy  it.  Else,  try  to 

*  expand  the  shell  variable. 

*/ 

while (  *src  &&  maxcount  >  0  ) 

{ 

if(  *src  —  'W  &&  src[l]  ) 

/*  If  the  character  following  the  \  is  a 
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760 

*  $  of  %  then  strip  the  backslash  and  copy 

761 

“  the  $  or  %  to  the  dest  array.  Otherwise 

762 

“  copy  both  the  \  and  the  character  that 

763 

“  follows. 

764 

“/ 

765 

766 

src++;  /*  Skip  past  the  \  “/ 

767 

768 

if (  ! ISVAR (*src)  ) 

769 

{ 

770 

if(  — maxcount  <-  0  ) 

771 

break; 

772 

“dest++  -  1 W  ; 

773 

} 

774 

775 

if (  — maxcount  <-  0  ) 

776 

break; 

777 

*dest++  -  “src++; 

778 

} 

779 

else  if(  ! I SVAR (  “src  )  II  ! (mode  &  2)  ) 

780 

{ 

781 

/“  Either  character  is  just  a  normal  character 

782 

“  (not  a  shell  variable)  or  we're  told  to  not 

783 

“  expand  shell  variables. 

784 

*/ 

785 

786 

“dest++  -  *src++; 

787 

if (  — maxcount  <-  0  ) 

788 

break; 

789 

} 

790 

else  if(  digit (  “++src  )  ) 

791 

{ 

792 

/“  Expand  a  $<num>  arg.  first  extract  the 

793 

*  <num>  from  source,  then  copy  the  correct 

794 

“  vector  out  of  the  Numv  array. 

795 

“  If  the  Numv  entry  is  NULL,  don't 

796 

*  put  anything  in  the  dest  array. 

797 

“/ 

798 

799 

for (  num  -  0;  digit (*src);  ) 

800 

num  -  (num  “  10)  +  (“src++  -  '0'); 

801 

802 

if (  num  <  Numc  ) 

803 

for (  p  -  Numv [num];  *p  ;  “dest++  -  *p++  ) 

804 

if(  — maxcount  <-  0  ) 

805 

break; 

806 

} 

807 

else 

808 

{ 

809 

/“  We've  found  a  $  not  followed  by  a  number  */ 

810 

811 

switch (  *src++  ) 

812 

{ 

813 

case  '*'; 

814 

num  -  unargv (Numc, Numv, dest, maxcount, '  ' 

815 

dest  +-  num; 

816 

maxcount  —  num; 

817 

break; 

818 

819 

case  ' p • : 

820 

getcwd (  dest,  maxcount  ); 

821 

for(  ;“dest  ;  ++dest,  — maxcount  ) 

822 

if  (  “dest  --  'W  ) 

823 

“dest  -  '/'; 

824 

break; 

825 

826 

case  num  -  get  hnum();  goto  skip; 

827 

case  's';  num  -  Shlev; 

828 

skip:  if (  maxcount  >  5  ) 

829 

( 

830 

sprintf (  dest,  "%d",  num  ); 

831 

fort; “dest  ;  ++dest,  — maxcount) 

832 

833 

) 

834 

break; 

835 

836 

default : 

837 

— src; 

838 

getvar (  &src,  sdest,  fimaxcount  ); 

839 

break; 

840 

) 

841 

) 

842 

843 

“dest  - 

■  '\0*  ; 

844 

) 

845 

846 

“start 

dest  &- 

0x7 f  ; 

847 

848 

DIAG ( " 

exp  vars: 

on  return  <%s>,",  start  dest  ); 

849 

DI AG { " 

returning  %d\n",  dest  -  start  dest  ); 

850 

851 

END  TRACE ("exp 

vars")  ; 

852 

853 

return (  dest  - 

start  dest  ) ; 

854 

} 

855 

857 

858 

prompt ( ) 

859 

{ 

860 

/*  Print  a  prompt  using  the  PROMPT  enviornment  variable 

861 

*  Return  true . 

8  62 

“/ 

863 

864 

char 

buf [50] ; 

865 

regist 

er  char 

“p; 

866 

867 

if (  Mode  “  INTERACTIVE  I  I  Echo  ) 

868 

{ 

869 

if  (  1  (F 

>  -  getenv ( "PROMPT" ) )  ) 

870 

printf(  "[%d:%d]  ",  Shlev,  get_hnum()  ); 

(Continued  on  ne^t  page) 
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871 

else 

872 

{ 

873 

exp  vars (  buf,  p,  50,  2  ); 

874 

printf(  buf  ); 

875 

) 

876 

} 

877 

878 

return  1; 

879 

} 

880 

882 

883 

int 

docmd (  cmd  ) 

884 

char 

•cmd 

885 

{ 

886 

/* 

Do  one  command  from  line. 

887 

* 

Return  an  exit  status  (or  -1  on  error) . 

888 

•/ 

889 

890 

register  DIRECTORY  *dp; 

891 

register  int  rval  -  -1; 

892 

893 

TRACE ("docmd") ; 

894 

PSTR  ( 

"docmd (1)  cmd-",  cmd  ); 

895 

896 

/*  If 

ther're  no  wild  cards  in  cmd  then  just  strip  backslashes 

897 

*  and  quotes.  Else,  expand  the  wild  cards  (  exp  dir  will  strip 

898 

*  backslashes  etc.)  Then  execute  the  command. 

899 

•/ 

900 

901 

if  (  ! 

has  wild(cmd)  ) 

902 

strip(cmd);  /•  Just  strip  backslashes  */ 

903 

904 

else 

if(  ! exp  dir (cmd,  MAXLINE)  ) 

905 

goto  abort; 

906 

907 

rval 

-  execute (cmd)  ; 

908 

909 

abort : 

END  TRACE ( "docmd") ; 

910 

return (  rval  ) ; 

911 

} 

912 

914 

915 

rcopy ( 

dest. 

src,  maxcount  ) 

916 

register  char 

•dest  ; 

917 

char 

•src 

918 

{ 

919 

register  char  *tbuf; 

920 

char 

•tail; 

921 

char 

•sd  -  dest; 

922 

923 

DIAG  ( 

"rcopy  (top  of  proc) :  src  -  <%s>\n",  src  ); 

924 

925 

if  (  ! 

•src  | |  maxcount  <-  0  ) 

926 

return; 

927 

928 

if  (  ! 

(tbuf  -  malloc(  maxcount  ))  ) 

929 

fprintf (stderr, "Sh:  out  of  memory\n") ; 

930 

else 

931 

{ 

932 

/•  1)  expand  the  src  buffer  into  tbuf 

933 

•  2)  advance  tail  to  point  past  the  next  ;  and  replace 

934 

•  the  ;  with  a  null . 

935 

*  3)  copy  everything  up  to  the  tail  to  dest  and  add  a 

936 

•  ;  to  dest  if  the  tail  is  non-null. 

937 

*  4)  repeat  this  process  using  the  tail  as  source. 

938 

•/ 

939 

940 

1*1*1 

exp  vars (  tbuf,  src,  maxcount  ,  3  ) ; 

941 

942 

tail  -  tbuf; 

943 

1*2*1 

next(  &tail,  ,  1 \\'); 

944 

SKIPWHITE (  tail  ); 

945 

946 

1*2*1 

for (src  -  tbuf;  *src  &&  src-tbuf  <  maxcount;  *dest++  -  *src++] 

947 

948 

949 

if(  (maxcount  —  (src-tbuf))  &&  •tail  ) 

950 

*dest++  -  ; 

951 

952 

•dest  -  • \0 ' ; 

953 

954 

DIAG ("rcopy  (before  recursive  call):  dest  -  <%s>\n",  sd  ); 

955 

956 

/•4*/ 

rcopy(dest,  tail,  maxcount); 

957 

free  (tbuf) ; 

958 

959 

DIAG ("rcopy  (after  recursive  call):  dest  -  <%s>\n",  sd  ); 

960 

} 

961 

} 

962 

963 

964 

965 

char 

•next 

cmd  () 

966 

{ 

967 

/• 

Get  a  line  from  input,  split  off  one  command,  and 

968 

* 

then  return  a  pointer  to  it  (or  NULL  if  at  end  of 

969 

* 

input.  History  processing  is  done  here  too. 

970 

* 

Semicolons  inside  quoted  strings  or  preceeded  by  a  1 \ ' 

971 

* 

do  not  seperate  commands.  Comments  and  blank  lines 

972 

* 

are  absorbed  (ie.  next  cmd  won't  return  until  it 

973 

* 

gets  a  real  input  line) . 

974 

*/ 

975 

976 

static  char  Cmdbuf [MAX LINE] ;  /•  Should  initialize  to  zeros  */ 

92 
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static  char 
register  char 
char 


*src  -  Cmdbuf 


TRACE ( Mnext_cmd" )  ; 

DIAG ("next  cmd:  src  is  <%s>\n",  src  ); 


while (  !*src  ) 


if(  !  (*Ifunct)  ()  ) 

( 

END_TRACE ( "next_cmd"  ) ; 
return  NULL; 

) 

DIAG("next_cmd:  got  <%s>  from  input\n",  Ibuf  ); 

src  -  Ibuf; 

SKIPWHITE (  src  ) ; 


while (  !*src 


*src  —  COMMENT  )  ; 


history (  src,  MAXLINE  -  (src-Ibuf)  ); 
if (  *src  ) 

{ 

rcopy(  Ibuf,  src,  MAXLINE  ); 
src  -  Ibuf; 

) 


p  -  next  (  &src,  1 ;'  ,  1 W)  ; 

DIAG  ("next_cmd:  buffer  <%s>\n",  p  ); 

DIAG("next_cmd:  on  next  call  buffer  will  be  <%s>\n",  src  ); 

strcpy(  Cmdbuf,  p  ); 
if{  Verbose  ) 

printf{"[sh  %d  input]  <%s>\n",  Shlev,  Cmdbuf  ); 

DIAG ("next_cmd:  returning  <%s>\n",  Cmdbuf  ); 

END_TRACE (  "next_cmd"  ); 

return (  Cmdbuf  ); 


*errmsgs[]  - 


%ci 

%cc  <string> 


file  args . . 


shell  entered  in  interactive  mode\n", 
enter  interactive  mode\n", 

commands  are  read  from  string.  If  several  strings\n", 
are  present  they  are  concatanated  together  before\n", 
execution.  The  'c'  may  be  upper  or  lower  case.\n", 
commands  are  taken  from  <file>.  Args  are  expanded\n", 
to  correspond  with  $0  $1  etc  inside  the  file.\n", 
for  DOS  compatability  %0  %1  etc  are  also  recognized\n" 
Strip  quotes  from  quoted  argument  strings.  Usually\n" 
they  are  left  in  so  that  a  spawned  process  can\n", 
assemble  its  argv  correctly . \n". 

Print  input  lines  to  the  shell  as  they  are  read.Xn", 
Print  lines  as  they  are  executed\n". 


usage(  c  ) 

{ 


Print  the  usage  error  message. 


register  char  **pp; 

fprintf  (stderr,  "Sh:  illegal  argument  <%c>:  Usage  is\n\n",  c) ; 
for<  pp  -  errmsgs;  **pp  ;  fprintf (stderr,  *pp++,  Switchar)  ) 


int  setargs(  p  ) 

register  char  *p; 

{ 

/*  Set  various  global  flags  base  on  command  line 

*  arguments.  This  routine  will  also  be  used  by 

*  "set"  which  can't  recognize  the  -c  switch.  So, 

*  ignore  -c  if  c_enabled  is  false,  p  should  point 

*  at  the  -  on  entry.  Processing  will  terminate  when 

*  a  space  or  tab  or  end  of  string  is  found. 


TRACE ("setargs") ; 

if (  *++p  ) 

{ 

for ( ;  *p  ;  p++) 

{ 

switch (  *p  ) 


case  'C':  Mode  -  COMMAND; 
case  1 q 1 :  Noquotes  -  1; 
case  'v';  Verbose  -  1; 
case  'x' :  Echo  -  1; 


(Continued  on  next  page) 
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1087 

1088 

1089 

1090 

1091 

1092 

1093 

1094 

1095 

1096 

1097 

1098 

1099 

1100 
1101 
1102 

1103 

1104 

1105 

1106 

1107 

1108 

1109 

1110 
1111 
1112 

1113 

1114 

1115 

1116 

1117 

1118 

1119 

1120 
1121 
1122 

1123 

1124 

1125 

1126 

1127 

1128 

1129 

1130 

1131 

1132 

1133 

1134 

1135 

1136 

1137 

1138 

1139 

1140 

1141 

1142 

1143 

1144 

1145 

1146 

1147 

1148 

1149 

1150 

1151 

1152 

1153 

1154 

1155 

1156 

1157 

1158 

1159 

1160 
1161 
1162 

1163 

1164 

1165 

1166 

1167 

1168 

1169 

1170 

1171 

1172 

1173 

1174 

1175 

1176 

1177 

1178 

1179 

1180 
1181 
1182 

1183 

1184 

1185 

1186 

1187 

1188 

1189 

1190 

1191 

1192 

1193 


abort: 

) 


case  * i * :  Mode  -  INTERACTIVE; 

case  1  1 : 
case  1 \t ' : 

default:  usage (  "p  ); 

} 

} 

} 

END_TRACE ( "setargs") ; 


break; 

goto  abort; 
break; 


/* - "/ 

doargs  (argc,  argv) 
char  ""argv; 

{ 

if(  — argc  <-  0  )  /*  Check  for  comand  line  args  &  "/ 

{  /"  use  interactive  mode  if  none  */ 


Mode  -  INTERACTIVE;  /*  are  found.  "/ 

Ifunct  -  interactive_input; 

return; 

} 

if(  *"(++argv)  —  Switchar  )  /"  There's  at  least  one  arg,  "/ 

{  /*  skip  to  second  arg  and  call  "/ 

setargs (  *argv++  );  /"  set  args  if  the  first  char  */ 

— argc;  /*  is  a  Then  skip  past  the  */ 

)  /"  second  arg  too.  */ 


Numv  -  argv  ; 

Numc  -  argc  ; 

if(  argc  <-  0  ||  !""argv  ) 

{ 

fprintf (stderr, "Sh:  missing  file  name,  ") ; 
fprintf (stderr, "use  -i  for  interactive  input\n") ; 
exit (1) ; 

} 

else  if(  Mode  ~  COMMAND  ) 

{ 

Ifunct  -  command_input ; 

) 

else  if(  Mode  --  FILEMODE  &&  ! (Filename  -  search ( "argv,  "bat"))) 

{ 

fprintf (stderr, "Sh:  can't  find  <%s>\n",  "argv  ); 
exit ( 1) ; 

} 

) 

/* - "/ 


setenv(  env,  allocate  ) 
char  "env; 

{ 

/*  Set  an  enviornment.  Env  may  be  "name-contfents"  or  the  -  may 
"  be  a  space. 

*  If  allocate  is  true  allocate  space,  otherwise  acutally  use 

*  env  (which  must  be  static)  as  the  string. 


register  char  *p; 

/"  Look  for  either  a  space  or  a  -  in  the  string.  If  you 

*  find  a  space,  replace  it  with  an  -. 

*/ 

for(  p  -  env  ;  "p  &&  *p  !-  1  '  &&  "p  ;  p++  ) 

if (  *P  --  '  '  ) 

*P  -  ; 

/*  Now  set  the  enviornment  to  the  indicated  value 

"/ 

if(  p  -  allocate  ?  strsave(  env  )  :  env  ) 
if (  putenv(p)  !-  -1  ) 
return; 

fprintf (stderr, "Sh :  setenv  failed,  out  of  memory\n"); 
if(  allocate  &&  p  ) 
free(p)  ; 

) 

/* - */ 


set(  str  ) 

register  char  "str; 

( 

/"  Set  a  shell  variable,  syntax  is 
*  (whitespace]  <name>  (-  <value>] 


register  int  i; 

char  "name; 


/*  Get  the  name,  replacing  the  trailing  blank  or  -  with 

*  a  null.  Print  variables  if  there  is  no  name. 

*/ 


if(  !*str  ) 

{ 

printf ("%-8s :  %s\n", 
printf ("%-8s :  %s\n", 
printf ("%-8s :  %s\n", 
printvars ( ) ; 

) 

else 


"echo", 

"cmd", 

"verbose". 


Echo  ?  "ON" 
Cmd  ?  "ON" 
Verbose  ?  "ON" 


"OFF") 

"OFF") 

"OFF") 
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for  (name  -  str;  *str  ;  ++str  ) 

if  (  *str  —  1 - 1  ||  *str  — 


*str++  -  0; 
break; 


Get  the  command  tail,  skipping  past  any 
or  blanks  to  get  there. 


while (  *str  —  1 
++str  ; 


/•  Process  the  command: 

*/ 


i  -  •str  ?  atoi(str)  :  1  ; 

if(  !strcmp(  "echo",  name))  Echo  -  i 
else  if (  !strcmp(  "verbose",  name))  Verbose  -  i 
else  if (  !strcmp(  "cmd",  name))  Cmd  -  i 
else  setvar(name,  str); 


Alias  support  uses  the  same  tables  as  shell  varialbes .  However, 
the  top  bit  of  the  first  character  of  the  alias  name  is  set 
to  indicate  its  function. 


1  unalias (  str  ) 
i  char  *str; 


alias (  str  ) 


•str  |-  0x80  ; 
unsetvar (  str  )  ; 


if(  !*str  ) 

printalias ()  ; 

else 

{ 

•str  |-  0x80 
set  (  str  ) ; 


Print  working  directory 


if(  !getcwd(  nbuf,  80  )  ) 

fprintf (stderr,  "sh:  path  too  long  to  print. \n") ; 


print f ("%s\n",  nbuf  ); 


disk__present  (  id  ) 
int  id; 


Return  true  if  there's  a  disk  plugged  into  the 
indicated  drive,  else  print  an  error  message 
and  return  1.  This  routine  assumes  that  drive 
C  has  a  disk  in  it  so  it  will  return  true  if  id 
or  id  —  'C'  without  checking. 


register  int  try  -  5; 

register  int  err  ; 

union  REGS  regs; 

if (  (id  -  toupper(id))  -- 
return  1; 


/•  times  to  try  to  read  disk 


||  id  —  'c*  ) 


regs . h . ah  -  4  ; 
regs.h.al  -  1; 
regs.x.cx  -  0; 
regs.h.dh  -  0; 
regs.h.dl  -  id 


Service  #4  (verify  sec)  */ 
#  of  sectors  •/ 
track  t  &  sector  #  */ 
head  #  •/ 
drive  #  */ 


Actually  read  the  disk.  Loop  until  we've  gotten  a  timeout 
error  (0x80)  from  dos  try  times. 


err  -  int86(0xl3,  firegs,  iregs)  &  Oxff; 


}  while (  (err  &  0x80)  &&  ( — try  >-  0)  ); 


regs. h. ah  -  0x0; 
int86(0xl3,  &regs,  &regs) ; 


/•  Recalibrate  diskette  system  •/ 


fprintf (stderr, "Cd :  can't  log  on  drive  %c,  ",  toupper (id) ) ; 


( Continued  on  next  page) 


Dr.  Dobb's  Journal,  January  1986 


95 

57 


C  CHEST  LISTING 


(Listing  Continued,  text  begins  on  page  18) 

1305  fprintf (stderr,"DOS  error  code  -  0x%02x\n"  ,  err 


1305 

1306  } 

1307 

1308  rel 

1309  } 

1310 

1311  /* - 

1312 

1313  void 

1314  register  char 

1315  { 

1316  /* 

1317  * 

1318  * 

1319  * 

1320  * 

1321  * 

1322  * 

1323  * 

1324  * 

1325  * 

1326 

1327  if 

1328  { 

1329 

1330 

1331 

1332 

1333 

1334 

1335 

1336  } 

1337 

1338  if 

1339 

1340  } 

1341 

1342  /* - 

1343 

1344  shift () 

1345  { 

1346  /* 

1347  * 

1348  * 

1349 

1350  if 

1351  { 

1352 

1353 

1354  } 

1355  } 

1356 

1357  /* - 

1358 

1359  doenv() 

1360  { 

1361  /* 

1362  * 

1363  * 

1364  * 

1365  * 

1366 

1367  st 

1368  re 

1369 

1370  if 

1371 

1372 

1373  if 

1374 

1375 

1376  sp 

1377  se 

1378  } 

1379 

1380  /* - 

1381 

1382  use_exit() 

1383  { 


return (  !err  ); 


cd (  name  ) 

*name; 

Change  the  current  directory  to  the  indicated  name . 

Log  in  a  new  disk  if  necessary.  This  routine  is 
a  bit  more  sophisticated  than  DOS  itself,  in  that 
it  checks  if  a  disk  exists  before  trying  to 
log  it  on.  This  checking  is  done  using  the 
"Get  diskette  status"  service  of  BIOS  interrupt  0x13. 
Get  to  the  current  directory  on  another  disk  by  saying 
"cd  x:"  Get  to  another  directory  on  another  disk  by 
saying  "cd  x : /dir/subdir/etc" 


if(  *name  &&  namefl]  --  ) 

{ 

if (  ! disk jpre sent (*name)  ) 
return; 

else 

{ 

bdos (  Oxe,  toupper ( *name)  -  'A',  0) ; 
name  +-  2; 


if (  *name  &&  chdir(  name  )  <  0  ) 

fprintf (stderr,  "sh:  Can't  find  %s\n",  name  ); 


/*  Process  the  "shift"  command  (move  all  the  $  args  left 

*  one  notch) . 

*/ 

if (  Numc  ) 

{ 

— Numc; 

++Numv; 

} 


/*  Reads  and  initializes  the  various  enviornment  variables. 

*  This  routine  should  only  be  called  once  and  it  must  be 

*  called  before  Shlev  is  used  and  before  command  line 

*  processing  is  done. 

*/ 

static  char  sbuf[16]; 
register  char  *p; 

if (  (p  -  getenv ("SWITCHAR") )  &&  *p  ) 

Switchar  -  *p  ; 

if (  (p  -  getenv ("SHLEV" ) )  &&  *p  ) 

Shlev  -  atoi (p) ; 

sprintf (sbuf,  "SHLEV-%d",  ++Shlev  ); 
setenv  (sbuf)  ; 


We  get  here  on  a  SIGINT  (~C)  interrupt 


signal (  SIGINT,  use_exit  ) ; 

fprintf (stderr, "Use  \"exit\"  or  \"logout\"  to  leave  outer  shell. \n" 


i  TOKEN  tokenize (  buf  ) 
i  register  char  *buf; 

'  ( 


1396 

/* 

This 

is  an  extremely  primitive  token  rec 

1397 

1398 

1399 

*/ 

eventually  be 

replaced 

with  something  me 

1400 

if  ( 

! strcmp ( 

"alias". 

buf)) 

return 

ALIAS; 

1401 

if  ( 

! strcmp ( 

"cd". 

buf)  ) 

return 

CD; 

1402 

if  ( 

! strcmp ( 

"exit". 

buf) ) 

return 

EXIT; 

1403 

if  ( 

1 strcmp ( 

"history1 

,  buf) ) 

return 

HISTORY; 

1404 

if  ( 

1 strcmp ( 

"logout". 

buf)) 

return 

LOGOUT; 

1405 

if  ( 

! strcmp ( 

"pwd". 

buf) ) 

return 

PWD; 

1406 

if  ( 

! strcmp ( 

"rem". 

buf)  ) 

return 

REM; 

1407 

if  ( 

! strcmp ( 

"setenv". 

buf) ) 

return 

SETENV; 

1408 

if  ( 

! strcmp ( 

"set". 

buf)) 

return 

SET; 

1409 

if  ( 

! strcmp ( 

"shift". 

buf)) 

return 

SHIFT; 

1410 

if  ( 

! strcmp ( 

"unalias1 

,  buf)  ) 

return 

UNALIAS ; 

1411 

if  ( 

1 strcmp ( 

"unset". 

buf) ) 

return 

UNSET; 

(Continued  on  page  98) 
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C  CHEST  LISTING 


(Listing  Continued,  text  begins  on  page  18) 

1412  return  CMD; 


Process  commands  using  the  current  Ifunct.  Continue  till 
end  of  input  is  reached.  If  expand_vars  is  false  then 
aliases  and  $args  aren't  expanded.  This  lets  us  read 
in  the  shrc.bat  file  unmolested 


char  cmdbuf [ 9] ;  /*  Place  to  put  extracted  command  */ 

char  *p,  *start; 

register  char  *cmd; 

register  int  i; 

int  rval  -  0; 

while (  start  -  cmd  -  next_cmd ( )  ) 

{ 

DIAGC'cmds:  next_cmd  returned  <%s>\n",  cmd  ); 


Strip  the  command  name  from  the  rest  of  the  command 


p  -  cmdbuf; 

for  (  i  -  8;  — i  >-  0  &&  *cmd  &&  "cmd  !- 


*p++  -  *cmd++) 


DIAG("cmds:  partitioned  <%s>",  cmdbuf  ); 

DIAG ( "+  <%s>\n",  cmd  ); 

SKIPWHITE (cmd) ; 

/*  If  Echo  is  set  then  echo  the  command  to  standard 

*  output.  Note  that  if  i  —  CMD  then  the  command 

*  will  be  echoed  in  execute  ()  (called  by  docmdO). 
*/ 


1454 

if<  (i  -  (int) 

tokenize (cmdbuf )  )  !-  (int)  CMD 

&&  Echo 

1455 

puts  ( 

start  ) ; 

1456 

1457 

switch (  i  ) 

1458 

{ 

1459 

case  ALIAS : 

alias  ( 

cmd  ) ; 

break; 

1460 

case  CD: 

cd  ( 

cmd  ) ; 

break; 

1461 

case  CMD: 

rval  -  docmd (start)  ; 

break; 

1462 

case  HISTORY: 

print  hist(  stdout  ); 

break; 

1463 

case  PWD: 

pwd  ( 

) ; 

break; 

1464 

case  REM: 

break; 

1465 

case  SET: 

set  ( 

cmd  ) ; 

break; 

1466 

case  SETENV : 

setenv  ( 

cmd  ) ; 

break; 

1467 

case  SHIFT: 

shift  ( 

); 

break; 

1468 

case  UNALIAS: 

unalias  ( 

cmd  ) ; 

break; 

1469 

case  UNSET: 

unsetvar ( 

cmd  ) ; 

break; 

1470 

default: 

print f  ( 

"Illegal  token\n"); 

break; 

1471 

1472 

case  LOGOUT: 

1473 

1474 

1475 

1476 

1477 

1478 

1479 

1480 

1481 

1482  ) 

1483  exit: 

1484  return  rval; 

1485  ) 

1486 

1487  /* - 

1488 

1489  main(argc,  argv) 


reset_f ileinput ( ) ; 

if(  access (Filename  -  "/logout . bat",  04)  --  0  ) 
cmds ( ) ; 

/*  Fall  through  to  EXIT  case  */ 


case  EXIT: 

goto  exit; 


Exit  status  is  that  of  the  most 

recently  excuted  program.  In  the  case  of  a  batch  file 
the  exit  status  will  be  that  of  the  shell  processing 
the  batch  file  (ie.  of  the  last  program  executed  by 
that  shell) . 


reargv Uargc,  &argv) 
doenv ( ) ; 


/*  Get  a  long  command  line  if  one's  there*/ 
/*  Read  various  enviornment  variables  and 

*  intialize  Shlev,  which  holds  the 

*  current  shell  level. 


Process  the  two  automatic  batch  file,  /shrc.bat  is 
executed  every  time  a  shell  is  created,  /login. bat 
is  only  executed  when  a  level  0  shell  is  created. 


if(  access (Filename  -  "/shrc.bat",  04)  — -  0  ) 

{ 

cmds  () ; 

re set_f ileinput () ; 

) 

if (  Shlev  —  0  &&  access (Filename  -  "/login. bat",  04) 
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1519 

reset  fileinput () ; 

1520 

} 

1521 

1522 

1523 

/*  Now  process  the  command  line  arguments.  Doargs  will 

1524 

*  set  the  Echo,  Verbose,  Cmd  and  Mode  variables  as 

1525 

*  appropriate.  If  we're  in  an  interactive,  level 

1526 

*  0  shell.  Call  signal  to  prevent  "C  from  working  on 

1527 

*  the  shell  itself  and  print  a  copyright  notice. 

1528 

*/ 

1529 

1530 

doargs (argc,  argv) ;  /*  Process  command  line  args  */ 

1531 

1532 

if (  Shlev  —  0  &&  Mode  —  INTERACTIVE  ) 

1533 

{ 

1534 

signal!  SIGINT,  use  exit  ); 

1535 

fprintf (stderr, "SH  (ver  %s)  -  Copyright  (c)  1985,  ",  VER) ; 

1536 

fprintf (stderr, "Allen  I  Holub.  All  rights  reserved . \n") ; 

1537 

) 

1538 

1539 

1540 

/*  Finally,  process  commands  from  the  input  source  determined 

1541 

*  by  the  command  line. 

1542 

*/ 

1543 

1544 

exit (  cmds ( )  ) ; 

1545  } 

End  Listing 

Shell  listings  continue  next  month 

99 
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PL/68K 


LISTING  ONE  (Text  begins  on  page  26) 


Declare  the  format  of  a  macro  table  node. 


struct  node  { 

struct  node  *  next;  /*  Pointer  to  next  node.  V 

int  nargs;  /*  Number  of  args  in  macro.  */ 

char  *  name;  /*  Pointer  to  name  of  macro.  */ 

char  *  text;  /*  Pointer  to  replacement  text  of  macro.  */ 


Define  the  hash  table  used  to  access  nodes  of  the  macro  table. 


•define  MAC_PRIME  101 
struct  node  *  ht  [MAC_PRIMEJ; 

/* 

Look  up  a  symbol  in  the  macro  table. 
Output :  Z 


V 

•define  hash_val  d2 
•define  bpO  al 
•define  bpl  a2 

lookup  (symbol) 
register  char  *  symbol; 

{ 

register  struct  node  **bpO, 
register  int  hash_val; 


if  found,  NZ  if  not  found. 
aO  pointer  to  text  of  symbol. 

dOw  number  of  arguments  (0-n) ,  -1  if  no  arguments. 


*bpl; 


/*  Get  the  hash  value  of  the  symbol  into  hash_val.  */ 
hash  (symbol) ; 
hash_val  -  dO; 

/*  Point  bpO  into  the  hash  table.  V 
bpO  -  iht; 

hash_val  *-  sizeof (struct  node  *); 
adda  (hash_val,  bpO) ; 

/*  Search  down  the  list  of  buckets  hanging  from  the  hash  table.  •/ 
for  (bpl  -  *bp0;  bpl;  bpl  -  bpl  ->  next)  { 
st r_eq (symbol,  bpl  ->  name); 
if  (Z)  { 

/*  Match.  */ 
aO  =  bpl  ->  text; 
dO  -  bpl  ->  nargs; 
move (Z_BIT,  ccr) ; 
return; 

) 


/*  No  match.  */ 
move (NZ_BIT,  ccr) ; 


End  Listing  One 


LISTING  TWO 


ht : 

ds.l 

101 

lookup: 

movem.l 

al/a2/d2,  -  (sp)  ; 

function  entry 

subq 

•  4,  sp 

move.l 

20  (sp),  (sp)  ;get 

the  hash  value  into  hash 

jsr 

hash 

move.l 

dO,  d2 

move.l 

•ht,  al  ; point  bpO  into  the  hash  table 

mulu 

•  4,  d2 

adda .  1 

d2,  al 

; 

search  down 

the  list  of  buckets 

move.l 

(al) ,  a2  ;  for  (bpl 

=  *  bpO ;...;...) 

bra 

3 

1: 

move.l 

6(a2),  (sp)  ;str  eq (symbol,  bpl  ->  name); 

move.l 

20  (sp) ,  -  (sp) 

jsr 

str  eq 

addq 

*4,  sp 

bnz 

2 

;if  (Z) 

move.l 

?(a2) ,  aO  ; 

aO  =  bpl  ->  text; 

move.w 

4(a2),  dO  ; 

dO  -  bpl  ->  nargs; 

move 

•  4 ,  ccr  ; 

move(Z  BIT,  ccr); 

bra 

_4 

;  return; 

move.l 

(a2) ,  a2  ;  for  ( . . . 

anpa .  1 

•C,  a2  ;for  ( _ ; 

bp;  . . . ) 

bnz 

1 

move 

•0,  ccr  ;move(NZ  ! 

BIT,  ccr); 

addq 

•4,  sp  ; function 

exit 

movem.l 

(sp) +,  al/a2/d2 

End  Listings 
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MULTITASKING  OS  LISTING 


(Text  begins  on  page  44) 


Terra  Nova  Communications  multi-tasking  kernel 
Initialization  and  task-switcher 

Note:  this  is  not  intended  to  be  a  complete  listing.  It's  only 
a  sample  of  some  of  the  techniques  used  in  our  system. 


CodeHeap 

StackEnd 

StackBegin 


External  symbols  (defined 
EXTERN  VecTable, 

JMPTable, 
JMPTabLen, 
KemEnd, 
IOInit, 
Heaplnit , 
Syslnit, 
SysConMon, 

HeapMunger, 

DiskMunger 


in  other  code  segments) 

/vector  table  for  hardware  vector  list 
/jump  table  for  system  calls 
/length  of  ju  mp  table  in  longwords 
/end  of  kernel  code  item  in  heap 
/our  private  I/O  initialization  routine 
/our  private  heap  initialization 
/system  variable  initializer 
/entry  point  for  system  console 
/monitor  task 

/entry  point  for  heap  munger  task 
/entry  point  for  disk  munger  task 


Entry  points  in  this  module  (referenced  from  elsewhere) 

ENTRY  Start,  /primary  entry  point  to  boot  our  OS 

ConSwitch,  /main  context  switcher 

ConSwSleep  /alternate  context  switcher  (puts 

/calling  task  to  sleep) 


Include  files  (mostly  equates) 
INCLUDE  SysEqu 


INCLUDE 

INCLUDE 


HeapDef 

SysIO 


Miscellaneous  storage 
DS.L  8 

DS.L  40 

DS.L  0 


/contains  the  low-memory  absolute 
/address  equates  (jump  table,  etc) 
/defines  the  heap  data  structure 
/contains  hardware  I/O  equates 


/heap  header  for  kernel  heap  item 
/system  stack  before  tasking  starts 
/top  of  startup  stack  area 


Pre-tasking  initialization 

this  code  works  in  single^task  mode 

prior  to  the  invocation  of  the  context  switcher 

/Initial  entry.  Calling  operating  system  is  still 
/alive  and  kicking  at  this  point. 

LEA  ReEntry,Al  /point  to  re-entry  instruction 

MOVE.L  A1,$20.W  /move  short  absolute  to  the  vector 

/for  privilege  exceptions 

MOVE  USP, AO  /try  a  privileged  instruction.  If  it 

/works,  then  we're  in  priv.  mode.  If  not,  then  trap  to 
/ReEntry  and  be  in  privileged  mode  anyway 
LEA  StackBegin, A7  /set  up  initial  stack 

Turn  off  all  interrupts  in  the  system 
Note:  this  is  device-specific  code. 

The  labels  in  the  operand  fields  are  from  our  own 
SysIO  include  file. 

CLR.B  FDCIntMask  /clear  floppy  disk  &  system  console 

CLR.B  HDIntMask  /clear  hard  disk  completion  int.  mask 

CLR.B  SerlOlIntMask  /clear  serial  boards 

CLR.B  SerI02IntMask 


Initialize  the  vector  table 

Copy  the  vectors  from  an  assembled  table  (in  another  module) 
into  the  actual  hardware  vector  list  in  low  RAM 

LEA  VecTable, AO  /source  (in  another  code  segment) 

LEA  $0.W,A1  /destination  (begins  at  $00  0000) 

MOVE  #191,  D7  /192  longwords  to  move 

MOVE.L  (A0) +,  (Al)+  /move  a  longword 

DBRA  D7,VecMove  /repeat  till  done  (fast  loop  on  68010) 

Copy  system  routine  JMP  table  from  assembled  object  code  (in 
another  module)  to  low  memory  jump  table,  where  everyone 
can  get  at  them. 

LEA  JMPTable, A0  /source 

LEA  System.W,Al  /dest.  (name  of  first  system  call  in 

/the  jump  table.  "System"  is  from  the  SysEqu  include 
/file.  It's  the  context  switcher) 

MOVE  # JMPTabLen/4,D7  /number  of  longwords  to  move 

MOVE.L  (A0)+, (Al)+  /move  a  longword 

DBRA  D7,JPIMove  /repeat  till  done  (fast  loop  on  68010) 

Clear  low  memory  to  zero  (between  jmp  table  and  kernel) 


LEA 

StackEnd,  A1 

/point  to  top  of  destination 

/and  bottom  of  destination  (end  of  the  jump  table) 

LEA 

SysterrW- JMPTabLen .  W,  A0 

SUBA 

A0,A1 

/calculate  the  length 

MOVE.L 

A1,D7 

/move  to  D7  for  counting 

LSR.L 

#4,D7 

/divide  by  16  for  16-byte  blocks 

LowClr 

CLR.L 

(A0)  + 

/clear  16  bytes,  quickly 

CLR.L 

(A0)  + 

CLR.L 

(A0)  + 

CLR.L 

(A0)  + 

DBRA 

D7, LowClr 

/do  it  until  done. 
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Clear  high  memory  to  zero  (between  kernel  and  end  of  RAM) 
(RAMEnd  is  first  byte  beyond  RAM,  defined  in  SysEqu) 


LEA 

RAMEnd,  Al 

/point  to  top  of  destination 

/and  bottom 

of  destination  (end  of  the  jump  table) 

LEA 

KernEnd,  AO 

SUBA 

A0,A1 

/calc  the  length 

MOVE.L 

A1,D7 

/move  to  D7  for  counting 

LSR.L 

#4,D7 

/divide  by  16  for  16-byte  blocks 

CLR.L 

(AO)  + 

/clear  16  bytes,  quickly 

CLR.L 

(AO)  + 

CLR.L 

(AO)  + 

CLR.L 

(AO)  + 

DBRA 

D7,HiClr 

/do  it  until  done. 

Initialize  all  of  the  primary  I/O  devices 

Note:  this  is  a  device  specific  routine  not  treated  in  the  article. 
JSR  IOInit 


Initialize  the  heap 

Note:  this  is  a  routine  in  the  heap  manager,  which  creates 
valid  heap  headers  for  the  three  initial  heap  items  discussed 
in  the  text:  the  deletion  below  the  kernel,  the  kernel  code 
item,  and  the  deletion  above  the  kernel. 

JSR  Heaplnit 

Initialize  the  system  zone  of  low  memory 

Note:  this  sets  up  the  TCB  and  master  handle  arrays,  as 

discussed  in  the  text,  as  well  as  initializing  the  time  of  day  and 

the  date  and  the  other  miscellaneous  system  values. 

JSR  Syslnit 

Spawn  off  the  initial  tasks 

This  will  create  TCBs  and  TData  items  for  the  tasks,  but  won't 
invoke  them.  They're  invoked  only  by  the  context  switcher. 

LEA  SysConMon,AO  ;point  to  system  console  entry  point 

MOVE.L  #4096, DO  ;tell  it  how  much  RAM  for  TData 

JSR  Spawn  ;jump  through  jump  table  entry 

;  ("Spawn"  is  a  jump  table  equate  in  SysEqu) 

LEA  HeapMunger,A0  ; spawn  the  heap  munger 

MOVE.L  #512, DO  ;heap  munger 's  TData  size 

JSR  Spawn 

LEA  DiskMunger,  AO  ;  Spawn  the  disk  munger 

MOVE.L  #8192, DO  ; (TData  includes  one  disk  buffer) 

JSR  Spawn 


TCB1.W,A2 


;get  address  of  first  TCB  in  array 
; (TCB1  is  defined  in  SysEqu) 

;now  start  the  context  switcher! 


Context  Switcher:  primary  version 
Simple  task-switch,  nothing  fancy. 

SysFlags  is  a  low-RAM  system  flag  byte,  defined  in  SysEqu. 

The  data  structure  for  the  TData  item  is  defined  in  SysEqu. 

The  data  structure  for  the  TCB  is  defined  in  SysEqu. 

BTST  #StopSys, SysFlags. W  ;task  switching  inhibited? 

BNE.S  ConSwX  ;yes,  exit  back  to  caller 

MOVE.L  OurTCB  (A5)  ,A0  ;get  TCB  address  from  TData 

SUBA.L  A5,SP  /subtract  TData  base  addr  from  stack 

MOVE.L  SP,TCBSP(A0)  /save  relative  displacement  in  TCB 


TCBNxt  (AO)  ,A2 
TCBA5  (A2) ,  A5 
TCBSP  (A2) ,  SP 
A5,SP 


/get  address  of  next  TCB 
/get  new  TData  base  address 
/get  stack  relative  displacement 
/restore  absolute  address 
/return  to  next  task 


ConSwSleep 


Context  Switcher:  alternate  version 
Put  the  calling  task  to  sleep. 

BTST  #StopSys, SysFlags. W  /task  switching  inhibited? 

BNE.S  ConSwX  /yes,  exit  back  to  caller 

/without  going  to  sleep 

MOVE.L  OurTCB (A5) ,  AO  /get  TCB  address  from  TData 

SUBA.L  A5,SP  /subtract  TData  base  addr  from  stack 

MOVE.L  SP, TCBSP (AO)  /save  relative  displacement  in  TCB 

MOVE.L  TCBNxt  (AO)  ,A2  /get  address  of  next  TCB 

MOVE.L  TCBPrev (AO) , A1  /get  addr  of  previous  TCB 

MOVE.L  A2, TCBNxt (Al)  /close  the  pointers  around  the  now- 

MOVE.L  Al, TCBPrev  (A2)  /sleeping  task. 

MOVE.B  # Sleep, TCBState (AO)  /mark  it  as  asleep 


TCBA5  (A2)  ,A5 
TCBSP  (A2)  ,  SP 
A5,  SP 


/get  new  TData  base  address 
/get  stack  relative  displacement 
/restore  absolute  address 
/return  to  next  task 


End  Listing 
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8080  SIMULATOR 


LISTING  ONE  (Text  begins  on  page  76) 

XXXXXXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXXKXXXXXXXKXXXXXXKXXXXXX 


8080  Simulator  for  MC68000 

Uith  CP/M  2.2  call  support,  optional  tracing  and 
Morrow  HDDMA  DMA  buffer  translating. 


*  Version  1.2  1/21/85  JEC  x 

*  Fixed  Extent  bug  in  OPEN  logic.  # 

*  Sped  up  code,  sample  MAC  from  2:13  to  1:40.  # 

*  Now  runs  at  a  1.4  MH2  equivalent  based  on  MAC  sample.  * 

*  Version  1.1  8/29/84  JEC  x 

*  Fixed  BDOS  call  /6  bug.  x 

x  H 

*  Version  1.0  05/25/84  by  Jim  Cathey  x 

*  x 

*  This  program  has  been  written  for  speed  wherever  possible,  * 

*  as  such  tends  to  be  large  because  of  the  separate  subroutine  # 

*  for  each  and  every  opcode  of  the  target  processor.  # 

*  x 

*  On  an  8MHz  68000  (Compupro)  system  the  simulation  speed  is  # 

*  a  little  better  than  a  1MHz  Z-80  when  running  MAC.  The  time  # 

*  for  a  sample  assembly  was  2:13  for  the  simulation  vs  0:35  * 

*  on  a  4MHz  Z-80,  both  systems  used  identical  hard  disk  systems.  * 

*  x 

*  It  is  not  a  complete  simulation,  as  some  flag  handling  # 

*  isn't  quite  right,  but  it  is  enough  to  run  the  programs  # 

*  I  wrote  it  for  (DDT,  LU,  MAC,  and  Morrow's  FORMATMU).  * 

*  x 
XXXXXXXXXXXXXXXXXXXXXKKXXXXKXXKXXXXXKKXKXXXXXXXKXXXXXKKKXXXXXXXXXXXXXXXXX 

text 

page 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

*  X 

*  This  file  contains  the  startup  routines,  the  simulator  core,  * 

*  tracing  code,  and  the  CP/M  2.2  simulation.  x 


bne  optprnt 
rts 

optprnt  equ  # 

ifne  trcdsk 
lea.l  fcbmsg, 
bsr  lpstr 
endc 


;  If  FCB  tracing,  print  header. 


mloop:  # 

"^mloop: 

ifne  trace 
tst  traceflg 
bne  dotrace 

cmpa.l  tracesad.pseudopc 
bne  notrace 
move.b  /I .traceflg 
dotrace  bsr  dump 

cmpa.l  traceead.pseudopc 
bne  notrace 
move.b  /0, traceflg 
notrace  equ  * 
endc 

moveq  /0,d0  ; 

move.b  ( pseudopc )+,d0  ; 

asl  /2,d0  ; 

move.l  0(opptr,d0.w) ,a0 
Jmp  (a0)  ; 


Execute  simulation 


;  Optional  trace. 


Execute  appropriate  simulation  subroutine 
Grab  next  opcode. 

(D0  high  word  is  still  0t) 

To  the  subroutine. 


page 

XXXXKXKXXKXKXXXXXXKXXXXXXKXXXKXXXXXXXXXKXXKXXKXXXXXXXXXXXXXXXXXXXKXXXXXXX 


Illegal  instructions  and  Dumping. 


XXXXXXXXXXXXXXXXXXXXXXXXXXXMXXXXXXXXKXXXXXXKXXXXXXKXXXXXXXXKXXXKXXXXXKXKX 


XXMXKKXXXKXXXXXXXXXXXXXKXMKKKKXKXX 


XXXXXXXXXXXXKXXXKXXXXKXXKXXKXXKXXKKXXXX 

xdef  optabl , flags, mnops 
globl  mloop, illegl .service 


*  Conditional  assembly  flags. 

x 

trace  equ  0  ;  Non-zero  for  trace  routine  inclusion, 

trcdsk  equ  0  ;  Non-zero  for  FCB  trace  routine  inclusion, 

dmpdsk  equ  0  ;  Non-zero  for  register  dump  in  FCB  trace. 

*  11  diskio  is  in  file  COM2.S  !! 

“diskio  equ  0  ;  Non-zero  for  special  HDDMA  support. 


Register  definitions  for  the  simulation. 


return 

pseudopc 

opptr 

pseudosp 

flagptr 

targbase 

regs 

regcon0e 

regcon01 

regcon0f 

regconff 

regf 

rega 


equ  8l6,r 
equ  0 1 5 , r 
equ  014,r 
equ  0 1 3 , r 
equ  01 2, r 
equ  0 1 1 , r 
equ  @1 1 ,r 
equ  7,r 
equ  6,r 
equ  5,r 
equ  4,r 
equ  3,r 
equ  2,r 


JMP  (return)  is  fast  return  to  MLOOP. 
8080's  PC  is  register  A5. 

Pointer  to  opcode  dispatch  table. 

8080's  SP  is  register  A3. 

Pointer  to  8080's  flag  lookup  table  is  A2. 
Pointer  to  8080's  address  space  is  A1. 

Base  pointer  to  8080's  registers  is  A1 . 
Register  based  constant  /$ E  (for  speed). 
Register  based  constant  /$!. 

Register  based  constant  /$F. 

Register  based  constant  /$FF. 

8080’s  Flags 
8080's  Accumulator 


Note,  only  leaves  D0-D1/A0  for  free  use  by  entire 
program  without  saving  registers  for  temporary  use. 


bdos  .opd  0,$4e42  ;  BDOS  'macro', 
bios  .opd  0,$4e43  ;  BIOS  'macro'. 


page 

XXXXXXKKXXXXXXXXKXXXXKXXXXXKXXXXXMXXXXXXXXXKXXXKXKXKKXKXXXXXXXXXXKXXXXXXX 


Initialization  and  Main  Opcode  dispatcher. 


XXXXXKKXXXXKKXXKXXXXXXXXXXXKXKXXXXXXXKXKXXXXXXXKXXKXXXKXXXXXXKKXXXXKXXXXX 


lea.l  target, targbase 
ifne  trace 
bsr  entrads 

endc 

bsr  lodfdos 
bsr  lodregs 
bsr  loadcom 
tst  d0 


Start  of  target  memory. 

Optional  trace  code. 

Enter  trace  delimiting  addresses 
if  the  code  is  desired. 

Load  up  the  fake  FDOS  in  target  mem. 
Load  the  remaining  simulation  registers- 
Load  the  .COM  program, 
quit  if  unsuccessful. 


illegl  move.l  /illgmsg.dl 
move.w  /9,d0 
bdos 

lea.l  -1 (pseudopc) ,a0 

move.b  (a0),d1 

suba.l  targbase,a0 

bsr  pbyte 

move.l  /ilgmsg2,d1 

move.w  /9,d0 

bdos 

move.l  a0,d1 
bsr  pword 
move.l  /ilgmsg3,d1 
move.w  /9,d0 
bdos 

move.l  /dumpmsg.dl 
move.w  /9,d£J 
bdos 

bsr  dump 
rts 

page 

dump  movem.l  d0-d1/a0,-(sp) 
move.l  /dmpmsg2,d1 
move.w  /9,d0 
bdos 

move.b  rega.dl 
bsr  pbyte 
move.b  regf.dl 
bsr  pbyte 
bsr  pspace 
move.w  regb(regs) ,d1 
bsr  pword 
bsr  pspace 
move.w  regd(regs) ,d1 
bsr  pword 
bsr  pspace 
move.w  regh(regs) ,d1 
bsr  pword 
bsr  pspace 
move.l  pseudosp, dl 
sub.l  targbase, dl 
bsr  pword 
bsr  pspace 
move.l  pseudosp, a0 
swap  d2 
move.w  /3,d2 

tosloop  move.b  1(a0),d1 
ror.w  /8,d1 
move.b  0(a0),d1 
bsr  pword 
bsr  pspace 
addq.l  /2,a0 
dbra  d2, tosloop 
swap  d2 

move.l  pseudopc, dl 
sub.l  targbase, dl 
bsr  pword 


Illegal  opcode,  say  what  &  where, 


and  spill  guts. 
Quit  simulation. 


;  Dump  all  registers, 

;  used  for  illegals  and  tracing. 


Save  REGA 
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bsr  pspace 
bsr  pspace 
move.b  (pseudopc) ,d1 
bsr  pbyte 

bsr  pspace  ;  Now  show  mnemonic 

bsr  pspace 

moveq  /0,d0 

move.b  (pseudopc) ,d0 

asl.w  /2,d0 

lea.l  mnops,a0 

move.l  (a0,d0.1),d1 

move. 1  dl ,-(sp) 

inc.l  dl 

move  /9,d0 

bdos 

move.l  (sp)+,a0 
cmp.b  t"  '’,(a0) 
beq  nooprnd 
cmp.b  /"C” ,(a0) 
bne  notcons 
move.b  1 (pseudopc) ,d1 
bsr  pbyte 
bra  nooprnd 

notcons  cmp.b  /"A",(a0) 
bne  nooprnd 
move.b  2(pseudopc) ,d1 
bsr  pbyte 

move.b  1 (pseudopc) , d 1 
bsr  pbyte 

nooprnd  bsr  pspace  ;  In  case  of  conout  calls  during  trace, 

bsr  pspace  ;  they  will  be  visible  at  end  of  line, 

bsr  pspace 

movem.l  (sp)+,d0-d1/a0 
rts 

page 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

X  X 

*  Initialization  subroutines.  * 

x  x 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

lodfdos  lea.l  fdos,a6  ;  Load  up  the  fake  FDOS. 


move.l  targbase.pseudosp 
adda.l  /$10000,pseudosp 
lea.l  -256(pseudosp) ,a0 
move.w  /fdoslen,d0 
lodloop  move.b  (a6)+,(a0)+ 
dbra  d0, lodloop 
lea.l  -256(pseudosp) ,a0 
move. 1  a0,d0 
sub.l  targbase,d0 

move.b  /$c3,0( targbase)  ;  Build  BIOS  &  BDOS  jumps. 

move.b  /$c3, 5 (targbase) 

move.b  d0, 6 (targbase) 

rol .w  /8,d0 

move.b  d0, 7 (targbase) 

rol.w  /8,d0 

add.w  /3,d0 

move.b  d0, 1 (targbase) 

rol.w  /8,d0 

move.b  d0,2(targbase) 

move.w  /0,-(pseudosp)  ;  Set  up  a  return  stack  to  exit  simulation, 
rts 


lodregs  lea.l  optabl.opptr  ;  Point  base  register  to  opcode  dispatch 

table. 

lea.l  mloop.return 
lea.l  flags, flagptr 
move . 1  targbase , pseudopc 

adda.l  /$100, pseudopc  ;  Start  execution  at  0100H  in  target  space. 

moveq  /$e,regcon0e  ;  Set  up  quick  constants. 

moveq  /$1,regcon01 

moveq  /$f,regcon0f 

move.l  /$ff .regconff 

moveq  /0,rega 

moveq  /0,regf 

rts 

page 

entrads  move.l  /tracemsg.dl  ;  Enter  trace  address  if  necessary, 
move.w  /9,d0 
bdos 

(Continued  on  neyt  page) 
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8080  SIMULATOR 


LISTING  ONE  (Listing  Continued,  text  begins  on  page  76) 


;  Get  trace  start  address. 


bsr  atol 
and. 1  /$ff ff ,d1 
move. 1  dl ,a0 
adda.l  targbase,a0 
move.l  a0,tracesad 
move.l  /tracerag2,d1 
move.w  /9,d0 
bdos 

bsr  atol 
and. 1  /Sffff.dl 
move. 1  dl ,a0 
adda.l  targbase,a0 
move.l  a0,traceead 
move.w  /10,d1 
move.w  /2,d0 
bdos 

move.w  /13,d1 
move.w  /2,d0 
bdos 
rts 


OPEN  file  to  be  loaded,  and  load  it  into  target 
space  if  successful. 


;  Get  trace  end  address. 


;  CRLF  to  end  line. 


loadcom  link  a6,/0  • 

movem.l  d2-d3/a2-a4 ,-(sp) 
move.l  12(a6),a0  ; 

lea.l  $5c(a0),a2  ; 

move.b  /' C' ,9(a2)  ; 

move.b  /’O' , 10(a2) 
move.b  /’M',11(a2) 
move.l  a2,d1 
move.w  /15,d0 
bdos  ; 

cmpi .w  /255,d0  ; 

beq  openerr 

move.l  pseudopc,d2  ; 

filelod  move.l  d2,d1  ; 

move.w  /26,d0 
bdos 

move.l  a2,dl 

move.w  /20,d0  ; 

bdos 

tst  d0 

bne  basepg 

add. 1  /128,d2 

bra  filelod 


Hark  stack  frame. 

Get  the  address  of  the  base  page. 
Get  FCB  address, 
mash  filename  to  .COM 


OPEN  file. 
ERROR? 


Start  loading  at  $0100  in  target. 
Set  DMA  address. 


;  Read  file  until  EOF. 


basepg  lea.l  $80(targbase> ,a2 
move.l  a2,d1 
move.l  a2,dmaaddr 
move.w  /26,d0 
bdos 

lea.l  $38(a0),a2 
lea.l  $5c(targbase) ,a3 
move.w  /36,d0 
fcbloop  move.b  (a2)+,(a3)+ 
dbra  d0, fcbloop 
lea.l  $80(a0),a2 
lea.l  $80(targbase) ,a4 
lea.l  $81 (targbase) ,a3 
clr  d0 

move.b  d0,(a4) 
move.b  (a2)+,d0 
taill  cmp.b  /$20,(a2)+ 
dbeq  d0f taill 
bne  loaded 

tail2  cmp.b  /$20,(a2)+ 
dbne  d0,tail2 
beq  loaded 
dec.l  a2 
subq  /2,d0 

tail3  move.b  (a2)+,(a3)+ 
inc.b  (a4) 
dbra  d0,tail3 
move.b  /0,(a3) 
bra  loaded 

openerr  move.l  /opnmsg.dl 
move.w  /9,d0 
bdos 
clr  d0 


Set  up  the  target's  base  page. 
Start  with  default  DMA  address. 


Copy  host’s  2nd  FCB  to  target's  1st  FCB. 


Grab  command  tail  from  host's  buffer. 
Hack  off  7.COM  filename. 

If  there’s  any  tail  left,  then 
remove  leading  whitespace. 


;  Move  the  rest  of  the  tail. 


;  Can’t  open  file. 


loaded  movem.l  (sp)+,d2-d3/a2-a4 


page 

XXKXXXXXXXXXXXXXXXXXXXXKXXXXXXXXKXXXKXXXXKXXKXXXXXXXXXXXXXKXXXXXXXXXXXXXX 


BIOS  and  BDOS  service  request  handler. 


XXXXXXXXXXXKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKXXXXXXXXXXXKXKXXXXXXXXXXX 


service  moveq  /0,d0 

move.b  (pseudopc)+,d0 
bne  biosfn 

bdosfn  moveq  /0,d1 

move . b  regc ( regs ) , d0 
move.w  regd(regs) ,d1 
cmp  /3 1 ,d0 
beq  badbdos 
cmp  /27,d0 
bne  okbdos 

badbdos  move.l  /ilgbdos.dl 
move.w  /9,d0 
bdos 

bsr  dump 
bra  quitprg 

okbdos  cmp  /9,d0 
bit  noconv 
cmp  /14,d0 
beq  noconv 
cmp  /32,d0 
beq  noconv 
cmp  /37,d0 
beq  noconv 
add.l  targbase, dl 

noconv  cmp  /26,d0 
bne  notdma 
move.l  dl.dmaaddr 

notdma  move.b  /0,fcbflag 
cmp  /15,d0 
bit  notfcb 
cmp  /24,d0 
bit  fcb 
cmp  /30,d0 
beq  fcb 
cmp  /33,d0 
bit  notfcb 
cmp  /37,d0 
bit  fcb 
cmp  /40,d0 
beq  fcb 
bra  notfcb 

page 

fcb  swap  d2 

move.w  /35,d2 
move.l  dl ,a0 
move.l  al ,-(sp) 
lea.l  fcbstor.al 

fcbl  move.b  (a0)+,(a1)+ 

dbra  d2,fcb1 
move.l  (sp)+,a1 
lea.l  fcbstor,a0 
move.b  33(a0) ,d2 
move.b  35(a0) ,33(a0) 
move.b  d2,35(a0) 
swap  d2 

move.b  /I .fcbflag 
move.l  dl ,-(sp) 
move.l  a0,d1 
ifne  trcdsk 
ifne  dmpdsk 
bsr  dump 
endc 
endc 

cmp.w  /15,d0 
bne  notopen 
tst .b  12(a0) 
beq  notopen 
bsr  openproc 
bra  results 

notopen: 

"’“'notopen: 

ifne  trcdsk 
move.l  d2,-(sp) 
move.b  /’  ’ ,d2 
bsr  fcbtrcl 
move.l  (sp)+,d2 
endc 


notfcb  cmp  /6,d0 

bne  notdcon 
cmp.b  /$ff,d1 
bne  notdcon 
move.w  /$fe,d1 
bdos 
tst  d0 
beq  results 
move.w  /6,d0 
move.w  /$FF,d1 

notdcon  bdos 

results  move.w  d0,regh(regs) 
move.b  d0,rega 


Handle  BIOS/BDOS  service  request 
of  form  HLT  DB  opcode. 

BDOS  or  BIOS? 

Get  BDOS  function  number. 

Get  argument. 

Can't  do  Disk  Parm  Hdr  function 
or  ALLOC  vector  fn. 


Translate  target  address  to  real  address. 


Save  last  known  DMA  address 
(in  case  of  OPEN  processing). 

Separate  FCB  type  requests 
from  the  rest  of  the  swine. 
(Assume  not,  at  first). 


Move  the  FCB  to  host  working  buf, 


and  swap  the  random  record  bytes 
to  make  them  match  the  68000's. 


Set  flag  for  proper  recovery. 
(Gotta  put  the  pig  back  in  pen!) 


Optional“2  Register  dump. 


OPEN  has  a  problem  in  that  CP/M-68K 
can  only  open  the  base  extent,  unlike 
CP/M-80.  So  we  have  to  check  and  do 
an  OPEN  then  SEEK  (RREAD)  if  required. 


;  Optional  FCB  trace. 


Not  an  FCB  request.  Is  it 
a  direct  console  I/O  function? 

Yes,  make  host's  look  like  target's. 


FINALLY!  Do  the  translated  function. 
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move.b  regh(regs) .regb(regs) 

tst.b  fcbflag  ;  Do  ue  need  to  restore  a  FCB? 

beq  done 

lfne  trcdsk 

bsr  fcbtrc2 

endc 

lea.l  fcbstor,a0  ;  Restore  the  FCB  to  target,  in  proper 

order. 

swap  d2 

move.b  33(a0) ,d2 
move.b  35(a0) ,33(a0) 
move.b  d2,35(a0) 
move.l  (sp)+,a0 
move. 1  al ,-(sp) 
lea.l  fcbstor.al 
move.w  /35,d2 
fcb2  move.b  (a1)+,(a0)+ 
dbra  d2,fcb2 
swap  d2 

move.l  (sp)+,a1 
done  move.b  rega,d0 

and.w  regconff,d0 

move.b  0(flagptr,d0.w) ,regf 

rts 


openproc: 

'w~openproc: 

ifne  trcdsk  ;  Optional  FCB  trace. 

swap  d2 

move.b  /’  ' ,d2 

bsr  fcbtrcl 

swap  d2 

bsr  fcbtrc2a 

endc 

move.b  33(a0),-(sp)  ;  Save  away  RR  fields! 

move.b  34(a0),-(sp) 

move.b  35(a0) , - ( sp ) 

movem.l  d0-d2,-(sp) 

moveq  /0,d2 

move.b  12(a0),d2  ;  Save  desired  extent, 

clr.b  1 2 ( a0 ) 


bsr  fcbbdos 
tst.b  d0 
bmi  badopen 
asl.l  /7,d2 
moveq  /0,d0 
move.b  32(a0) ,d0 
bclr  /7,d0 
add.l  d2,d0 
move.w  d0,34(a0) 
swap  d0 

move.b  d0,33(a0) 
move.l  /Junkbuf.dl 
move.w  /26,d0 
bdos 

movem.l  (sp)+,d0-d2 
move.w  /33,d0 
bsr  fcbbdos 
clr  d0 

# 

# 

movem.l  d0-d1,-(sp) 
move.w  /26,d0 
move.l  dmaaddr.dl 
bdos 

movem.l  (sp)+,d0-d1 

restore  move.b  (sp)+,35(a0) 
move.b  (sp)+,34(a0) 
move.b  (sp)+,33(a0) 
rts 

badopen  movem.l  (sp)+,d0-d2 
bra  restore 


fcbbdos: 

fcbbdos: 

ifne  trcdsk 
move.l  d2,-(sp) 
move.b  /'+' ,d2 
bsr  fcbtrcl 
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;  Do  BDOS  (with  opt.  tracing). 

;  No  seek  if  not  good  OPEN. 

;  Make  EXTENT  /  into  record  offset. 


;  Add  onto  CR  to  make  abs  record  /. 
;  Put  into  FCB. 


;  Set  DMA  addr  elsewhere  for  Rand  Seek. 


Random  READ  (SEEK)  desired  extent. 

Do  BDOS  (with  opt.  tracing). 

(OPEN)  must  always  be  successful  because 
of  the  way  CP/M-80  &  CP/M-68K  differ 
on  OPENing  non-2ero  extents. 

Restore  the  proper  DMA  address. 


;  Restore  RR  fields. 


;  BDOS  call  with  optional  FCB  trace. 


(Continued  on  neyt  page) 
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8080  SIMULATOR 


LISTING  ONE  (Listing  Continued,  text  begins  on  page  76) 


move.1  (sp)+,d2 

endc 

bdos 

ifne  trcdsk 
bsr  fcbtrc2 
endc 
rts 


fcbtrc2a: 

movem.l  d0-d1,-(sp) 

bra  fcbtr21 

endc 


;  Line  termination  if  no  result 
;  is  to  be  presented. 


page 

MNMMMMMMMMMMMMMNMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMXM 


biosfn  cmp  /I  ,d0  ; 

beq  quitprg 

cmp  /$fpd0  ; 

beq  gudbios 
cmp  /7,d0 

bge  badbios  ; 

gudbios  clr.w  dl 

move.b  regc(regs) ,d1 
movem.l  d2-d7/a0-a6,-(sp) 
bios 

movem.l  (sp)+,d2-d7/a0-a6 

move.b  d0,rega 

rts 

badbios  move.b  d0 , — ( sp )  ; 

move.1  /biosrasg.dl  ; 

Bove.w  /9,d0 
bdos 

move.b  (sp)+,d1 
bsr  pbyte 
move.l  /biosmg2,d1 
move.w  /9,d0 
bdos 

bsr  dump 


Handle  Bios  calls. 


;  List  Status  is  ok. 


*  Misc.  service  routines.  * 

*  (Inelegant,  but  rarely  used  so  they  stand  as  is).  * 

M  M 

MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMNMMMMMMMMMMMMMMMMMMMMNMMMMMMMMMMMMMMM 


Don't  allow  disk  functions! 


Flag  illegal  BIOS  call 
and  spill  guts. 


quitprg  move.l  (sp)+,d0 
rts 


Trash  return  address  and 
quit  simulation. 


FCB  Tracing  support  routines. 


mmmnmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmnmmmmmmmmmmmmmmmmxmmmmm 


movem.l  d0-d2/a0,-(sp) 

;  Dump  to  printer  each  FCB  usage 

move.b  /9,d1 

;  in  format  FN  /,  Disk,  Name  (ASCII) 

bsr  lpchar 

;  and  the  rest,  all  in  hex  but  the 

move.w  d0,d1 

;  name  field.  Print  the  returned 

bsr  lpbyte 

;  value  after  the  FCB. 

move.b  d2,d1 

;  Char  in  D2  is  printed  after  FN  /. 

bsr  lpchar 

bsr  lpspace 

bsr  lpspace 

move.b  (a0)+,d1 

bsr  lpbyte 

bsr  lpspace 

move.w  /10,d2 

move.b  (a0)+,d1 

;  Print  Name  field. . . 

bsr  lpchar 

dbra  d2,fcbtr1 

bsr  lpspace 

move.w  /3,d2 

pbyte  move.l  /$20018,d0 
bra  pdigits 

pword  move.l  /$40010,d0 
bra  pdigits 

paddr  move.l  /$60008,d0 
bra  pdigits 

plong  move.l  /$80000,d0 
pdigits  rol.l  d0,dl 
bra  pdigent 
pdiglop  swap  d0 

rol.l  /4,d1 
bsr  ntoa 
pdigent  swap  d0 

dbra  d0, pdiglop 
rts 

ntoa  movem.l  d0-d 1 , - ( sp ) 
and  /$f,d1 
cmp  /$a,d1 
bit  ntoa2 

add.b  X* A*- '9* -1 ,dl 
ntoa2  add.b  /'0',d1 
move.w  /2,d0 
bdos 

movem.l  (sp)+,d0-d1 
rts 

pspace  move.w  /32,d1 
move.w  /2,d0 
bdos 
rts 


2  nybbles,  24  bit  shift  first. 

4  nybbles,  16  bit  shift  first. 

6  nybbles,  8  bit  shift  first. 

8  nybbles,  no  shift  first. 

Do  shift. 

Save  nybble  count. 

Print  variable  in  dl . 

Get  nybble  count. 

Nybble  in  dl  to  ASCII,  then  output. 


;  Print  a  space. 


page 

Line  Printer  versions  of  above 


fcbtr2  move.b  (a0)+,d1 
bsr  lpbyte 
bsr  lpspace 
dbra  d2,fcbtr2 
bsr  lpspace 
bsr  lpspace 
lea.l  I6(a0),a0 
move.w  /3,d2 

fcbtr3  move.b  (a0)+,d1 
bsr  lpbyte 
bsr  lpspace 
dbra  d2,fcbtr3 
bsr  lpspace 
bsr  lpspace 
move.l  dmaaddr.dl 
sub.l  targbase.dl 
bsr  lpword 
bsr  lpspace 

movem.l  (sp)+,d0-d2/a0 
rts 

page 

fcbtrc2  movem.l  d0-d1,-(sp) 
bsr  lpspace 
bsr  lpspace 
move.b  d0,d1 
bsr  lpbyte 

fcbtr21  move.b  /10,d1 
bsr  lpchar 
move.b  /13,d1 
bsr  lpchar 
movem.l  (sp)+,d0-d1 
rts 


Skip  d0. .dn  field. 


lpbyte  move.l  /$20018,d0 
bra  lpdigts 

lpword  fflove.l  /$40010,d0 
bra  lpdigts 

lpaddr  move.l  /$60008,d0 
bra  lpdigts 

lplong  move.l  /$80000,d0 
lpdigts  rol.l  d0,d1 
bra  lpdgent 
lpdiglp  swap  d0 

rol.l  /4,d1 
bsr  lntoa 
lpdgent  swap  d0 

dbra  d0, lpdiglp 
rts 

lntoa  movem.l  d0-d1,-(sp) 
and  /$f,d1 
cmp  /$a,d1 
bit  lntoa2 
add.b  /,A’-,9'-1 ,d1 
lntoa2  add.b  /’0' ,d1 
lntoa3  move.w  /5,d0 
bdos 

movem.l  (sp)+,d0-d1 
rts 


lpchar  movem.l  d0-d1,-(sp) 
bra  lntoa3 

lpspace  movem.l  d0-d1,-(sp) 
move.w  /32,d1 
bra  lntoa3 


2  nybbles.  24  bit  shift  first. 

4  nybbles,  16  bit  shift  first. 

6  nybbles,  8  bit  shift  first. 

8  nybbles,  no  shift  first. 

Do  shift. 

Save  nybble  count. 

Print  variable  in  dl . 

Get  nybble  count. 


;  Nybble  in  dl  to  ASCII,  then  output. 


Print  a  character. 


Print  space. 


;  Line  termination  of  FCB  trace. 


Remaining  misc.  service  routines. 


lpstr  movem.l  d0-d1,-(sp) 
lpstrl  move.b  (a0)+,d1 
beq  lpstr2 
bsr  lpchar 
bra  lpstrl 


;  Print  a  null-terminated  string. 
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lpstr2 

movem.l  (sp)+,d0- 

dl 

even 

rts 

regop3 

equ  -9  ; 

Operan 

1  for  DAA  storage. 

regb 

equ  -8  ; 

Offset 

from  register  base  pointer  for 

regc 

equ  -7  ; 

8080's 

pseudo-registers. 

konin 

move.v  /I ,d0 

Console  Input  for  'atol'. 

regd 

equ  -6 

A  &  F 

ire  in  Data  Registers. 

bdos 

rege 

equ  -5  ; 

Pseudo 

-PC  is  kept  in  an  Address  Register. 

rts 

regh 

equ  -4 

regl 

equ  -3 

regopl 

equ  -2  ; 

Operan 

1  for  DAA  storage. 

atol 

moveq  /0,d1 

ASCII  to  long,  stops  on  Invalid  hex  char. 

regop2 

equ  -1  ; 

" 

2 . 

clr  d2 

Returns  long  In  dl,  terminator  char  In  d0, 

atoll 

bsr  konin 

d2*1  If  any  chars  entered  before  terminator. 

fcbstor 

ds.b  36  : 

Host  works  FCB's  out  of  here. 

cmp.b  /$40,d0 

fcbflag  ds.b  1  ; 

Flag  says  we  used  the  FCB  buffer. 

bio  atol2 

and  /$5F,d0 

Mask  to  upper  case. 

even 

atol2 

cmpl.b  /’0' ,d0 

Check  range  (0..9,A..F). 

tracesad  ds.l  1  ; 

Trace 

tart  address. 

bio  atolend 

traceead  ds.l  1 

Trace 

nd  address. 

cmpl.b  /'F' pd0 

traceflg  ds.w  1  ; 

Tracing  enabled  flag. 

bhl  atolend 

cmpl.b  /’9’  ,d0 

dmaaddr 

ds.l  1  ; 

DMA  address  storage. 

bis  atol3 

cmpl.b  /'A' ,d0 

page 

bhs  atol3 

fdos 

dc.b  $76,0,$C9  ; 

Fake  BDOS  for  target  system. 

bra  atolend 

X 

; 

BIOS  Jump  Table 

atol3 

moveq  /I ,d2 

Valid  characters  entered,  flag  It. 

dc.b  $C3,$33,$FF 

Uboot 

sub.b  /'0' ,d0 

dc.b  $C3,$36,$FF 

Const 

cmp.b  /$9,d0 

dc.b  $C3,$39,$FF 

Con  in 

bis  atol4 

dc.b  $C3,$3C,$FF 

Conout 

sub.b  X *  A ’ -  * 9 * ~ 1 ,d0 

dc.b  $C3,$3F,$FF 

List 

atol4 

ext  d0 

To  long. 

dc.b  $C3,$42,$FF 

Punch 

ext.l  d0 

dc.b  tC3,S45,$FF 

Reader 

asl.l  /4,d1 

Tack  It  onto  Dl . 

dc.b  $C3,$48,$FF 

Home 

add. 1  d0,d1 

dc.b  $C3.$4B,$FF 

Seldsk 

bra  atoll 

dc.b  $C3,$4E,$FF 

Settrk 

atolend 

rts 

dc.b  $C3,J51,$FF 

Setsec 

dc.b  $C3,$54,$FF 

Setdma 

page 

dc.b  $C3,$57,$FF 

Read 

data 

dc.b  $C3,$5A,$FF 

Write 

XXXXXXX 

XKKXXKXXXXXXXKXXXXXXXXXXKXXXXKXXKXXXKXKXXXXXXXXKXXXKKXXXKXKKXXXK 

MX 

dc.b  $C3,$5D,$FF 

Llstst 

X 

X 

dc.b  $C3,*60,SFF 

Sectran 

X 

Target  processor 

s  data  registers. 

X 

X 

Fake  FDOS. 

X 

X  # 

XXKKXXXKXXXXKXKXXXXXXXXXXXXXKKXXXXXXXXXXXXKKXXXK XX XXXXXXX X XX XXXXXXXXKXX XX 

( Continued  on  neyt  page) 
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8080  SIMULATOR 


LISTING  ONE  (Listing  Continued,  text  begins  on  page  76) 


dc.b  $76,1 ,$C9 
dc.b  $76,2,$C9 
dc.b  $76,J,$C9 
dc.b  $76,4,$C9 
dc.b  $76,5,$C9 
dc.b  $76,6,$C9 
dc.b  $76,7,$C9 
dc.b  $76,8, $C9 
dc.b  $76,9,$C9 
dc.b  $76, 10 ,SC9 
dc.b  $76,1 1 ,$C9 
dc.b  $76, 12,$C9 
dc.b  $76,15,$C9 
dc.b  $76, 14,$C9 
dc.b  $76, 15 ,$C9 
dc.b  $76 ,16, $C9 

fdoslen  equ  *-fdos 


BIOS  for  target  system 
;  Const 
;  Conln 
;  Conout 
;  List 
;  Punch 
;  Reader 
;  Home  # 

;  Seldsk  * 

;  Settrk  * 

;  Setsec  * 

;  Setdma  * 

;  Read  * 

;  Write  * 

;  Llstst 
;  Sectran  * 


regconff  equ  4,r 


regop3  equ  -9 
regb  equ  -8 


regi  equ  -> 
regopl  equ  -2 
regop2  equ  -1 


Register  based  constant  /$FF. 

Often  used  constants  /0  &  /8  are  predominantly 
used  by  Instructions  that  have  'quick*  modes 
which  encompass  these  values  —  no  register 
needed  (or  available,  either). 

8080's  Flags 

8080’s  Accumulator 

Operand  3  for  DAA  storage. 

Offsets  from  register  base  pointer  for 

8080’s  pseudo-registers. 

A  &  F  are  in  Data  Registers. 

Pseudo-PC  is  kept  in  an  Address  Register. 


Operand  1  for  DAA  storage. 
"  2  "  " 


page 

*  *  X  *  *****  X  XXX  X  XXX  X  X  X  XXXX  X  X  *  X  X  X  X  XXXX  tt  XX  XX  KXK  XXX  X  XX  X  M  X  it  X  X  X  X  X  X KMX  X  X  X  XXX X  X  XXX 

#  X 

#  Messages.  * 

*  * 
XXXXXXXXXXXXXXKXXXXXXXXXKXXXXXKXKXXXXKXXXKXXXXXXXXXXXXKXKXXXXXKXXXXXXKXXX 

illgmsg  dc.b  $d,$a, ' Illegal  instruction  $' 
ilgmsg2  dc.b  '  at  $' 
ilgmsg3  dc.b  ' .$' 

dumpmsg  dc.b  $d,$a, 'Register  contents:$' 
dmpmsg2  dc.b  $d,$a 

dc.b  '-AF-  -BC-  -DE-  -HL-  -SP-  -S0-  -SI-  -S2-  -S3-  -PC-  -op-’,$d, 
$a, ’$’ 

biosmsg  dc.b  $d,$a, ’ Illegal  BIOS  call  $’ 
biosmg2  dc.b  ’ .$' 

tracemsg  dc.b  13,10, 'Start  trace  at  >$’ 
tracemg2  dc.b  13, 10, 'End  trace  at  >$' 
opnrasg  dc.b  'Cannot  open  .COM  file.S’ 
llgbdos  dc.b  'Unsupported  BDOS  call. S' 

fcbmsg  dc.b  9,’Fn/  Dr  NAME  EX  SI  S2  RC  CR  R0  R1  R2  Addr  Rslt' 
,10,13 

dc.b  9,* - * 


XXXXXXXXXXXXXXXKXKXXKKXXXXKXKXXXKXXMXXXKXNXXXXXKXXMXXXXXXXXXXXXXXXXXXXXXX 


page 
even 
optabl  dc.l 


movebm.moveba 

movecm.moveca 

movedm.moveda 

moveem.moveea 

movehm.moveha 

movelm.movela 

halt.movema 

moveam.moveaa 


Target  processor’s  address  space. 


XXXXKXMXKXXXXXXXXXXNXXXXXMXXXKKXXXKXMXKXXKKMXKXXXXXKXXXXKXXXXXXXKXXXXXXKK 


even 

registers  ds.b  10 
target  ds.b  $10001 
Junkbuf  ds.b  $80 
.end 


Actual  storage  for  8080's  other  registers. 
8080's  universe. 

For  BDOS’  OPEN  faking  (RREAD  buffer). 


End  Listing  One 


nop00 , lxib , staxb , inxb , inrb , dcrb , mvib , rlca 
nop08,dadb, ldaxb.dcxb, inrc.dcrc.mvic.rrca 
nop10,lxid,staxd, inxd, inrd,dcrd,mvid,ral 
nopl 8 , dadd , ldaxd , dcxd , inre , dcre , mvie , rar 
nop20, lxlh,shld,inxh, inrh,dcrh,mvih,daa 
nop28 , dadh , lhld , dcxh , inrl , dcrl , mvil , cma 
nop30 , lxis , sta , inxs , inrm , derm , mvim , stc 
nop38 , dads , Ida , dexs , inra , dcra , mvia , cmc 
movebb , movebc , movebd ,  ifiovebe , movebh , movebl , 
moveeb , movecc , movecd , movece , movech , moved , 
movedb , movedc , movedd , movede , movedh , movedl , 
moveeb , moveec , moveed , moveee , moveeh , moved , 
movehb , movehc , movehd , movehe , raovehh , movehl , 
move lb .move lc , move Id , movele , movelh , move 1 1 , 
movemb , movemc , movemd , moveme , movemh , moveml , 
moveab , moveac , movead , moveae , moveah , moveal , 
addb , addc , addd , adde , addh , addl , addm , addaa 
adeb ,  adcc ,  aded ,  adee ,  adch ,  add ,  adem ,  adca 
subb ,  subc ,  subd ,  sube ,  subh ,  subl ,  subrn ,  subaa 
sbbb , sbbe , sbbd , sbbe , sbbh , sbbl , sbbm , sbba 
andb , andc , andd , ande , andh , andl , andm , anda 
xrab , xrac , xrad , xrae , xrah , xral , xram , xraa 
orab , orac , orad , orae , orah , oral , oram , oraa 
empb , empe , empd , empe , emph , cmpl , empam , empaa 
rnz , popb ,  J  nz ,  J  mpa , enz , pushb , adi , rst0 
rz, ret, Jz.nopCB.cz, cal l,aci,rst8 
rnc , popd , J  nc , out , cnc , pushd , sui , rst 1 0 
rc , nopD9 , J  c , in , cc , nopDD , sbi , rst 1 8 
rpo , poph , j  po , xthl , epo , pushh , ani , rs t20 
rpe , pehl , j  pe , xchg , epe , preED , xrl , r st28 
rp , popp , jp , di , cp , pushp , oria , rst30 
rra.sphl , Jra,ei,cm,nopFD,cpi,rst38 


page 

XXXHXXKXXXMXXXKKXXXXXKXXMXKKXXXXMXXKXXKKXXXXXXXXXXKXXXKXXXXXXXXXXMXKXKKXX 


Flag  register  lookup  tables. 


XXXKXXXKXXXXKXXKXXXXXXXXXKXXKXKXXKXKXXXXKXMXXXXXXXXXXXKXXXXXXXKXXMXXXXXXK 

flags  dc . b  $00 , $0 1 , $04 , $05 , $40 , $4 1 , $44 , $45 , $80 , $8 1 , $84 , $85 , $C0 , $C1 , $C4 , $C5 


LISTING  TWO 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

*  X 

H  This  file  contains  the  target  processor  (8080)  simulation  * 

*  routines.  x 

*  x 
XXKXKXXMXXXXXXXXXXXXXXXXXKXMKXXXXXXXXXXXXXXXXKKXKXXXKXXKXXKXXXXKMKXXXXKXX 

XKXXXXXXXXXXXXXKMXXKMXXXXXXKXXXXXXXXXXXKXXXKXXKKKXXXXXXXKXXKXXXXXXXXXXKXK 

*  X 

*  Opcode  dispatch  table.  One  longvord  entry  per  opcode  of  the  * 

*  target  (8080)  processor,  including  illegals.  * 

*  x 
XXKKXXXXXXXKXXXXMXXXXXXKXXKXXXXXXXXXXXXXKXXXXXXXXXXXXXXHXXXKXXXXXXXXKXKXX 


dc.b  $44, 
dc.b  $00, 
dc.b  $00, 
dc.b  $04, 
dc.b  $00, 
dc.b  $04, 
dc.b  $04, 
dc.b  $00, 
dc.b  $80, 
dc.b  $84, 
dc.b  $84, 
dc.b  $80, 
dc.b  $84, 
dc.b  $80, 
dc.b  $80, 
dc.b  $84, 


$00,  $00,  $04,: 
$04, $04, $00,: 
$04,  $04,  $00,: 
$00,  $00,  $04,: 
$04, $04 ,$00, 
$00, $00, $04, 
$00, $00, $04, 
$04, $04, $00, 
$84, $84, $80, 
$80, $80, $84, 
$80, $80, $84, 
$84. $84, $80, 
$80, $80, $84. 
$84, $84, $80, 
$84, $84, $80, 
$80, $80, $84, 


I, $00, $04, $04,: 
.,$04, $00, $00, 
.,$04, $00, $00, 
l,$00,$04,$04, 
,,$04, $00, $00, 
I, $00  ,$04  ,$04  , 
l,$00,$04,$04, 

.  ,$04 ,$00 ,$00, 
,,$84, $80, $80, 
I, $80, $84, $84, 
l,$80,$841$84, 

I  ,$84 ,$80, $80, 

I,  $80, $84, $84, 
[,$84, $80, $80, 
[,$84, $80, $80, 

J,  $80, $84 ,$84, 


1, $00, $00, $04 
3 ,$04 ,$04 ,$00 

3,  $04, $04, $00 

4,  $00, $00, $04 

3,  $04 ,$04, $00 
1, $00, $00, $04 

4,  $00 ,$00, $04 
3, $04, $04, $00 

3,  $84, $84, $80 

4,  $80, $80, $84 
4, $80, $80, $84 

3,  $84, $84, $80 

4,  $80, $80, $84 
3, $84, $84, $80 

3 , $84 ,$84 ,$80 

4,  $80, $80, $84 


globl  optabl , flags, nop00 

xdef  mloop, illegl .service, preED, outspec 


return  equ  @ 1 6 , r 
pseudopc  equ  @15, r 
opptr  equ  814,r 
pseudosp  equ  @13, r 
flagptr  equ  @12, r 
targbase  equ  0 1 1 , r 
regs  equ  @1 1 ,r 

regcon0e  equ  7,r 
regcon01  equ  6,r 
regcon0f  equ  5,r 


Non-zero  for  special  HDC/DMA  support. 

JMP  (return)  is  fast  return  to  MLOOP. 
8080’s  PC  is  register  A5. 

Pointer  to  opcode  dispatch  table. 

8080's  SP  is  register  A3. 

Pointer  to  8080's  flag  lookup  table  is  A2. 
Pointer  to  8080’s  address  space  is  A1. 

Base  pointer  to  8080's  registers  is  A1 . 

Register  based  constant  /$E  (for  speed). 
Register  based  constant  /$1 . 

Register  based  constant  /$F. 


page 

XXKXKXXXXXXXXXXXKXXKXXXXKXXXXXXXXKKXXKXXXXKXXXXXXXXXXKXKXXXXXXXXXXKXKXXXK 
X  H 

*  Opcode  simulation  subroutines.  # 

*  x 

*  Note:  I/O  instructions  are  based  at  68000  address  $FF0000  * 

*  as  is  appropriate  for  the  CompuPro  CPU-68K  card.  * 

*  x 

Also,  all  routines  assume  that  the  high  word  of  D0  *  0!  * 

*  x 
XXXXXXttXKXXXMXXKXXXXXXXXKXXXXXKXMKXKXKXMMXXKXXXKXKKXXKXXXKXXXKXXXXKMXXXMX 


nop00  Jmp  (return) 
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lxib 

move.b  (pseudopc)+,regc(regs) 
move.b  (pseudopc)+,regb(regs) 

Jmp  (return) 

;  01  Lxl  BC.nnnn 

staxb 

nove.w  regb(regs) pd0 
move.b  rega,0(targbase,d0. 1) 

Jmp  (return) 

;  02  Stax  B 

inxb 

inc.w  regb(regs) 

Jmp  (return) 

;  03  Inx  B 

inrb 

lnc.b  regb(regs) 
move  sr,d0 
and.w  regcon0e,d0 
and.v  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 

Jmp  (return) 

;  04  I nr  B 

dcrb 

dec.b  regb(regs) 
move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 

Jmp  (return) 

;  05  Dcr  B 

mvib 

move.b  (pseudopc)+,regb(regs) 

Jmp  (return) 

;  06  Mvi  b,nn 

rlca 

rol .b  / 1 ,rega 

;  07  Rlc 

docyf 

bcs  riel 
bclr  /0,regf 

Jmp  (return) 

riel 

bset  /0pregf 

Jmp  (return) 

nop08 

bra  illegl 

;  08  Illegal  for 

dadb 

move.w  regb(regs) ,d0 
add.w  d0,regh(regs) 
bra  docyf 

;  09  Dad  B 

ldaxb 

move.w  regb(regs) ,d0 
move.b  0(targbase,d0.1) ,rega 

Jmp  (return) 

;  0A  Ldax  B 

dcxb 

dec.w  regb(regs) 

Jmp  (return) 

;  0B  Dcx  B 

inrc 

lnc.b  regc(regs) 
move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 

Jmp  (return) 

;  0C  Inr  C 

dcrc 

dec.b  regc(regs) 
move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 

Jmp  (return) 

;  0D  Dcr  C 

mvlc 

move.b  (pseudopc)+,regc(regs) 

Jmp  (return) 

;  0E  Mvi  C 

rrca 

ror.b  /I ,rega 
bra  docyf 

;  0F  Rrc 

nop  10 

bra  Illegl 

;  10  Illegal  for  8080 

lxld 

move.b  (pseudopc)+,rege(regs) 
move.b  (pseudopc)+,regd(regs) 

Jmp  (return) 

;  11  Lxl  DE , nnnn 

staxd 

move.w  regd(regs) ,d0 
move.b  rega,0(targbase,d0.1) 

Jmp  (return) 

;  12  Stax  D 

inxd 

lnc.w  regd(regs) 

Jmp  (return) 

;  15  Inx  D 

(Continued  on  neyt  page) 
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LISTING  TWO  (Listing  Continued,  text  begins  on  page  76) 


inrd  inc.b  regd(regs)  ;  14  Inr  D 

move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

dcrd  dec.b  regd(regs)  ;  15  Dcr  D 

move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr ,d0.w) ,regf 
Jmp  (return) 

mvid  move.b  (pseudopc)+,regd(regs)  ;  16  Mvi  D,nn 

Jmp  (return) 

ral  roxr.b  /l.regf  ;  17  Ral 

roxl .b  /I ,rega 
roxl.b  /l.regf 
Jmp  (return) 

nop 18  bra  illegl  ;  18  Illegal  for  8080 

dadd  move.w  regd(regs) ,d0  ;  19  Dad  D 

add.w  d0,regh(regs) 
bra  docyf 

ldaxd  move.w  regd(regs) ,d0  ;  1A  Ldax  D 

move.b  0(targbase,d0. 1) ,rega 
Jmp  (return) 

dcxd  dec.w  regd(regs)  ;  IB  Dcx  D 

Jmp  (return) 

lnre  Inc.b  rege(regs)  ;  1C  Inr  E 

move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 
Jmp  (return) 

dcre  dec.b  rege(regs)  ;  ID  Dcr  E 

move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 
Jmp  (return) 

mvle  move.b  (pseudopc)+,rege(regs)  ;  IE  Mvi  E,nn 

Jmp  (return) 

rar  roxr.b  /l.regf  ;  IF  Rar 

roxr.b  /I ,rega 
roxl.b  /I ,regf 
Jmp  (return) 

nop20  bra  illegl  ;  20  Illegal  for  8080 

lxih  move.b  (pseudopc)  +  ,regl(regs)  ;  21  Lxl  H.nnnn 


move.b  (pseudopc)+, regh(regs) 

Jmp  (return) 

shld  move.b  1 (pseudopc) ,d0  ;  22  Shld  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
move.l  d0,a0 
adda.l  targbase.a0 
move.b  regl(regs) , (a0)+ 
move.b  regh(regs) , (a0) 

Jmp  (return) 

inxh  lnc.w  regh(regs)  ;  23  Inx  H 

Jmp  (return) 

inrh  Inc.b  regh(regs)  ;  24  Inr  H 

move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 .regf 
or.b  0(flagptr,d0.w) ,regf 
Jmp  (return) 

dcrh  dec.b  regh(regs)  ;  25  Dcr  H 

move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 .regf 
or.b  0(flagptr,d0.w) ,regf 
Jmp  (return) 

mvih  move.b  (pseudopc)+,regh(regs)  ;  26  Hvl  H,nn 

Jmp  (return) 

daa  move.b  regop3(regs) ,d0  ;  27  Daa 

roxr.b  d0 

move.b  regop2(regs) ,d0 
move.b  regopl (regs) ,d1 
swap  regcon0e 
move.b  rega,regcon0e 
and.b  regcon0f ,regcon0e 
cmp.b  /9,regcon0e 
bhi  halfcy 
and.b  regcon0f,d0 
and.b  regcon0f,d1 
orl.b  /$f0,dl 
addx.b  d0,d1 
bcc  nohalf 

halfcy  add.b  /6,rega 
bcs  fullcy 

nohalf  btst  /0,regf 
bn2  fullcy 

move.b  rega,regcon0e 
and.b  /$f0,regcon0e 
cmp.b  /$90,regcon0e 
bis  nofull 


(Listings  to  be  Continued  next  month) 
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LISTING  ONE  (Text  begins  on  page  118) 


;  DUMMY  SEGMENT  TO  BE  GROUPED  WITH  HIMEM,  WHICH 
;  IS  AN  EMPTY  SEGMENT  AT  THE  END  OF  THE  USER'S 
;  PROGRAM 

HIMEM  GROUP  HIDATA 

HIDATA  SEGMENT  COMMON  'HIMEM' 

FLARB  DW  0 
HIDATA  ENDS 


;  'MAIN'  IS  THE  PROGRAM'S  ENTRY  POINT, 

;  JUST  ABOVE  THE  PSP 

EXTRN  MAIN: FAR 

ARCODE  SEGMENT  PUBLIC  'CODE' 

ASSUME  CS: ARCODE 
PUBLIC  FREMEM 

FREMEM  PROC  FAR 

PUSH  BP  ;  STANDARD  ENTRY  STUFF 

MOV  BP, SP 

;  GET  THE  ADDRESS  OF  HIMEM,  THE  TOP  OF  THE 
;  USER'S  PROGRAM,  STICK  IT  IN  USER'S  VARIABLE 

MOV  AX, SEG  HIDATA  ;  GET  TOP  SEGMENT 

LES  BX, 18 [BP]  ;  SEND  IT  TO  THE  USER 

MOV  ES: [BX] , AX 


FIND  OUT  HOW  MUCH  MEMORY  IS  AVAILABLE  ABOVE 
HIMEM  BY  REQUESTING  A  LOT  OF  MEMORY. 

THE  CALL  TO  FUNCTION  4AH  NEEDS  THE  SEGMENT 


ADDRESS  OF  THE  PROGRAM'S  PSP.  GET  IT  BY 
SUBTRACTING  10  PARAGRAPHS  FROM  THE  SEGMENT 
OF  THE  PROGRAM'S  ENTRY  POINT,  WHICH  HAS  THE 
LABEL  'MAIN'. 


MOV 

AX, SEG  MAIN 

/  GET  ENTRY  SEGMENT 

SUB 

AX, 10H 

/  ADJUST  TO  GET  PSP 

MOV 

ES,  AX 

/  PUT  VALUE  INTO  ES 

MOV 

BX,  -ID 

/  GET  ALL  OF  MEMORY 

MOV 

AX, 4  AO  OH 

/  DOS  FUNCTION  CODE 

INT 

21H 

/  DO  IT 

THE  NUMBER  OF  AVAILABLE  PARAGRAPHS  IS  IN  BX, 
RETURN  IT  TO  USER. 

LES  DI , 1 4 [ BP ]  ;  STORE  IT  IN 

MOV  ES: [DI] , BX  ;  USER'S  VARIABLE 


TRY  TO  ALLOCATE  THE  PARAGRAPHS  REQUESTED. 
A  VALUE  OF  -1  MEANS  DON'T  ALLOCATE  ANY. 


LES  DI, 10 [BP] 
MOV  BX,  ES: [DI] 
CMP  BX, -ID 
JE  OK 

MOV  AX, SEG  MAIN 
SUB  AX, 10H 
MOV  ES, AX 
MOV  AX, 4 AO OH 
I NT  21H 
JNA  ERR 

OK:  XOR  AX,  AX 

ERR:  LES  BX, 6 [BP] 

MOV  ES: [BX] , AX 


GET  THE  USER'S 
VARIABLE 

SHOULD  WE  ALLOCATE? 
NO,  BAIL  OUT 
GET  ENTRY  POINT 
ADJUST  TO  GET  PSP 
PUT  IT  IN  ES 
DOS  FUNCTION  CODE 
DO  IT 

CHECK  FOR  ERRORS 
NONE,  CLEAR  FLAG 
STORE  ERROR  CODE 
IN  USER'S  VARIABLE 


THAT'S  IT 


MOV  SP, BP  ;  STANDARD  EXIT  STUFF 

POP  BP 
RET  16 


FREMEM  ENDP 


ARCODE  ENDS 
END 


End  Listing  One 


LISTING  TWO 

;  Michael  Barr's  32-bit  Square 

;  Call  with  CX:BX  =  argument 
;  Returns  BX  -  result 


sqrt  proc  near 

push  ax 

push  dx 

push  di 

jcxz  sqrt 3 

mov  dx,  cx 

mov  di,-l 

sqrtl:  shl  dx,l 

jc  sqrt2 

shl  dx,  1 

jc  sqrt2 

shr  di,l 

jmp  sqrtl 

sqrt 2 :  mov  dx, cx 

mov  ax,  bx 

anp  dx,  di 

jae  sqrt 4 

div  di 

cmp  ax,  di 

jae  sqrt 4 

add  di,ax 

rcr  di, 1 

jmp  sqrt 2 

sqrt 3:  mov  dx,bx 

mov  di, Offh 

or  bx, bx 

jnz  sqrtl 

mov  di,bx 

sqrt4:  mov  bx,di 

pop  di 

pop  dx 

pop  ax 

ret 

sqrt  endp 


Root  Routine 

;CX:BX  =  argument 
;save  other  registers 

; prepare  first  try 

/estimating  size  of  arg. 
;to  guess  initial  try 

/restore  argument 
/prevent  overflow 

/ comp  quotient  and  divisor 

/average  them 

/and  do  it  again 
/prepare  first  try 

/lower  half  zero? 

/no,  jump 

/return  result  in  BX 


End  Listings 
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16-BIT  SOFTWARE  TOOLBOX 


One  of  the  more  ominous  devel¬ 
opments  in  the  last  few  months 
is  the  appearance  of  so-called  Trojan 
horse  programs  on  some  public  bul¬ 
letin  board  systems.  These  have  ap¬ 
peared  under  such  names  as  EGABTR, 
VDIR,  and  SYSUTIL.  They  are  usually 
accompanied  by  scanty  documenta¬ 
tion  that  bills  them  as  super  disk  di¬ 
rectories  or  something  similar,  but 
their  actual  effect  is  to  trash  your  sys¬ 
tem  by  formatting  the  hard  disk, 
erasing  the  file  allocation  table,  or 
writing  random  garbage  into  files.  I 
put  the  people  who  create  and 
upload  such  programs  to  public  BBSs 
in  the  same  category  as  terrorists. 

Along  similar  lines,  some  villains 
have  taken  advantage  of  their  knowl¬ 
edge  of  the  public-domain  PC  remote 
BBS  to  upload  programs  that  purport 
to  paint  a  pretty  picture  on  the  screen 
or  do  something  else  cute  but  actually 
copy  the  password  file  or  other  vital 
system  files  to  (unprotected)  files  un¬ 
der  another  name.  The  villain  calls 
back  later  and  downloads  the  unpro¬ 
tected  files,  thereby  gaining  access  to 
privileged  files  and  messages. 

As  the  computer  terrorists  become 
more  clever,  we  can  expect  the  ap¬ 
pearance  of  subtle  sabotage  pro¬ 
grams  that  copy  themselves  to  hid¬ 
den  files  on  the  hard  disk  or  attach 
themselves  to  the  bootable  operating 
system  and  don't  do  their  damage 
until  much  later.  For  example,  I  can 
envision  a  hard  disk  destruction  pro¬ 
gram  that  would  wait  until  it  saw 
that  you  had  not  run  Backup  for  a 
week!  The  nature  of  the  damage 
could  also  be  so  subtle  that  it  would 
drive  you  crazy,  such  as  simply 
changing  a  bit  in  a  random  sector  of 


by  Ray  Duncan 

The  programs  published  in  this 
month's  column  are  available  for 
downloading  from  the  Laboratory  Mi¬ 
crosystems  RBBS  at  (213)  306-3530  (300 
baud  or  1,200  bps). 


rrojan  Horse  Programs 


the  hard  disk  every  few  days. 

These  developments  have  the  po¬ 
tential  to  damage  or  destroy  the  pro¬ 
liferation  of  public-domain  software 
on  bulletin  boards,  which  would  be 
very  sad.  BBS  operators  will  not  want 
to  take  the  risk  of  being  held  liable  for 
disasters  due  to  Trojan  horse  pro¬ 
grams.  On  the  LMI  RBBS,  we  are  im¬ 
mediately  adopting  a  policy  of  delet¬ 
ing  all  programs  that  are  not 
uploaded  in  the  form  of,  or  at  least 
accompanied  by  source  code  as  a 
clear-text  ASCII  file.  I’d  like  to  hear 
comments  from  readers  on  this  sub¬ 
ject,  especially  those  who  have  been 
victims  or  who  can  provide  actual 
samples  of  these  Trojan  horse  pro¬ 
grams. 

EXEC  Calls  and  FORTRAIV 

Robert  Sypek  of  a  firm  called  Argis  in 
Hudson,  Massachusetts,  writes: 
“While  attempting  to  write  a  pro¬ 
gram  that  would  execute  a  user  or 
system  task  from  a  user  program,  I 
ran  into  many  of  the  problems  de¬ 
scribed  in  past  issues  about  using  the 
DOS  2.y  EXEC  function  call.  My  prob¬ 
lems  were  compounded  by  the  fact 
that  Microsoft’s  languages  (FORTRAN, 
Pascal,  C)  set  up  their  own  data  and 
stack  segments,  and  the  code  segment 
is  that  of  the  user  program  or  subrou¬ 
tine,  not  the  segment  of  the  root  pro¬ 
gram.  This  means  that  the  program 
segment  prefix  (PSP)  is  inaccessible 
from  any  routine  called  by  a  user  pro¬ 
gram.  All  is  not  lost,  however,  as  I  be¬ 
lieve  I  have  found  a  method  of  re¬ 
trieving  the  necessary  information  to 
allow  an  EXEC  function  to  be  called. 

“The  method  depends  on  two 


pieces  of  information  that  may  be 
gleaned  from  the  Microsoft  user 
manuals:  the  compiler  defines  a  null 
segment  called  HIMEM  that  is  placed 
at  the  end  of  all  other  segments 
when  the  user  program  is  loaded, 
and  the  compiler  defines  a  symbol 
called  MAIN  that  is  located  directly 
after  the  PSP.  Both  the  segment  and 
the  symbol  have  the  PUBLIC  attribute, 
making  them  accessible  to  the  user. 

"The  segment  of  the  PSP  may  be 
found  by  subtracting  10H  from  the 
segment  of  MAIN,  yielding  the  value 
of  the  ES  register  needed  for  the  call 
to  EXEC.  The  value  of  HIMEM  can  then 
be  used  to  calculate  the  size  of  the 
user  program  and  the  segment  of  the 
next  available  paragraph  of  memo¬ 
ry” 

Mr.  Sypek  enclosed  an  assembly- 
language  subroutine  that  we  are 
printing  as  Listing  One  (page  116). 
The  routine  is  invoked  in  the  form: 

CALL  FREMEM(MEMPTR,MEMAVL, 
MEMALL.ERR) 

where  MEMPTR  is  the  segment  value 
of  the  next  available  paragraph,  ME- 
MAVL  is  the  number  of  paragraphs 
available,  and  MEMALL  is  a  user-de¬ 
fined  variable  specifying  the  amount 
of  memory  above  the  program  to 
leave  allocated  to  the  user.  (A  value  of 
—  1  leaves  all  memory  allocated  to  the 
program.)  An  error  code  of  0  indicates 
that  the  function  was  successful. 

Lightweight  Reading 

Those  who  think  the  mainframe 
mentality  is  gone  forever  should 
read  Martin  Healy's  article  “Toward 
a  Viable  OS  for  the  PC”  ( Datamation , 
September  1985).  At  first  I  took  this 
article  for  a  practical  joke  because  it 
contains  so  many  distortions  of  the 
history  and  current  state  of  the  art  in 
microcomputers,  sideways  slams  at  a 
variety  of  targets,  and  outrageous 
gobbledygook  (example:  "PC  Net¬ 
work  could  be  the  answer,  but  it 
won’t  share  data,  only  the  file”). 


118 


Dr.  Dobb's  Journal,  January  1986 


The  author  asserts  that  "there  are 
in  fact  two  leading  real  operating 
systems  for  micros,  Unix  and  Con¬ 
current  DOS  from  Digital  Research.” 
He  goes  on  to  say  "The  new  Version 
4.1  [of  Concurrent  DOS]  is  the  ideal¬ 
ized  multitasking  PC  DOS,  which  due 
to  its  maturity  should  eliminate  any 
Microsoft  version  (PC  DOS  4.0?)  there¬ 
of.  That  leaves  Microsoft  to  concen¬ 
trate  on  its  Unix-like  system,  Xenix.”  I 
am  sure  the  folks  at  Microsoft  will  be 
very  relieved  to  learn  from  Mr.  Hea- 
ly  that  they  no  longer  have  to  waste 
all  that  effort  on  maintaining  MS  DOS, 
can  take  MS  DOS  4.0  out  of  testing  and 
toss  it  in  the  trash  can,  and  turn  their 
attention  to  other  matters. 

Square  Roots 

Michael  Barr  of  the  Department  of 
Mathematics  at  McGill  University 
sent  us  his  8086  assembly-language 
subroutine  for  square  roots  (Listing 
Two,  page  116).  He  writes:  "This  rou¬ 
tine  gives  the  correct  floored  square 
root  for  any  32-bit  number  (consid¬ 
ered  as  unsigned).  It  is  also  faster 
than  the  bit-at-a-time  algorithms  you 
have  put  into  DDJ. 

"Apropos  that  last  statement,  there 
seems  to  be  a  discussion  between 
people  who  believe  that  Newton's 
method  is  always  the  best  way  to  do 
a  square  root  and  others  who  believe 
equally  fervently  that  the  bit-at-a- 
time  method  is  always  faster.  Com¬ 
mon  sense  would  dictate  that  they 
are  both  wrong.  I  strongly  suspect 
that  Newton's  method  is  faster  if  and 
only  if  you  have  an  on-chip  (or  co¬ 
processor)  division  of  the  relevant 
size.  In  particular,  to  do  a  32-bit 
square  root,  you  need  a  32-bit  by  16- 
bit  division.  This  much  I  have  tested; 
Newton's  method  is  just  about  twice 
as  fast  (about  330  msec,  compared  to 
about  650  msec  for  the  bit-at-a-time). 
What  I  haven’t  tested  (I  can't  face  the 
thought  of  programming  them)  are 
64-bit  square  roots.  But  there  is  every 
reason  to  believe  that  it  will  be  faster 
to  do  the  bit-at-a-time  square  root 
than  to  code  division  and  then  use 
that  for  Newton’s  method.” 

Big  DOS 

The  new  wave  of  PCs,  based  on  the 
80286  microprocessor,  are  still  limited 
to  1  megabyte  of  direct  memory  ad¬ 
dressing  because  they  run  MS  DOS  or 
its  clones  in  8086  emulation  mode 
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(called  Real  Mode  by  Intel).  The  ability 
of  the  80286  to  address  16  megabytes 
of  RAM  in  "Protected  Virtual  Memory 
Mode”  is  currently  supported  only  by 
the  80286  Xenix  and  iRMX-286  operat¬ 
ing  systems,  neither  of  which  is  likely 
to  become  very  popular  due  to  their 
incompatibility  with  WordStar, 
dBASE  III,  and  Lotus  1-2-3.  The  aver¬ 
age  user's  exploitation  of  the  full  ca¬ 
pabilities  of  the  PC/AT  and  other  such 
machines  awaits  the  arrival  of  an  op¬ 
erating  system  that  runs  in  Protected 
Mode  and  can  execute  the  popular 
MS  DOS  applications  unaltered. 

Such  an  operating  system  has  been 
the  subject  of  much  industry  rumor 
and  speculation.  Digital  Research  has 
been  talking  about  “Concurrent  DOS- 
286”  for  some  time  now,  even  an¬ 
nouncing  the  operating  system's 
"immediate  availability”  at  a  press 
conference  in  New  York  about  six 
months  ago.  (See  "Concurrent  DOS- 
286:  Available  Now,”  Intel  Speak  Soft¬ 
ly  Quarterly,  vol.  2,  no.  2,  Second 
Quarter  1985.)  But  lately  DRI  has  been 
backpedaling  a  bit  and  now  admits 
that  80286  Concurrent  DOS  will  prob¬ 
ably  never  exist  in  the  form  original¬ 
ly  advertised.  Of  course,  the  compa¬ 
ny  is  blaming  its  problems  on 
"defects”  in  the  80286  design.  (When 
in  doubt,  fall  back  on  the  classic  pro¬ 
grammer’s  defense:  "It  must  be  a 
hardware  problem.”) 

Microsoft  Corp.  is  also  known  to  be 
working  on  a  Protected  Mode,  up- 
ward-compatible  version  of  PC  DOS 
(already  dubbed  Big  DOS  by  the  trade 
rags  and  assumed  to  be  Version  5.0). 
But  Microsoft  has  been  very  close¬ 
mouthed  about  these  efforts,  pre¬ 
sumably  wanting  to  make  sure  it  can 
pull  it  off  before  committing  itself  to 
such  a  product  in  public.  Too  bad  DRI 
wasn't  that  careful! 

Ross  Nelson,  who  previously 
worked  on  the  80286  team  at  Intel, 
took  the  time  to  write  to  us  with 
some  musings  on  the  future  of  DOS 
and  Protected  Mode.  He  says,  "With 
regard  to  the  286  in  the  marketplace, 
it  seems  to  me  that  unless  a  compara¬ 
tively  low-cost  system  (PC/I I?)  is  in¬ 
troduced,  there  won't  be  a  lot  of 
work  done  that  will  take  advantage 
of  Protected  Mode  (PM).  The  installed 
base  of  AT  users  vs.  the  number  of 
PC-compatible  users  will  make  it  eco¬ 
nomically  unfeasible.  Once  people 
do  start  working  with  PM,  they  will 


encounter  some  interesting  prob¬ 
lems.  The  great  virtue  of  PM  is  that 
no  task  in  the  system  should  be  able 
to  corrupt  another  task  (assuming  the 
operating  system  is  stable).  As  a  soft¬ 
ware  engineer,  I  applaud  this  philos¬ 
ophy,  and  I  believe  that  this  use  of 
the  286  should  be  encouraged.  Realis¬ 
tically,  however,  it  is  clear  that  there 
will  be  a  transition  period  in  which 
PM  will  only  be  used  to  gain  access  to 
the  larger  memory  space. 

Nelson  wrote:  “As  far  as  I  can  tell, 
there  are  only  two  ways  of  switching 
back  to  Real  Mode  when  you  are  in 
Protected  Mode,  and  only  one  of  them 
is  feasible  with  the  standard  80286 
part.  This  is  essentially  the  method 
IBM  has  chosen  [in  the  VDISK  driver 
supplied  with  PC  DOS  3.x  .  .  .  RD], 
which  is  to  place  enough  state  infor¬ 
mation  to  restart  your  process  in  a 
safe’  location  and  RESET  the  proces¬ 
sor.  The  other  method  requires  a  spe¬ 
cial  bond-out'  part  (which  Intel  uses  in 
its  12-ICE).  By  activating  a  special  pin 
on  the  bond-out  chip,  you  can  issue 
special  instructions  that  dump  and  re¬ 
store  the  internal  state  of  the  machine, 
including  the  Machine  Status  Word. 
Systems  built  with  the  bond-out  chip 
could  easily  be  toggled  between  Real 
Mode  and  Protected  Mode. 

"Whether  or  noUa  DOS  5.0  or  Big 
DOS  can  be  successful  in  emulating 
the  current  PC  system  architecture 
on  a  286  will  depend  on  how  freely 
the  implementors  translate  the  word 
compatible.  I  do  not  believe  that  100 
percent  compatibility  can  be  accom¬ 
plished  without  unreasonable  over¬ 
head.  I  suspect  that  even  partial  com¬ 
patibility  will  have  large  memory 
requirements.  It  would  not  surprise 
me  to  see  a  512K  operating  system 
with  an  additional  32K  required  on  a 
per-task  basis.  Here  is  how  I  believe 
some  of  the  problems  that  come  up 
can  be  handled: 

“Video — This  has  quite  a  few  sim¬ 
ple  solutions:  (a)  trap  each  initial  write 
to  the  display  segment,  and  replace 
the  offending  segment  register  with 
an  OS-created  descriptor;  (b)  use  the 
TopView  solution,  that  is,  require  ap¬ 
plications  to  issue  a  software  inter¬ 
rupt  to  get  the  address  of  their  own 
'local'  display  buffer;  (c)  trap  every 
display  write  and  deal  with  it  on  a 
case-by-case  basis.  Solution  (c)  is  the 
most  compatible  but  the  poorest  per¬ 
former;  (a)  is  almost  as  compatible  and 
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would  substantially  increase  perfor¬ 
mance.  Solution  (b)  is  the  best  and 
would  not  cause  a  great  deal  of  in¬ 
compatibility,  especially  with  pro¬ 
grams  that  use  installable  device 
drivers. 

“Communications — Here  we  have 
|  no  simple  solutions.  I  would  expect 
that  all  but  the  most  primitive  com- 
|  munications  applications  would 
have  to  be  rewritten.  Anything  more 
j  complicated  than  Int  14H  calls  should 
;  be  declared  incompatible  and  re¬ 
written  to  fit  the  new  OS. 

“EXE  files — Here,  the  OS  must  limit 
I  the  free-memory’  size  to  64K  of  code 
and  64K  of  data.  Programs  that  need 
more  memory  should  be  forced  to 
|  [dynamically]  allocate  it.  Because  of 
|  the  large  number  of  programs  that 
indiscriminately  load  segment  regis¬ 
ters,  however,  an  OS  might  want  to 
trap  segment  load  faults  and  attempt 
to  map  them  into  the  8086-style  phys¬ 
ical  addressing  scheme. 

“COM  files — These  programs  are 
the  most  likely  to  be  incompatible, 

I  because  they  often  load  and  stay  resi¬ 
dent  and  have  only  one  segment  (CS). 
Because  executable  segments  are 
never  writable,  an  OS  would  incur 
severe  performance  penalties  trying 
to  simulate  the  standard  DOS  mode  of 
I  operation  here.  Some  heuristics 
would  work  for  some  programs, 
such  as  loading  DS,  SS,  and  ES  with  a 
writable  alias  of  the  CS  descriptor, 

!  but  any  program  that  did  segment 
register  arithmetic  would  then  yield 
incorrect  results. 

"Obviously,  there  are  hundreds  of 
similar  problems. .  . .  The  question  is, 
what  solutions  will  the  marketplace 
accept?  It  seems  that  a  Protected 
j  Mode  286  operating  system  will  have 
to  contain  a  large  measure  of  DOS/ 
IBM  PC  compatibility  to  prevent  the 
software  gap’  problem  faced  by  the 
Macintosh,  Amiga,  etc.  Unfortunate¬ 
ly,  this  means  a  lower-performance, 
aesthetically  unpleasing  solution.  I 
would  welcome  a  radically  differ¬ 
ent,  optimized  system,  but  only  IBM 
has  the  clout  to  pull  it  off,  and  there 
would  still  be  two  important  factors: 
IBM  would  have  to  want  to  do  it,  and 
it  would  have  to  do  it  right.” 

Nothing  but  the  Best  for  IU y 
Little  Girl 

Bichard  Gaulden,  vice  president  of 
sales  and  marketing  for  EDCOM,  Inc., 


wrote  me  a  letter  describing  his  com¬ 
pany  as  a  "national  supplier  of  en¬ 
richment  materials  to  school  and  li¬ 
brary  systems.’’  His  sales  pitch 
wound  up  with  the  statements:  “ED¬ 
COM  can  free  your  distribution  chan¬ 
nels  by  marketing  software  that  be¬ 
comes  outdated  by  new  releases.  The 
educational  market  does  not  have 
j  the  need  for  constant  upgrades,  espe- 
i  cially  when  new  versions  are  more 
|  costly.”  Kind  of  gives  you  a  warm,  se- 
{  cure  feeling  about  your  kids’  educa¬ 
tion  in  computer  literacy,  doesn't  it? 

DDJ 

(Listing  begins  on  page  116) 
Reader  Ballot 
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FORUM _ 

PROFESSIONAL  PROGRAMMER 


Kitchen-Table 

Entrepreneur 


The  purpose  of  this  depart¬ 
ment  is  to  provide  infor¬ 
mation  of  use  to  profes¬ 
sional  programmers.  This 
first  installment  addresses 
itself  to  the  independent 
software  developer,  ro¬ 
mantically  and  perhaps 
not  altogether  inaccurately 
envisioned  as  working  on  a 
VAX  by  day  and  by  night 
designing  the  compiler  of 
tomorrow  on  an  XT  on  the 
kitchen  table.  We  point 
here  to  a  number  of  books 
that  might  be  of  use  to  the 
kitchen-table  entrepre¬ 
neur. 

Copyright 

Head  books  on  copyright 
with  some  caution.  Both 
copyright  law  itself  and 
the  interpretations  of  it  in 
court  have  changed  in 
their  application  to  soft¬ 
ware  publishing.  Don’t  as¬ 
sume  that  you  need  not 
copyright  your  software  if 
you  favor  a  Freeware/ 
Shareware  approach  to 
distribution. 

Renter,  Daniel.  Legal  Care 
for  Your  Software.  Berke¬ 
ley,  Calif.:  Nolo  Press,  1984. 

Read  this  for  discussion 
of  all  the  legal  issues:  work- 
for-hire  agreements,  non¬ 
disclosure  agreements, 
contracts,  license  agree¬ 
ments.  The  author  covers 
the  differences  among  and 
nuances  of  copyright, 
trade-secret  protection, 
patent,  and  trademark  reg¬ 
istration.  The  book  ex¬ 
plains  your  legal  liabilities 
and  how  international 
copyright  works.  It  has  a 
number  of  sample  forms, 
such  as  a  beta  test  site 
agreement  form. 


Salone,  M.J.  How  to  Copy¬ 
right  Software.  Berkeley, 
Calif.:  Nolo  Press,  1984. 

Read  it  for  deeper  dis¬ 
cussion  of  copyright  issues. 
What  happens  when  the 
first  500  disks  go  out  with 
no  copyright  notice  on  the 
disk  or  in  the  code?  What 
can  you  do  if  your  copy¬ 
right  is  infringed?  Hun¬ 
dreds  of  examples  are 
provided. 

Documentation 

Read  something  on  docu¬ 
mentation  and  realize  how 
important  it  is.  A  good 
manual  is,  after  all,  the  best 
copy  protection  available. 
Many  programmers  cut 
their  own  throats  by  re¬ 
leasing  good  software  with 
illiterate,  poorly  designed 
documentation.  Besides 
creating  an  aura  of  ama¬ 
teurishness  for  your  prod¬ 
uct,  such  a  manual  will 
hide  the  capabilities  of 
your  product  from  users — 
and  however  experienced 
a  programmer  you  may 
be,  the  odds  are  you're  an 
amateur  in  producing 
documentation. 

Houghton-Alico,  Doann. 
Creating  Computer  Soft¬ 
ware  User  Guides.  New 
York:  McGraw-Hill,  1985. 

Read  it  to  jog  your  mem¬ 
ory  about  some  of  the  tech¬ 
niques  available  for  com¬ 
municating  about  your 
software — maybe  what 
your  compiler  documenta¬ 
tion  needs  is  a  good  pie 
chart.  Maybe  not.  Use  the 
book  to  get  an  idea  of  what 
professional  documenta¬ 
tion  writers  have  to  do, 
though  their  tasks  are 
somewhat  different  from 
yours,  of  course. 

Stephan,  Peter  M.  Writing 
User-usable  Manuals.  Salt 
Lake  City:  Wredco  Press, 


1984. 

Read  it  as  an  example  of 
decent  low-cost  documen¬ 
tation.  The  author  has  won 
awards  for  his  documenta¬ 
tion,  and  although  the 
book  may  not  tell  you  any¬ 
thing  you  don’t  already 
know,  it  shows  that  a  man¬ 
ual  need  not  be  typeset  and 
perfect  bound. 

Strunk,  William,  and 
White,  E.B.,  The  Elements 
of  Style.  New  York:  Mac¬ 
millan,  1972. 

Read  it.  Whether  you 
write  the  documentation 
or  hire  writers,  your 
words  are  likely  to  see 
print  somewhere.  There  is 
no  more  concise  guide  to 
keeping  your  foot  out  of 
your  semiliterate  mouth 
than  this  book. 

Markets 

Read  these  if  you're  really 
an  independent  software 
developer  and  don’t  want 
to  distribute  your  prod¬ 
ucts)  yourself.  These  books 
mainly  list  software 
distributors. 

Amato,  Francis.  Guide  to 
Computer  Magazines.  Dal¬ 
las:  Steve  Davis,  1985. 

Read  it  for  a  quick  idea 
of  the  editorial  focus,  cir¬ 
culation,  and  audience  of 
selected  computer  maga¬ 
zines.  This  can  be  useful 
for  promotional  and  ad¬ 
vertising  purposes,  and 
some  of  the  magazines  are 
software  markets  in  them¬ 
selves,  publishing  pro¬ 
grams  in  their  pages  and/ 
or  on  disks. 

Hoffman,  Roger.  The  Com¬ 
plete  Software  Market¬ 
place.  New  York:  Warner 
Books,  1984. 

Read  it  for  many  reasons. 
One  reason  is  to  get  an 
overview  of  the  things  you 


need  to  know  in  running  a 
small  software  business. 
The  book  has  lists  of  distrib¬ 
utors,  including  mail-order 
companies,  electronic  dis¬ 
tributors,  and  magazines. 
There  are  also  lists  of  disk 
duplication  services,  PR 
firms,  market  research 
firms,  trade  associations 
and  shows,  seminars,  and 
conferences.  There  are 
case  studies  and  a  useful 
section  on  freebies  for  the 
independent  author. 

McGehee,  Brad  M.,  ed.  1986 
Programmer's  Market.  Cin¬ 
cinnati:  Writer’s  Digest 
Books,  1985. 

Read  it  for  publishers 
who  use  "free-lance”  mate¬ 
rial — even  the  terminology 
reflects  this  book's  heri¬ 
tage.  It  was  put  together  by 
people  who  view  the  inde¬ 
pendent  software  develop¬ 
er  as  another  kind  of  au¬ 
thor.  If  that  description  fits 
you,  this  book  may  also. 

Software  Design 

Read  this  to  remind  your¬ 
self  of  the  basic  principles 
and  also  to  learn  a  vocabu¬ 
lary  for  communicating 
the  principles  to  others. 

General  Electric.  Software 
Engineering  Handbook. 
New  York:  McGraw-Hill, 
1986. 

Read  it  for  one  approach 
to  the  management  of  large 
software  projects  when 
your  design  team  actually 
becomes  a  team.  Also  read 
its  bibliography  for  sources 
on  design  methods:  Nassi/ 
Sneiderman,  Warmer, 
Yourdon,  and  Jackson 
methodologies;  data-flow 
driven  design. 
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OF  INTEREST 


Peak  Electronics  has  an¬ 
nounced  a  68K  coproces¬ 
sor  board  that,  it  claims, 
you  can  plug  into  any 
(IEEE-696-1983)  S-100  system 
running  CP/M-2.2  and  have 
CP/M-68K  running  in  min¬ 
utes  with  no  hardware  or 
software  modifications. 
The  68K8-CP  is  a  10-MHz 
processor  card  with  an 
MC68008  (8-bit  version  of 
the  68000),  up  to  512K  RAM, 
up  to  128K  EPROM,  two  38.4 
kilobaud  serial  ports,  and 
an  8-bit  parallel  printer 
port.  The  68K8-CP  doesn't 
replace  your  current  CPU 
card  but  runs  in  conjunc¬ 
tion  with  it,  so  you  can 
jump  back  and  forth  be¬ 
tween  operating  systems. 
Peak  says  that  the  board 
will  support  Concurrent 
DOS  68K  when  it's  released. 

Speaking  of  Concurrent 
DOS  68K,  maybe  DRI  is  final¬ 
ly  going  to  exploit  the  head 
start  it  had  in  68K  develop¬ 
ment  software:  The  com¬ 
pany  was  expected  to  in¬ 
troduce  its  68K  developer’s 
kit  at  Comdex  in  Novem¬ 
ber.  With  Concurrent,  DRI 
has  two  operating  systems 
for  the  68000;  three  if  you 
count  the  GEM  windowing 
environment.  Concurrent 
DOS  68K  has  a  CP/M  front 
end  that  will  run  most  CP/ 
M-68K  programs,  and  DRI  is 
promising  GEM  support  for 
subsequent  versions  of 
Concurrent  DOS  68K. 

Speaking  of  GEM,  last 
month  we  discussed  it  and 
other  windowing  environ¬ 
ments  and,  because  of 
space  limitations,  men¬ 
tioned  only  some  of  the 


most  visible.  We  don’t  feel 
right  about  giving  all  that 
attention  to  the  big  boys 
and  never  mentioning  two 
windowing  products  we 
have  had  good  experience 
with:  Desqview  and  dVVin- 
dow.  It  was,  of  course,  not 
only  Digital  Research,  IBM, 
and  Microsoft  that  went 
windowing.  Quarter- 
deck’s  Desqview  is  an  im¬ 
pressive  competitor  to 
TopView,  which  bundled 
with  AST's  Rampage  ex¬ 
panded  memory  board, 
lets  users  run  up  to  nine 
programs  concurrently  in 
memory.  Also,  the  success 
of  the  concept  of  windows 
is  exemplified  by  its  em¬ 
ployment  in  a  nonoperat¬ 
ing  system  application  in 
the  product  dWindow.  For 
years,  Ashton-Tate’s  dBASE 
II  set  the  standard  for  aus¬ 
terity  in  user  interfaces: 
You  can  t  get  much  sim¬ 
pler  than  a  single-period 
prompt.  Liberty  Bell  Pub¬ 
lishing’s  dWindow  does  a 
dazzling  cathedral  win¬ 
dow  treatment  on  dBase  II 
(and  now  dBase  III)  that 
makes  it  look  like  an  en¬ 
tirely  different  product. 

Speaking  of  entirely  dif¬ 
ferent  products,  Answer 
Software  has  announced 
an  80286  emulator  for  de¬ 
velopers  of  80286-based 
software.  The  ICD286  con¬ 
sists  of  a  card  for  the  host 
system  (which  must  be  in 
the  IBM  PC/XT/ AT  family  or 
a  compatible),  a  Buffer  Box 
that  plugs  into  the  80286 
slot  in  the  target  system, 
and  a  symbolic  debugger. 
It  allows  uploading  and 
downloading  of  code  and 
data,  hardware  and  soft¬ 
ware  breakpoints,  single¬ 
stepping,  and  full-speed 
emulation  up  to  10-MHz 
clock  rates. 

And  speaking  of  80286 
development,  American 


ADO  has  introduced  an 
80286  board  for  Multibus 
systems.  The  SOL  C286-01 
(no  relation  to  the  Proces¬ 
sor  Technology  Sol  com¬ 
puter  of  story  and  song)  is 
being  manufactured  in  6-, 
8-,  and  10-MHz  versions 
and  has  up  to  512K  RAM,  a 
Centronics  printer  inter¬ 
face,  and  two  8-  or  16-bit 
SBX  bus  I/O  connectors. 
Then  there’s  the  ET- 
286Plus,  a  10-MHz  AT-com- 
patible  single-board  com¬ 
puter  that  uses  the  new 
1-Mb  dynamic  RAMs  and 
allows  4  megabytes  on¬ 
board.  ATS  International 
was  expected  to  show  it  at 
Comdex. 

As  long  as  we’re  speak¬ 
ing  of  the  286  and  operat¬ 
ing  systems,  we  should 
mention  Locus  Comput¬ 
ing's  Multisystem  Merge. 
This  product  allows  simul¬ 
taneous,  transparent  exe¬ 
cution  of  Unix  and  MS  DOS 
on  the  same  machine  ac¬ 
cording  to  the  company. 
You  can  set  several  Unix 
tasks  to  work  in  the  back¬ 
ground  while  you  run  a 
DOS  application  in  the  fore¬ 
ground.  This  is  the  system 
AT&T  is  using  on  its  6300-F 
Unix/DOS  computer.  Locus 
developed  some  of  the 
technology  in  the  system 
while  writing  PC-Inter- 
face,  a  product  that  links 
DOS  computers  to  a  host 
Unix  machine. 

DRI,  which  we  were 
speaking  of  a  few  para¬ 
graphs  back,  is  of  course 
not  the  only  developer  of 
operating  system  software 
for  the  68K,  as  two  recent 
announcements  prove.  U  S 
Software  has  announced  a 
real-time  multitasking  sys¬ 
tem  for  embedded  appli¬ 
cations  using  the  68K.  It’s 
ROMable,  requires  3K  of 
code  space,  and  is  called 
USX68K.  Integrated  Busi¬ 


ness  Computers  has  ported 
TheOS-16  (formerly  Oasis) 
to  its  line  of  68010  comput¬ 
ers  and  was  expected  to  be 
showing  a  beta  version  at 
Comdex. 

Speaking  of  beta-test 
versions,  Tall  Tree  Systems 
has  begun  shipping  beta 
versions  of  its  Jlaser- 
printer  interface  to  soft¬ 
ware  companies  it  deems 
closest  to  achieving  com¬ 
patible  products.  The  in¬ 
terface  is  a  PC/XT/ AT  card 
that  works  with  the  JRAM 
2-megabyte  memory 
board;  it’s  designed  to 
spend  memory  to  buy 
print  speed  and  typeface 
flexibility  for  laser  print¬ 
ers.  It  transfers  bit¬ 
mapped  images  directly 
from  RAM  to  the  print 
mechanism  and  is  sup¬ 
posed  to  provide  unlimit¬ 
ed  type  fonts  with  full 
graphics  capabilities  at  300 
dots  per  inch  in  eight 
seconds. 

Speaking  of  mucho  me¬ 
gabytes,  Reference  Tech¬ 
nology  has  announced  a 
device  that  lets  you  attach 
up  to  eight  of  its  optical 
disk  drives,  for  more  than 
4  gigabytes  of  storage  on  a 
(sturdy,  large)  desktop. 
The  device  is  PC/XT/ AT  or 
compatible  compatible. 

Speaking  of  product  an¬ 
nouncements,  Speech 
Technology  is  now  selling 
the  cross-assemblers  it  de¬ 
veloped  in  the  process  of 
designing  and  manufac¬ 
turing  electronic  devices 
to  aid  the  blind  (its  real 
business).  The  MS  DOS 
cross-assemblers  for  the" 
8048  and  6502  were  writ¬ 
ten  in  C  and  support  a  sub¬ 
set  of  C  preprocessor  com¬ 
mands,  macros,  three 
object  file  formats,  and 
features  to  support  PROM 
programming.  They  sell 
for  $30  each  or  $75  for 
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both  with  source  code  and 
are  distributed  with  no  re¬ 
striction  on  noncommer¬ 
cial  copying. 

Speaking  of  copying,  we 
are  watching  with  interest 
SoftKIone’s  fortunes  with 
a  product  it  cheerfully  de¬ 
scribes  as  a  clone  of  Mi- 
crostuf's  Crosstalk  XVI 
data-comm  unications 
package.  SoftKIone’s  Mir¬ 
ror  was  designed  to  the 
precise  visual  specs  of 
Crosstalk,  and  SoftKlone 
presents  itself  as  introduc¬ 
ing  a  new  idea — mirror- 
image  software  at  a  lower 
price  than  the  mirrored 
product  and  perhaps  with 
added  capabilities.  Rather 
than  competing  by  pro¬ 
ducing  a  better  or  cheaper 
product,  the  notion  here  is 
to  produce  the  same  prod¬ 
uct  better  or  cheaper. 
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This  Issue 

Pascal,  Ada,  and  Modula-2  are  re¬ 
garded  as  languages  that  encour¬ 
age  structured  programming. 
This  issue  presents  for  each  lan¬ 
guage  some  code  that  we  hope 
you  will  find  educational,  useful, 
or  both.  We  found  Terry  Ritter's 
explication  of  CRCs  particularly 
enlightening. 
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to  see  the  benefits  of  background 
tasking  and  print  spooling,  while 
multiprocessor  architectures  are 
approaching  practicality.  But  ap¬ 
plication  concurrency  and  multi¬ 
processor  designs  will  only 
scratch  the  surface  of  parallel¬ 
ism  until  we  recast  algorithms  in 
parallel.  Is  some  new  Knuth 
even  now  writing  the  book  on 
parallel  algorithms? 
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It's  December-  23 
as  1  write  this, 
and  I'm  hurry¬ 
ing  to  get  this  note  to 
you  before  skipping 
out  for  the  holidays. 

When  you  read 
this,  we  expect  to  be 
in  the  middle  of  mov¬ 
ing  into  our  spacious 
new  offices  at  SOI 
Galveston  Dr.,  Red¬ 
wood  City,  CA  94063.  You  should 
send  any  correspondence  there. 

Our  editorial  calendar  (see  below) 
indicates  what  topics  we  intend  logo 
after  this  year.  But  the  calendar 
doesn't  tell  the  whole  story,  it  doesn't 
include,  for  example,  coverage  of 
networking  issues,  cryptography, 
and  memory-resident  standards,  all 
I  of  which  we  ll  be  looking  into  in 
i  1986,  nor  does  it  mention  other  topics 
|  that  you  will  surely  think  of.  Send  us 
|  your  ideas. 

Allen  Holub  wanted  to  pass  along 
:  this  suggestion:  DDJ  writers  and  coir 
'  umnists  are  often  more  than  happy 
I  to  respond  to  letters  from  readers. 

|  Your  chances  of  getting  a  response 
are  increased  if  you  include  a  self-ad¬ 
dressed,  stamped  envelope.  You  can 
also  reach  our  columnists  via  our 
Electronic  Edition. 

Frank  DeRose,  our  special  projects 
editor,  is  coordinating  the  editorial 
aspects  of  our  new  book  line  and  of 
the  Electronic  Edition  of  DU/ on  Com¬ 
puServe,  Frank  spells  out  in  this  issue 
what  vve  intend  to  do  with  our  on¬ 
line  publishing  experiment.  When 
you  read  this,  some  details  of  imple¬ 
mentation  will  probably  be  different 
from  what  he  says  here,  writing  as 
he  was  before  Christmas.  Print  has  its 
limitations,  which  is  why  we’re  ex¬ 
ploring  electronic  publishing,  bog  on 
to  find  out  what's  really  happening 
there. 

We’re  also  doing  the  groundwork 
for  an  ambitious  software  review 
program.  You  won't  see  the  results  of 
this  until  midyear,  but  last  August’s  C 
review  and  the  review  of  program¬ 


mable  editors  in  No¬ 
vember  indicate  the 
direction  we  ll  be 
taking:  comparative 
reviews  of  many 
products;  more  than 
one  programmer 
evaluating  the  prod¬ 
ucts;  using  the  most 
useful  and  objective 
sets  of  benchmarks 
we  can  coax  and  co¬ 
erce  veteran  programmers  into  de¬ 
veloping  for  us;  and  regular  updates 
and  bug  reports  on  the  reviews 
themselves.  We've  wisely  promoted 
Sara  Noah  Ruddy  (our  erstwhile  edi¬ 
torial  assistant)  to  assistant  editor 
with  responsibility  for  coordinating 
this  whole  review  process. 

The  other  member  of  the  editorial 
staff  whose  name  you  should  know 
is  Vince  Leone,  our  managing  editor, 
who  puts  the  pieces  together  every 
month.  Vince,  Sara,  Frank,  Allen,  and 
I  will  probably  be  joined  by  one 
other  editor  in  the  next  month  or 
two.  I'll  let  you  know. 

One  final  note:  we  owe  you  an  arti¬ 
cle.  In  January,  vve  promised  a  look 
at  a  program  that  ports  between  dia¬ 
lects  of  Pascal.  This  month  was 
packed,  and  we  didn't  have  room  for 
everything;  watch  for  it  in  March. 


1986  editorial  calendar 
March:  The  future  of  programming;  Arti¬ 
cle  deadline:  past. 

April:  Al.  Deadline:  past. 

May:  Designing  usable  software.  Dead¬ 
line:  past. 

June:  Communications.  Deadline:  3/1/86. 
July:  Forth.  Deadline:  4/1/86. 

August:  C.  Deadline:  5/1/86. 

September:  Algorithms.  Deadline:  6/1/86 
October:  80286/80386  programming. 
Deadline:  7/1/86 

November:  Graphics.  Deadline:  8  1  86 
December:  Operating  systems  Deadline: 


9/1/86 


yM  5~* 
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Columns 

Dear  DDJ, 

Allen  Holub’s  C  Chest  arti¬ 
cle  on  recursive  descent 
parsing  (September  1985) 
was  very  interesting  but 
contained  an  inaccurate 
grammar  that  gives  erro¬ 
neous  results  such  as: 

2*3  +  1  =  8 

(should  be  evaluated  as 
(2*3) +  1  =  7) 

6-5-4  =  5 
(should  be  evaluated  as 
(6  — 5)  — 4  =  -3) 

A  correct  grammar  for 
expressions  is  found,  in 
one  form  or  another,  in  ev¬ 
ery  book  on  compiling.  I 
will  show  how  the  rather 
unintuitive  final  form  is 
reached  by  proceeding  in 
small  steps. 

A  very  simple  grammar 
is  given  by  the  following 
rules: 

E  ::=  E  A  E  !  (E) !  —  E  !  n 
A  ::=  +1  —  1*1/ 

where  E  and  n  stand  for 
expression  and  number  re¬ 
spectively,  and  A  stands 
for  arithmetic  operator. 
This  grammar  is  ambigu¬ 
ous,  as  6  —  5  —  4  can  be 
parsed  in  two  valid  (but 
different)  ways: 

(6 -5) -(4) 

(6) -(5 -4) 

In  each  case,  the  parenthe¬ 
sised  symbols  form  an  ex¬ 
pression,  and  the  two  ex¬ 
pressions  are  linked  by  an 


arithmetic  operator.  We 
need  a  rule  to  introduce  as¬ 
sociativity,  i.e.,  to  ensure 
the  first  parse  of  6—5—4. 
Rule  (5)  in  Figure  6  of  the 
article  attempts  to  do  so 
but  introduces  the  wrong 
associativity: 

E  ::=  F-E 

forces  the  incorrect  parse 

6-5-4=6-15-4) 

Inverting  the  order  in  rules 
(2)  to  (5)  will  solve  the  asso¬ 
ciativity  problem.  This 
leaves  us  with  a  second 
problem.  We  want  both 
2*3  +  1  and  1  +  2*3  to  evalu¬ 
ate  as  7.  This  is  because  in 
mathematics  multiplica¬ 
tion  and  division  have  a 
higher  precedence  than 
addition  and  subtraction. 
To  achieve  this  we  intro¬ 
duce  two  new  nontermin¬ 
als,  term  and  factor. 
Roughly  speaking,  terms 
are  things  that  get  added 
(or  by  extension  subtract¬ 
ed)  together,  while  factors 
get  multiplied  (or  divided). 
The  resulting  grammar  is: 


E  ::=  E+TIE— TIT 
T  ::=  T*F  I T/F  I  F 
F  ::=  n  I  — n  I  (E)  I  —(E) 

This  grammar  is  correct.  It 
will  not  parse  2*3  +  1  as 
(2)*(3  +  l)  because  that 
would  be  an  expression 
multiplied  by  an  expres¬ 
sion,  not  one  of  the  valid 
ways  of  forming  an  ex¬ 
pression. 

Though  correct,  this 
form  is  not  suitable  for 
parsing  by  recursive  de¬ 
scent.  There  is  no  way  to 
"get  at”  the  first  piece  to 
start  the  recursion.  The 
grammar  given  by  Holub 
allowed  us  to  start  eyprf  J 
with  (to  evaluate  6  —  5—4): 

Ival  =  factor! ); 

Ival  —  =  expr( ); 

Our  grammar  would  seem 
to  require: 

Ival  =  eyprt  j; 

Ival  —  =  factor! ); 

So  eyprf  )  would  call  itself 
in  an  infinite  loop.  The 
grammar  must  therefore 
be  modified  as  follows: 


E  ::=  TE' 

E’  ::=  +TE’  I  —  TE’  I  NULL 
T  ::=  FT' 

T’  ::=  *FT’ I /FT' I  NULL 
F  ::=  nl  -n  1(E)  I  -(E) 

E'  and  T’  are  the  new  non¬ 
terminals  required  to 
make  the  basic  grammar 
parsable  by  recursive  de¬ 
scent.  They  allow  us  to 
split  off  a  piece  to  get 
started. 

Note  that  the  definition 
of  a  factor  is  unchanged,  so 
the  code  for  factorf  )  and 
constant  )  will  not  need  to 
be  modified. 

Mohamed  el  Lozy 

Health  Sciences  Com¬ 
puting  Facility 

665  Huntington  Ave. 

Boston,  MA  02115 

DISnDATa 

Dear  DDJ, 

In  your  November  1985  is¬ 
sue  on  page  89,  you  ran  an 
ad  for  a  disassembler  writ¬ 
ten  by  C.  W.  Medlock  of 
PRO/AM  SOFTWARE.  On  the 
basis  of  claims  made  in  the 
ad,  I  purchased  this  prod¬ 
uct  for  the  price  of  $145. 

To  my  sorrow,  when  I 
received  this  software  and 
tried  it,  I  found  that,  for  the 
vast  majority  of  programs, 
it  does  not  correctly  locate 
the  data  and  code  areas  as 
claimed  in  the  ad.  Instead, 
it  invariably  outputs  large 
segments  of  code  areas  as 
data.  What  is  worse  is  that 
there  are  no  switches  in  the 
program  to  override  the 
automatic  "algorithm" 
when  this  occurs,  nor  is 
there  any  provision  for  tell¬ 
ing  the  program  where  the 
data  and  code  areas  are  if, 
as  is  usually  the  case,  you 
happen  to  know  this  infor¬ 
mation.  The  only  recourse 
you  have,  as  described  in 
the  20-page  manual  sup¬ 
plied  with  the  program,  is 
to  do  a  series  of  binary 
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patches  to  the  executable 
file  for  each  area  of  code 
the  program  doesn't  find. 
Needless  to  say  this  is  a 
lengthy  and  time-consum¬ 
ing  process.  In  addition,  I 
found  that  for  some  input 
programs  the  disassembler 
hangs  the  computer  so  that 
a  reboot  is  necessary. 

Gerald  Coquin 

132  Rotary  Dr. 

Summit,  NJ  07901 

Of  Interest 

Dear  DDJ, 

In  reading  through  the  No¬ 
vember  1985  issue  of  Dr. 
Dobb 's  Journal,  I  ran  across 
a  notice  concerning  our  C- 
Link  product.  We  are 
pleased,  of  course,  to  be 
mentioned  in  your  publi¬ 
cation;  however,  the  infor¬ 
mation  in  Alex  Ragen's  Of 
Interest  column  is  out  of 
date. 

During  the  past  few 
months  since  the  last  news 
release  was  issued,  we 
have  changed  our  market 
strategy  in  response  to  the 
lack  of  Unix  and  C  experi¬ 
ence  among  users.  The 
main  focus  of  our  market¬ 
ing  effort  is  to  use  C-Link  as 
a  tool  to  provide  a  transla¬ 
tion  service.  We  will  con¬ 
tinue  to  offer  C-Link  as  a 
product  but  only  to  users 
willing  to  be  trained  in  its 
usage.  When  sold  in  this 
manner,  the  cost  is  $4,995 
plus  $195  for  additional 
run-time  licenses. 

Please  contact  me  direct¬ 
ly  if  you  would  like  more 
information  about  either 
the  C-Link  product  or 
service. 

James  R.  Getzinger 

Software  Manufactur¬ 
ers  Inc. 

20720  S.  Leapwood  Ave. 

Carson,  CA  90746 

Fgrep 

Dear  DDJ, 

I  wish  to  express  my  appre¬ 


ciation  for  the  excellent  ar¬ 
ticle  by  Ian  Ashdown  in  the 
September  1985  issue  cov¬ 
ering  FGREP.C.  This  article 
has  been  very  enlightening 
to  me  in  actually  applying 
the  algorithms  to  construct 
finite  state  automata  as  out¬ 
lined  in  the  Aho  and  Ull- 
man  book  Principles  of 
Compiler  Design  and  re¬ 
ferred  to  by  Mr.  Ashdown 
in  the  discussion  of  the 
FGREP.C  program. 

I  have  adapted  the  Unix 
C  program  for  the  BDS  com¬ 
piler  and  library  for  my 
Z80  machine  and  in  this 
process  have  encountered 
two  items  in  the  source 
program  that  I  wish  to 
comment  upon — they  may 
be  important  because  of 
their  possible  nonportable 
nature. 

First,  I  would  like  to  take 
exception  with  Mr.  Ash¬ 
down's  use  of  the  defini¬ 
tion  of  TRUE  as  (  —  1).  I  sug¬ 
gest  that  this  usage  is  not  in 
the  "spirit  of  C”  and  is  out 
of  context  with  the  clearly 
defined  usage  of  relational 
and  logical  operator  re¬ 
turns  in  C,  which  K  &  R 
guarantees  to  be  1  for  TRUE 
and  0  for  FALSE  when  mak¬ 
ing  explicit  comparisons. 
Mr.  Ashdown's  use  of  (  —  1) 
may  be  a  legacy  of  assem¬ 
bly-language  program¬ 
mers,  and  its  use  in  the  pro¬ 
gram  on  a  stand-alone  basis 
poses  no  problems,  but  it 
certainly  plays  havoc  if 
other  standard  headers  are 
used  and  TRUE  gets  rede¬ 
fined.  For  levity  and  con¬ 


dign  punishment,  I  suggest 
that  Mr.  Ashdown  compile 
and  run  the  program 
shown  in  Table  1,  below. 

Second,  I  had  a  problem 
with  the  stoupperi  )  rou¬ 
tine  in  that  the  resulting 
string  lost  its  first  letter  in 
being  put  to  uppercase.  It  is 
suggested  that  this  routine 
is  nonportable  and  compil¬ 
er-dependent.  The  prob¬ 
lem  stems  from  the  intu¬ 
itive  use  of  post-increment 
on  the  left  side  of  an  assign¬ 
ment  expression,  expect¬ 
ing  the  assignment  to  be 
made  before  the  post-in¬ 
crement.  The  strict  con¬ 
structionist  interpretation 
of  operator  precedence 
has  the  post-decrement  op¬ 
erator  higher  than  assign¬ 
ment  and  has  the  compiler 
reduce  the  left  side  of  the 
expression  below  before 
the  assignment  operation 
is  performed: 

*temp+  +  = 

toupper(*temp); 

This  results  in  a  loss  of  a 
character.  The  order  of 
evaluation  is  not  defined 
by  K  &  R  in  this  case,  and 
few  books  on  C  discuss 
these  sorts  of  statements 
wherein  the  order  of  eval¬ 
uation  is  not  defined. 
These  are  pernicious 
when  they  seem  so  intu¬ 
itive.  Other  cases,  such  as: 

arraylx]  =  +  +  x; 

which  is  not  defined  is,  I 
suggest,  easier  to  recognize 


#define  true  (—1) 

'define  false  0 

main( ) 

(M8 

iffTRUE  =  = !  false) 

puts(“\nAII’s  right  with  the  world.”); 

else 

puts(“\nThe  world  is  upside  down.”); 

} 


Table  1 


intuitively  and  less  likely 
to  be  applied  by  a  C  pro¬ 
grammer. 

It  may  be  of  use  for  DDJ 
to  list,  for  example,  these 
cases  of  evaluation-sensi¬ 
tive  expressions  that  are 
not  defined  in  K  &  R  and 
lead  to  nonportability. 

Justin  Farnsworth 

65  rue  Chauveau 

92200  Neuilly  France 

Unix 

Dear  DDJ, 

I  am  amazed  at  the  number 
of  products,  advertised  in 
your  magazine  and  else¬ 
where,  that  are  designed  to 
make  MS  DOS  look  more  like 
Unix.  So  far,  I've  seen  a  va¬ 
riety  of  text  editors  made 
famous  under  Unix,  a 
plethora  of  C  compilers,  a 
word  processing  package 
that  bears  strange  similar¬ 
ities  to  nroff,  and  an  imple¬ 
mentation  of  make.  There 
is  reportedly  a  package  that 
implements  the  Bourne 
shell  and  comes  with  a  va¬ 
riety  of  utility  programs, 
such  as  diff  and  grep.  You 
can  even  buy  a  LALR(l) 
parser  generator  (a  freebie 
under  Unix  called  yacc).  All 
of  this  is  in  addition  to  the 
many  features  of  MS  DOS  it¬ 
self  that  were,  uh,  bor¬ 
rowed  directly  from  Unix 
without  so  much  as  one 
word  of 

acknowledgement. 

One  could  spend  several 
thousands  of  dollars  equip¬ 
ping  an  MS  DOS  machine 
with  all  these  programs, 
and  the  result  would  still 
not  approach  the  power  of 
Unix.  A  purchase  of  Xenix 
seems  to  me  to  be  the  best 
buy  in  the  software  mar¬ 
ket.  It  is  the  most  useful 
piece  of  bundled  software 
I’ve  seen. 

David  F.  Ziffer 

Software  Development 
Systems 

3110  Woodcreek  Dr. 

Downers  Grove,  IL  60515 

DDJ 
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VIEWPOINT 


Sixth  Generation 
Minds 


Our  man  from  muppetland 
returns  with  an  entourage 
including  strange  attractors 
and  motorboats  on  mercu¬ 
ry  pools. — ed. 

How  might  we  simulate 
actual  human  cognition 
via  new  kinds  of 
hardware? 

A  clue  comes  from  the 
work  of  Erich  Goldmeier, 
whose  essentially  gestalt 
investigations  in  visual  per¬ 
ception  were  a  response  to 
"the  frustrating  effort  to 
teach  pattern  recognition" 
to  computers.  He  found 
that  the  distinctions  hu¬ 
mans  make  between  fig¬ 
ure  and  ground,  matter 
and  form,  norms  and  dis¬ 
tortion,  etc.,  cannot  be  the 
result  of  examining  the 
features  of  the  figures  or 
any  formal  aspects  of  the 
figures.  Instead,  Goldmeier 
believes,  there  are  proto¬ 
typical  or  archetypal  fig¬ 
ures  existing  somehow  at 
the  neurological  level, 
such  as  "regions  of  reso¬ 
nance”  in  the  brain. 

All  this  fits  with  Michael 
Doherty's  latest  DDJ  article 
citing  the  works  of  Rosch, 
Nelson,  and  Palermo, 
which  suggests  that  con¬ 
cepts  cannot  be  broken 
down  into  a  list  of  features 
via  reductionistic  tech¬ 
niques  and  then  recom¬ 
bined.  In  this  view,  objects 


by  Richard  Grigonis 


Richard  Grigonis  is  em¬ 
ployed  by  Children's  Tele¬ 
vision  Workshop.  He  is  best 
known  to  DDJ  readers  for 
his  articles  on  fifth  and 
siyth  generation  computing 
and  the  Grigonis-Doherty 
debate  these  articles 
precipitated. 


are  categorized  not  by  tab¬ 
ulating  features  but  in 
terms  of  measured  dis¬ 
tance  from  some  mental 
ideal  or  type.  Doherty  also 
mentions  the  linguistic  cu¬ 
riosities  known  as  "squish¬ 
es.”  The  facts  that  the  ger¬ 
und  "his  going"  can  be 
used  in  the  same  positions 
as  a  normal  noun  phrase 
and  that  it  can  be  placed 
along  a*  continuum  of 
"nouniness”  implies  that 
one  can’t  assign  linguistic 
terms  to  discrete  categories 
and  state  hard  rules  based 
on  membership  in  the 
categories. 

But  how  does  all  this  re¬ 
late  to  building  a  computer 
whose  workings  parallel 
those  of  the  brain? 

Until  recently,  it  was 
thought  that  the  firings  of 
neurons  in  the  brain  could 
be  likened  to  the  activity  of 
flip-flops  in  a  computer. 
Now  it  appears  that  large 
groups  of  neurons  work  in 
unison,  interacting  via 
complex  electromagnetic 
fields — which  could  ex¬ 
plain  the  "regions  of  reso¬ 
nance" 'required  by  Gold- 
meier's  view  and  also  such 
phenomena  as  associative 
memory  and  the  ability  of 
the  brain  to  recognize  in¬ 
ternally  complex  stimuli 
(such  as  a  friend’s  face)  al¬ 
most  instantly. 

In  one  model,  which  is 
based  on  the  work  of  such 
researchers  as  E.  Roy 
Johns  of  the  New  York  Uni¬ 
versity  Medical  Center  and 
W.  Ross  Adey  of  the  Loma 
Linda  Veterans  Adminis¬ 
tration  Hospital,  neurons 
behave  as  complex  nonlin¬ 
ear  oscillators.  This  places 
the  problem  of  under¬ 
standing  the  collective  be¬ 
havior  of  neurons  in  the 
realm  of  chaos  theory, 
which  describes  mathe¬ 
matically  systems  that  shift 
from  periodic  to  nearly 


chaotic  behavior — such  as 
the  way  a  stream  of  air  be¬ 
comes  turbulent  near  an 
airfoil — that  are  best  de¬ 
scribed  via  the  mathemati¬ 
cal  entities  known  as 
"strange  attractors." 

Unlike  what  happens  in 
more  tractable  systems, 
when  one  changes  input  to 
a  strange  attractor  slightly 
one  ends  up  with  a  wildly 
different  output.  Erol  Ba- 
sar  of  the  University  of 
Physiology  in  Lubeck, 
West  Germany,  plotted  the 
amplitudes  of  two  brain 
frequencies  and  found 
their  relationship  to  be 
that  of  a  strange  attractor. 
Maybe  free  will  is  a 
strange  attractor? 

In  any  case,  building  a 
"field-effect"  computer 
based  on  nonlinear  oscilla¬ 
tors  ought  to  be  a  techno¬ 
logical  nightmare.  Eric  J. 
Lerner  says  that  it  could  be 
done  in  one  of  four  ways: 
(1)  microwave  circuits  built 
from  conventional  compo¬ 
nents;  (2)  Josephson  junc¬ 
tions,  which  are  natural 
nonlinear  oscillators  in  the 
microwave  region;  (3)  us¬ 
ing  ,an  optical  processor, 
increasing  the  electromag¬ 
netic  frequencies  of  indi¬ 
vidual  transmitting  units; 
(4)  using  some  kind  of  mo¬ 
lecular  processor  such  as 
those  projected  for  future 
"biochips.  ” 

One  could  think  up  some 
additional,  perhaps  less 
plausible,  versions  of  such 
a  computer:  a  swimming 
pool  filled  with  liquid  mer¬ 
cury  the  surface  of  which 
is  disturbed  by  thousands 
of  toy  motorboats  with 
broken  propellers  and 
faulty  engines  (the  "non¬ 
linear  accelerators");  or  a 
soundproofed  room  filled 
with  thousands  of  micro¬ 
computers  fitted  with 
speech  recognition/pro¬ 
duction  devices  squawking 


at  each  other  at  various 
frequencies. 

But  is  it  worthwhile? 

The  successes  of  limited 
expert  systems  demon¬ 
strate  special  deficiencies 
in  human  cognition.  As  Do¬ 
herty  wrote,  “The  strange 
fact  about  AI  has  always 
been  that  it’s  easier  to  sim¬ 
ulate  an  expert  than  to  sim¬ 
ulate  the  common  sense  of 
a  five-year-old.”  The  tre¬ 
mendous  contextual 
knowledge  that  children 
possess  is  wired  into  the 
brain  along  with  the  in¬ 
nate  capacity  to  under¬ 
stand  the  grammars  and 
semantics  of  natural  lan¬ 
guage.  These  abilities  have 
been  genetically  handed 
down  to  us  by  our  ances¬ 
tors,  useful  evolutionary 
"inventions”  by  the  ubiq¬ 
uitous  DNA  molecule  to 
keep  itself  from  extinction. 
Thus,  the  amount  of  learn¬ 
ing  required  in  these  cog¬ 
nitive  areas  is  minimal,  as 
they  are  processes  ac¬ 
quired  over  time  in  a  way 
that  is  "transparent  to  the 
user.” 

But  we  should  not  feel 
too  complacent.  The  other 
side  of  the  coin — learning 
new  forms  of  knowledge 
and  mastering  them  as  an 
expert — is  a  domain  easily 
dominated  by  computers. 
If  you  or  I  were  to  memo¬ 
rize  a  few  hundred  rules 
and  apply  them  logically, 
we  could  get  straight  As  on 
MIT  calculus  finals,  but  we 
are  unlikely  just  now  to 
run  off  to  examine  Slagle's 
hundred  rules.  The  future 
of  the  art  and  science  of  ex¬ 
pertise  belongs  to  ma¬ 
chines,  not  to  human 
beings. 
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DDJ  ON  LINE 


DDJ  Goes 
On  Line 

On  January  1,  the  Electron¬ 
ic  Edition  of  Dr.  Dobb's 
Journal  appeared  on  Com¬ 
puServe.  Through  the  Elec¬ 
tronic  Edition  DDJ  will  of¬ 
fer  the  following: 

•  We  will  make  available  in 
our  data  libraries  most  of 
the  listings  that  appear  in 
the  articles  and  columns  of 
Dr.  Dobb's  Journal  every 
month.  The  data  libraries 
will  also  contain  selections 
from  some  of  our  more 
popular  back  issues  and  oc¬ 
casionally  articles  and  list¬ 
ings  that  have  not  ap¬ 
peared  in  the  magazine. 

•  Some  of  our  more  signifi¬ 
cant  programs  will  be 
available  through  Softex  in 


the  near  future.  Softex  is 
CompuServe's  electronic 
software  exchange,  a 
menu-driven  program  that 
allows  users  to  purchase 
and  download  software 
though  the  network. 

•  We  will  maintain  a  dis¬ 
play  area  where  Compu¬ 
Serve  users  can  read  ab¬ 
stracts  of  the  material  in 
the  current  issue.  The  dis¬ 
play  area  will  also  contain 
general  magazine  informa¬ 
tion,  such  as  our  editorial 
calendar,  writers’  guide¬ 
lines,  and  information  for 
advertisers. 

•  We  will  compile  lists  of 
the  commercial  software 
development  tools  avail¬ 
able  to  microcomputer 
programmers.  We  will  also 
compile  selected  bibliogra¬ 
phies  and  give  capsule  re¬ 


views  of  newly  released 
books. 

•  We  will  provide  a  messag¬ 
ing  facility  with  columnists 
and  other  SIG  members. 

•  We  will  stage  regular  on¬ 
line  teleconferences  with 
authors,  columnists,  and 
other  distinguished  guests. 

•  We  will  take  subscrip¬ 
tions  for  Dr.  Dobb's  Jour¬ 
nal,  the  magazine.  We  will 
also  provide  a  way  for 
readers  to  register  circula¬ 
tion  complaints. 

•  We  will  provide  com¬ 
plete  information  about 
other  DDJ  publications, 
such  as  back  issues,  bound 
volumes,  indexes,  Dr. 
Dobb's  Books,  and  Dr. 
Dobb's  Software.  We  will 
also  take  orders  for  these 
items. 

Please  watch  this  de¬ 


partment  for  further  an¬ 
nouncements  about  con¬ 
ference  schedules  or  the 
availability  of  listings  from 
back  issues.  Also,  if  you 
have  a  request  for  a  listing 
from  a  back  issue,  drop  us 
a  note  or  just  leave  a  mes¬ 
sage  in  the  DDJ  Electronic 
Edition  on  CompuServe. 

Some  of  these  services 
may  not  yet  be  available. 
Most  will  be  free,  but  some 
will  involve  a  small 
charge. 

You  access  the  DDJ  Elec¬ 
tronic  Edition  by  typing  go 
DDJ  at  any  CompuServe 
system  prompt.  We  hope 
you  will  drop  by  and  have 
a  look.  See  you  soon! 


DIM 
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COLUMNS 


C  CHEST 

A  New  Shell  for  MS  DOS  (continued) 


This  month's  column  continues 
with  the  MS  DOS  shell.  Last 
month  I  described  how  to  use  the 
shell  and  printed  Listing  One,  the 
shell  itself.  This  month,  because  the 
various  subroutines  that  make  up  the 
shell  are  commented  well  enough  so 
that  additional  comments  here  are 
unnecessary,  I’ll  discuss  only  the 
shell’s  organization  at  a  reasonably 
high  level  and  those  subroutines 
whose  function  is  not  immediately 
evident.  Refer  to  the  listings  for  more 
details.  This  month’s  listings  (Listings 
Two,  Three,  Four,  and  Five,  pages 
66  —  74)  are  the  history,  shell  vari¬ 
ables,  alias  support,  and  a  couple  mi¬ 
nor  support  routines.  Next  month  I’ll 
finish  up  the  shell  with  another  col¬ 
lection  of  miscellany. 

A  bug  was  found  in  last  month’s 
listing  after  the  issue  went  to  press. 
As  printed,  the  shell  would  try  to  ex¬ 
pand  *  or  ?  even  if  these  characters 
were  in  a  quoted  string.  To  fix  this 
problem,  replace  the  subroutine 

has_wild( ) 

(line  348)  with  the  code  shown  in  Ta¬ 
ble  1,  page  18. 

This  morning  I  dumped  all  the  var¬ 
ious  shell  listings  out  on  my  printer 
for  the  first  time.  I  admit  I’m  sur¬ 
prised  by  the  number  of  pages  now 
piled  on  my  desk  (for  all  that,  sh.exe 
is  only  28,906  bytes  compared  with 
23,210  bytes  for  command.com). 
Anyway,  for  both  my  own  sanity 
and  to  make  everyone's  life  a  little 
easier,  I’ve  compiled  a  cross-refer¬ 
ence  of  all  the  shell-related  subrou¬ 
tines  (Table  2,  page  18).  The  table 
shows  the  subroutine  name,  the  list¬ 
ing  number  (and  month  of  publica¬ 
tion),  and  the  line  number  on  which 


by  Allen  Holub 


the  subroutine  starts.  Next  month’s 
listings  are  included  in  the  table  as 
are  subroutine-like  macros. 


Compiling  the  Shell 

The  shell  was  compiled  using  the 
most  recent  version  (3.0)  of  the  Micro¬ 
soft  C  compiler.  (I  am  not  as  im¬ 
pressed  with  the  compiler  as  many 
other  reviewers  seem  to  be;  there  will 
be  an  extensive  review  of  the  compil¬ 
er  in  this  column  next  month.)  I've 
tried  to  restrict  myself  to  those  library 
subroutines  that  are  readily  portable 
to  other  compilers.  Most  of  the  sys¬ 
tem-level  routines  ( chdirf  ),  getcwdf  ), 
and  so  on)  are  simple  BDOS  calls  any¬ 
way  so  it  shouldn't  be  too  hard  to 
write  them  if  you  don’t  have  them  al¬ 
ready.  All  the  library  routines  used 
are  listed  in  a  block  of  externs  on  lines 
110—123  of  Listing  One. 

Three  routines  may  cause  trouble  if 
you’re  not  using  the  Microsoft  com¬ 
piler.  These  are  signaK  J,  which  lets 
you  handle  a  "C,  and  the  environ¬ 
ment  manipulation  routines  getenvf ) 
and  putenvf ).  If  you  need  a  signalt  ), 
I’d  suggest  using  Ray  Duncan's 
break.asm  (DDJ,  September  1985,  pp. 
119  —  121),  which  is  functionally  very 
similar  to  signaK  ).  ( Break.asm  sets  a 
global  flag  rather  than  calling  a  sub¬ 
routine  when  ~C  is  encountered.) 

Getenvf J,  used  to  examine  an  envi¬ 
ronment  string,  is  relatively  straight¬ 
forward  to  write.  A  pointer  to  the  en¬ 
vironment  string  is  part  of  a 
program's  PSP.  [For  more  informa¬ 
tion  about  the  PSP,  see  The  Peter  Nor¬ 
ton  Programmer's  Guide  to  the  IBM  PC 
(Microsoft  Press,  1985)  p.  260f.]  In  any 
event,  Lattice,  Microsoft,  and  Aztec 
all  have  a  getenvf )  in  their  libraries. 
Unfortunately  of  the  three,  only  Mi¬ 
crosoft  has  a  putenvf  J,  and  adding  an 
environment  string  is  a  harder  prob¬ 


lem,  mostly  because  a  child  process 
must  inherit  the  shell’s  environment. 
The  various  fork/spawn  functions 
have  to  be  rewritten  to  pass  the  new 
environment  to  the  child.  If  anyone 
has  done  any  of  this,  please  send  me 
your  routines,  and  I’ll  print  them. 
Lacking  that,  I'll  try  to  write  them 
myself  within  the  next  few  months. 

The  shell  modifies  only  two  envi¬ 
ronment  strings.  CMDLINE  holds  the 
full  2,048-byte  command  line,  and 
SHLEV  holds  the  current  shell  nesting 
level.  If  you  can  live  without  these, 
then  you  don’t  need  a  putenvf ).  An 
alternative  approach  is  to  use  the  In- 
tra-Application  Communications 
Area  supported  by  DOS.  The  ICA  is  a 
16-byte  block  at  addresses  0000:4f0  to 
0000:4ff,  reserved  by  DOS  so  that  pro¬ 
grams  can  communicate  with  each 
other  (that  is,  DOS  promises  not  to 
trash  it  for  you).  The  current  shell 
level  and  a  long  pointer  to  the  com¬ 
mand  line  buffer  could  be  put  into 
the  ICA  and  then  accessed  by  a  child 
process  instead  of  using  environ¬ 
ment  variables.  You  should  probably 
put  a  checksum  in  the  ICA  as  well,  to 
make  sure  that  another  program 
hasn’t  modified  it. 

I've  used  the  void  type  in  the  shell 
so  that  a  warning  will  be  printed  if 
you  use  the  return  value  of  a  subrou¬ 
tine  that  doesn’t  return  a  value, 
though  I  haven't  used  any  pointers  to 
void.  I’d  suggest  putting  a 

typedef  int  void; 

into  your  stdio.h  file  rather  than  dis¬ 
pensing  with  the  void  declarations — 
your  program  will  be  more  portable 
that  way.  Microsoft  also  supports 
strong  type  checking,  so  I’ve  been  us¬ 
ing  it  too.  Strong  type  checking  is 
turned  on  by  including  a  type  list  as 
part  of  an  extern  statement.  For 
example: 

extern  int  fopen(  char  *,  char  *  ); 
will  do  all  the  usual  things,  and  a 
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int  has_wild(  bp ) 
register  char  *bp; 


warning  will  be  printed  if  the  return  { 

value  from  fopen  isn’t  put  into  an  int. 

In  addition,  warnings  will  be  printed 
if  fopen  is  called  with  anything  other 
than  two,  character-pointer  argu¬ 
ments.  A  subroutine  with  a  variable 
number  of  arguments  can  be 
declared: 

extern  void  printfl  char  * , ) 


/*  Return  true  if  the  string  has  a  *  or  ?  in  it 

*  Does  not  recognize  a  *  or  ?  in  a  quoted  string. 

7 

register  int  inquote  =  0; 

for( ;  *bp  ;  ++bp) 

{ 

if(*bp - '\  V  &&*(bp+1)) 

+  +  bp  ; 


Here,  printfl )  must  have  one  charac¬ 
ter-pointer  argument,  but  this  one 
can  be  followed  by  zero  or  more  ad¬ 
ditional  arguments  of  indeterminate 
type.  Printfl  js  return  value  (which  is 
garbage  anyway)  can’t  be  used  for 
anything  because  of  the  void.  If 
you’re  not  using  a  compiler  that  sup¬ 
ports  strong  type  checking,  don't  en¬ 
ter  the  type  list  when  you  type  in  the 
code.  All  the  extern  statements  are 
grouped  near  the  top  of  every  mod¬ 
ule  so  that  you  can  find  them  easily. 

Another  potential  portability  prob¬ 
lem  is  the  enumerated  type  (TOKEN) 
used  on  lines  193—208  of  Listing  One. 
You  can  replace  the  TOKEN  declara¬ 
tion  with 


typedef  int  TOKEN; 


^define 

^define 

^define 

^define 

^define 


ALIAS 

CD 

CMD 

EXIT 

HISTORY 


0 

(ALIAS  +1) 
(CD  +1) 
(CMD  +1) 
(EXIT  +1) 


One  final  portability  issue:  I’ve 
used  both  bit  fields  and  explicit  initia¬ 
lizers  all  over  the  place.  To  my  mind, 
these  are  both  part  of  the  C  language, 
and  I  wouldn't  consider  dispensing 
with  them  any  more  than  I’d  consid¬ 
er  not  using  +  +  or  pointers.  Just  be¬ 
cause  a  few  turkey  compilers  (such 
as  BDS)  can’t  compile  a  program  writ¬ 
ten  in  C,  I’m  not  going  to  deliberately 
cripple  my  own  programs  by  not  us¬ 
ing  perfectly  legitimate  constructs. 
This  is  an  MS  DOS  shell  anyway  and 
most  MS  DOS  compilers  support  bit 
fields  and  initializers  (if  yours 
doesn’t,  you  should  consider  getting 
another  compiler).  Those  that  don’t 
support  bit  fields  will  just  ignore  the 


else  if(  iSQUOTE(*bp) ) 
inquote  =  inquote; 


else if(  iinquote  && (*bp  =  =  ’*’! I *bp  =  =  ’?’) ) 
return  1 ; 


return  0; 

} 


Table  1 


name 

listing  # 

month 

module 

line  number 

typedef  TOKEN 

listing  1 

(jan) 

sh.c 

193 

typedef  VAR 

listing  3 

(feb) 

var.c 

29 

add_entry 

listing  7 

(mar) 

dir.c 

247 

add— hist 

listing  2 

(feb) 

hist.c 

72 

alias 

listing  1 

(jan) 

sh.c 

1237 

cd 

listing  1 

(jan) 

sh.c 

1313 

clab 

listing  7 

(mar) 

dir.c 

349 

cmds 

listing  1 

(jan) 

sh.c 

1417 

cmp 

listing  7 

(mar) 

dir.c 

359 

command_inpu  . . . 

listing  1 

(jan) 

sh.c 

285 

copy_ path 

listing  7 

(mar) 

dir.c 

327 

cptolower 

listing  2 

(dec) 

cptolow.c 

1 

cpy 

listing  3 

(dec) 

cpy.c 

1 

cursize 

listing  4 

(dec) 

vidbios.c 

49 

del _ dir 

listing  7 

(mar) 

dir.c 

412 

DIAG 

listing  1 

(jan) 

sh.c 

156 

digit 

listing  1 

(jan) 

sh.c 

251 

dir 

listing  7 

(mar) 

dir.c 

431 

dirtoa 

listing  7 

(mar) 

dir.c 

200 

disk— present 

listing  1 

(jan) 

sh.c 

1266 

doargs 

listing  1 

(jan) 

sh.c 

1100 

docmd 

listing  1 

(jan) 

sh.c 

883 

doenv 

listing  1 

(jan) 

sh.c 

1359 

efgets 

listing  5 

(dec) 

efgets.c 

393 

eget_hist 

listing  2 

(feb) 

hist.c 

169 

egets 

listing  5 

(dec) 

efgets.c 

138 

ENDTRACE 

listing  1 

(jan) 

sh.c 

151 

errmsgs 

listing  1 

(jan) 

sh.c 

1029 

execute 

listing  1 

(jan) 

sh.c 

631 

exp_ dir 

listing  1 

(jan) 

sh.c 

479 

exp_vars 

listing  1 

(jan) 

sh.c 

706 

file _ input 

listing  1 

(jan) 

sh.c 

305 

find_first 

listing  7 

(mar) 

dir.c 

45 

find_next 

listing  7 

(mar) 

dir.c 

67 

findvar 

listing  3 

(feb) 

var.c 

43 

fixup— name 

listing  7 

(mar) 

dir.c 

137 

( Continued  on  page  20) 
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:  <num>  part  of  the  declarations,  so 
your  structures  will  be  a  little  larger, 
but  the  program  will  still  compile 
without  modification. 

The  subroutines  are  organized 
functionally  rather  than  alphabeti¬ 
cally.  You  can  use  the  cross-refer¬ 
ence  if  you  need  to  find  something. 
The  biggest  potential  organizational 
problem  is  sh.c  (Listing  One),  which 
is  too  big  for  me  to  be  totally  comfort¬ 
able  with  it.  Break  it  up  if  you  need 
to.  The  routines  on  lines  1137—1379 
(the  various  system-level  command 
support  routines:  setenv,  set,  and  so 
on)  could  be  made  into  another  inde¬ 
pendent  module  without  too  much 
trouble,  but  that  only  gets  rid  of  a 
few  hundred  lines. 

Shell  Organization 

The  shell  itself  (Listing  One)  is  orga¬ 
nized  functionally  into  several  parts: 

Typedefs,  * defines ,  and  so  on  (lines 
110-2226) 

Input  routines  (lines  227—346) 
Command  processing  (lines 
347-1026) 

Start-up  routines  (lines  1029  —  1136) 
Internally  implemented  com¬ 
mands  (lines  1138  —  1378) 

The  command  processor  itself  (in¬ 
cluding  main,  lines  1382—1545) 

Of  these,  the  organization  of  the  input 
routines  needs  some  comment.  I 
eventually  intend  to  augment  Sh  with 
several  of  the  loop  control  functions 
supported  in  the  Unix  C  shell.  The 
easiest  way  to  do  this  is  to  treat  the 
shell  as  a  small  compiler  (or  interpret¬ 
er).  That  is,  it's  nice  to  have  a  token 
recognizer  parse  keywords  from  the 
input  and  then  tell  the  command  in¬ 
terpreter  what  to  do  rather  than  have 
the  command  interpreter  itself  figur¬ 
ing  out  what's  on  the  input  line.  So, 
the  command  interpreter  ( cmds( )  on 
line  1417)  calls  ne?ct—cmd( )  to  get  a 
command  from  input.  Cmdst )  then 
strips  the  first  word  from  the  input 
line  and  calls  tokenize( )  to  analyze 
this  word.  Tokenize(  )  returns  a 
unique  integral  value  that  can  be  used 
to  vector  into  a  switch. 

Input  can  come  from  one  of  three 
places,  depending  on  the  command 
line  with  which  the  shell  was  in- 


gcur 

listing  4 

(dec) 

vidbios.c 

82 

get_hist 

listing  2 

(feb) 

hist.c 

97 

get_hnum 

listing  2 

(feb) 

hist.c 

188 

getcur 

listing  4 

(dec) 

vidbios.c 

105 

getkey 

listing  5 

(dec) 

efgets.c 

69 

getl 

listing  5 

(dec) 

efgets.c 

372 

getpage 

listing  4 

(dec) 

vidbios.c 

36 

getvar 

listing  3 

(feb) 

var.c 

194 

has_only 

listing  7 

(mar) 

dir.c 

113 

has_wild 

listing  1 

(jan) 

sh.c 

348 

haswild 

listing  7 

(mar) 

dir.c 

84 

hist_name 

listing  2 

(feb) 

hist.c 

214 

history 

listing  2 

(feb) 

hist.c 

269 

interactive _ _ 

listing  1 

(jan) 

sh.c 

269 

isalias 

listing  3 

(feb) 

var.c 

25 

isname 

listing  3 

(feb) 

var.c 

24 

isrootdir 

listing  7 

(mar) 

dir.c 

97 

ISVAR 

listing  1 

(jan) 

sh.c 

179 

iswhite 

listing  1 

(dec) 

next.c 

5 

ISWHITE 

listing  1 

Gan) 

sh.c 

177 

main 

listing  1 

(jan) 

sh.c 

1489 

mk_dir 

listing  7 

(mar) 

dir.c 

385 

next 

listing  1 

(dec) 

next.c 

8 

next_cmd 

listing  1 

Gan) 

sh.c 

965 

nextarg 

listing  1 

Gan) 

sh.c 

441 

nextarg 

listing  8 

(mar) 

reargv. c 

12 

PMODE 

listing  1 

Gan) 

sh.c 

186 

print _ hist 

listing  2 

(feb) 

hist.c 

195 

printalias 

listing  3 

(feb) 

var.c 

173 

printvars 

listing  3 

(feb) 

var.c 

183 

prompt 

listing  1 

Gan) 

sh.c 

858 

PSTR 

listing  1 

Gan) 

sh.c 

160 

ptail 

listing  5 

(dec) 

efgets.c 

112 

pwd 

listing  1 

Gan) 

sh.c 

1251 

rcopy 

listing  1 

Gan) 

sh.c 

915 

reargv 

listing  8 

(mar) 

reargv.c 

46 

reset _ fileinput 

listing  1 

Gan) 

sh.c 

238 

restore_hist 

listing  2 

(feb) 

hist.c 

253 

save_hist 

listing  2 

(feb) 

hist.c 

231 

scur 

listing  4 

(dec) 

vidbios.c 

68 

search 

listing  1 

Gan) 

sh.c 

573 

set 

listing  1 

Gan) 

sh.c 

1172 

setargs 

listing  1 

Gan) 

sh.c 

1063 

setcur 

listing  4 

(dec) 

vidbios.c 

100 

setenv 

listing  1 

Gan) 

sh.c 

1138 

setvar 

listing  3 

(feb) 

var.c 

137 

shift 

listing  1 

Gan) 

sh.c 

1344 

skipto 

listing  6 

(mar) 

skipto.c 

1 

SKIPWHITE 

listing  1 

Gan) 

sh.c 

178 

ssort 

listing  9 

(mar) 

ssort.c 

9 

strip 

listing  1 

Gan) 

sh.c 

363 

strsave 

listing  5 

(feb) 

strsave.c 

6 

tokenize 

listing  1 

Gan) 

sh.c 

1393 

TRACE 

listing  1 

Gan) 

sh.c 

150 

unalias 

listing  1 

Gan) 

sh.c 

1227 

unargv 

listing  4 

(feb) 

unargv.c 

7 

unsetvar 

listing  3 

(feb) 

var.c 

62 

usage 

listing  1 

Gan) 

sh.c 

1047 

use_exit 

listing  1 

Gan) 

sh.c 

1382 

varcpy 

listing  3 

(feb) 

var.c 

101 

wchar 

listing  4 

(dec) 

vidbios.c 

112 

wstr 

listing  4 

(dec) 

vidbios.c 

125 

Table  2  (cont.):  Cross-reference  for  all  shell-related  subroutines  and  sub¬ 
routine-like  macros 
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voked:  the  command  line  itself,  a  file, 
or  interactively  from  standard  input.  | 
All  three  of  these  sources  have  their 
own  problems,  and  I  didn't  want 
neyt—cmd! )  to  have  to  worry  about 
these  problems.  Thus,  the  shell  uses 
multiple  input  routines. 

When  argv  is  parsed  (by  doargs! ), 
line  1100),  a  global  pointer  to  a  sub¬ 
routine  (Ifunct,  line  234)  is  initialized 
to  point  at  an  appropriate  input  rou¬ 
tine.  Text  is  then  input  indirectly 
through  this  pointer.  Ifunct  will 
point  at  one  of  the  routines  interacti¬ 
ve-input!  ),  command-input (  ),  or  fi¬ 
le-input!  ).  All  three  routines  act  in 
the  same  way — they  get  a  line  of  in¬ 
put  from  somewhere  and  put  that 
line  into  the  global  array  Ibuf  (de¬ 
clared  on  line  216).  A  pointer  to  Ibuf  is 
returned  on  success,  and  0  is  re¬ 
turned  on  EOF.  The  string  input  rou¬ 
tine  command— input!  ),  returns  EOF 
when  it  reaches  the  end  of  a  string  to 
maintain  compatibility  with  the 
other  routines. 

Of  the  three  input  routines,  the 
weirdest  is  file— input! )  (used  to  pro¬ 
cess  batch  files).  The  problem  here  is 
caused  by  collusion  between  MS  DOS 
and  the  compiler’s  I/O  library.  When 
a  program  spawns  a  child  process, 
the  child  inherits  the  parent’s  file  de¬ 
scriptors.  This  is  documented  in  sev¬ 
eral  places,  both  in  the  MS  DOS  and 
the  Microsoft  C  Compiler  documen¬ 
tation.  None  of  these  sources,  howev¬ 
er,  deign  to  mention  that  when  the 
child  process  terminates,  e}dt(  )  will 
close  all  open  files,  including  those 
files  that  belong  to  the  parent  pro¬ 
cess.  In  other  words,  spawning  a 
child  process  under  MS  DOS  closes  all 
open  files  in  the  parent  process  as  an 
undesirable  side  effect.  This  problem 
is  circumvented  in  fde— input!  ), 
which  reads  a  line  from  a  file,  re¬ 
members  the  current  position  in  the 
file  with  an  fseek!  )  call,  and  then 
closes  the  file.  The  next  time  file— in¬ 
put!  )  is  called,  it  reopens  the  file, 
seeks  to  the  previous  position  in  the 
file,  and  then  reads  another  line.  I 
know  this  is  a  kludge,  but  I  couldn’t 
think  of  any  easy  way  around  the 
problem  short  of  reading  the  entire 
batch  file  into  a  local  buffer  and  then 
processing  that  buffer.  The  repeated 
seeks  seemed  a  better  solution,  but 


it’s  not  a  good  one. 

Another  somewhat  convoluted 
piece  of  code  is  the  routine  that  does 
alias  expansion.  The  expansion  of  a 
single  alias  is  straightforward.  The 
same  routines  (and  tables)  are  used  to 
hold  and  expand  both  aliases  and 
shell  variables.  An  alias  has  the  high 
bit  of  the  first  character  of  the  name 
set  when  it  is  stored  and  a  shell  vari¬ 
able  does  not  so  that  the  alias  expan¬ 
sion  routines  can  differentiate  be¬ 
tween  them.  That  is,  aliases  and  shell 
variables  do  not  share  the  same 
name  pool,  even  though  they're 
stored  in  the  same  table.  All  the  sim¬ 
ple  alias  maintenance  routines  are  in 
Listing  Three. 

The  shell,  on  the  other  hand,  uses 
the  simple  alias  expansion  routines 
in  complex  ways.  The  problem  here 
is  compound  commands — single 
aliases  consisting  of  several,  semico¬ 
lon-delimited  commands  concatenat¬ 
ed  together.  These  additional  com¬ 
mands  could  also  be  aliases. 

The  initial  command  is  read  in  by 
ne\t-jcmd( )  on  line  991.  Blank  lines 
and  comment  lines  (those  with  a  *  in 
the  far  left  column)  are  skipped  at 
this  level.  Then  history  is  applied. 
(Note  that  applying  history  here 
means  that  the  /  that  signifies  a  his¬ 
tory  expansion  has  to  be  the  charac¬ 
ter  at  the  left  end  of  the  line  not  the 
first  character  of  the  command, 
which  could  be  anywhere  on  the 
line  following  a  semicolon.)  Now 
aliases  are  expanded  by  calling  the 
recursive  routine  rcopy! )  (on  line 
915).  Each  recursive  iteration  ex¬ 
pands  one  alias.  Looking  at  the  code 
as  I  write  this,  the  method  used 
seems  needlessly  convoluted.  On  the 
other  hand,  it  works — -"If  it  ain't 
broke,  don’t  fix  it.” 

Availability 

This  column  is  part  of  a  four-part  se¬ 
ries  describing  the  entire  shell.  A  re¬ 
print  of  all  four  parts  along  with  a 
disk  containing  the  listings  and  an  ex¬ 
ecutable  version  of  the  shell  is  avail¬ 
able  for  $29.95  from  Dr.  Dobb's  Jour¬ 
nal,  2464  Embarcadero  Way,  Palo 
Alto,  CA  94303.  Please  direct  inquiries 
to  the  The  Shell.  Prepayment  is 
required.  ddj 

(Listings  begin  on  page  66) 
Reader  Ballot 
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by  Terry  Ritter 


The  Cyclic  Re¬ 
el  undancy 
Check  (or  CRC) 
is  a  way  to  detect  er¬ 
rors  in  data  storage  or 
transmission.  With 
more  and  more  data 
being  transmitted  over 
phone  lines,  the  need 
for  protocols  that  pro¬ 
tect  data  from  damage 
in  transit  has  in¬ 
creased,  but  the  the¬ 
ory  behind  CRC  gener¬ 
ation  is  not  well  known. 

What  Is  a  CRC? 

The  Cyclic  Redundancy  Checs  a  way  to  detect  small 
changes  in  blocks  of  data.  Error  detection  is  especially 
important  when  computer  programs  are  transmitted  or 
stored  because  an  error  of  even  one  bit  (perhaps  out  of 
hundreds  of  thousands)  is  often  sufficient  to  make  a  pro¬ 
gram  faulty.  Although  a  few  errors  in  a  text  file  might  be 
acceptable  (because  the  text  can  be  reedited  when  re¬ 
ceived  or  recovered),  an  error-free  file  is  preferable.  An 
error-correcting  protocol  triggered  by  CRC  error  detec¬ 
tion  can  provide  this  accuracy  at  low  cost. 

The  CRC  algorithm  operates  on  a  block  of  data  as  a 
unit.1  We  can  understand  the  CRC  better  if  we  see  this 
block  of  data  as  a  single  (large)  numerical  value.  The  CRC 
algorithm  divides  this  large  value  by  a  magic  number  (the 
CRC  polynomial  or  generator  polynomial),  leaving  the  re¬ 
mainder,  which  is  our  CRC  result. 


® 1985  by  T.  F.  Ritter.  All  rights  reserved.  Blue  Jean  Soft¬ 
ware,  2609  Choctaw  Trail,  Austin,  TX  78745 


The  CRC  result  can 
be  sent  or  stored  along 
with  the  original  data. 
When  the  data  is  re¬ 
ceived  (or  recovered 
from  storage),  the  CRC 
algorithm  can  be  reap¬ 
plied  and  the  latest  re¬ 
sult  compared  to  the 
original  result.  If  an  er¬ 
ror  has  occurred,  we 
will  probably  get  a  dif¬ 
ferent  CRC  result.  Most 
uses  of  the  CRC  do  not 
attempt  to  classify  or  locate  the  error  (or  errors)  but  sim¬ 
ply  arrange  to  repeat  the  data  operation  until  no  errors 
are  detected. 

Using  the  CRC 

The  IBM  8-inch  floppy  disk  specification  used  the  CRC- 
CCITT  polynomial  for  error  detection,  and  this  CRC  is  now 
used  in  almost  all  floppy  disk  controller  devices.  A  disk 
controller  computes  a  CRC  as  it  writes  a  disk  sector,  and 
then  it  appends  that  CRC  to  the  data.  When  the  data  is 
read  back,  a  new  CRC  is.  computed  from  the  recovered 
data  and  compared  to  the  original  CRC(M  If  the  CRC  values 
differ,  an  error  has  occurred  and  the  operation  is  repeat¬ 
ed.  The  standard  disk  CRC  (CRC-CCITT)  is  hidden  in  the 
controller  and  nowadays  receives  little  comment. 

One  version  of  the  XMODEM  (or  Christensen)  file  trans¬ 
mission  protocol  also  uses  the  CRC-CCITT  polynomial  to 
detect  data  transmission  errors  typically  caused  by  line 
noise.  When  the  receiving  end  detects  a  data  error,  it 
sends  a  NAK  (Negative  Acknowledge)  character  to  the 
sender,  which  requests  that  the  defective  data  block  be 
retransmitted.  The  receiving  end  repeats  this  process  un- 


Some  implementations  of  XMO¬ 
DEM  use  a  CRC  algorithm  that 
introduces  unnecessary  delay  in 
data  transmission.  CRCs  can  be 
used  in  communications ,  startup 
verification  of  ROM  code,  and 
program  and  data  correctness 
validation. 
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til  the  CRC  from  the  transmitting  end  matches  the  local 
result  or  until  one  or  both  ends  give  up.  When  the  result 
does  match,  the  receiving  end  sends  an  ACK  (acknowl¬ 
edge)  character,  and  the  transmitting  end  then  sends  the 
next  block. 

Error  Control  and  Efficiency 

Many  different  CRC  polynomials  are  possible;  these  gen¬ 
erator  polynomials  are  designed  and  constructed  to  have 
desirable  error-detection  properties.  If  the  CRC  polynomi¬ 
als  are  well  constructed,  the  major  difference  between 
them  is  in  their  length.  Longer  polynomials  provide 
more  assurance  of  data  accuracy  and  are  fully  usable 
over  larger  amounts  of  data;  however,  longer  polynomi¬ 
als  produce  longer  remainder  values,  adding  error- 
checking  overhead  to  the  data. 

A  “16-bit’'  polynomial  has  a  16-bit  remainder.  There 
are  two  well-known  16-bit  polynomials:  CRC-16  (used  in 
early  BISYNC  protocols)  and  CRC-CCITT  (used  in  disk  stor¬ 
age,  SDLC,  and  XMODEM  CRC).  Of  the  two,  CRC-CCITT  may 
be  a  little  stronger  and  by  convention  is  often  used  in 
ways  that  strengthen  its  error-detection  capabilities.  This 
article  illustrates  CRC-CCITT,  which  is  the  pnomial  x1B  + 
x12  +  x5  +  1. 

Polynomials  are  classified  by  their  highest  nonzero  dig¬ 
it  (or  place),  which  is  termed  the  degree  of  the  polynomi¬ 
al.  Both  CRC-16  and  CRC-CCITT  are  of  degree  16,  which 
means  that  bits  16  through  0  are  significant  in  their  de¬ 
scription;  a  degree-16  polynomial  thus  has  17  bits.  Nor¬ 
mally  we  are  most  concerned  with  the  remainder  of  the 
CRC  operation,  which  has  one  bit  less  than  the  polynomi¬ 
al.  Thus,  we  may  think  of  16-bit  CRCs,  even  though  their 
generator  polynomials  actually  contain  17  bits  (bits  16 
through  0). 

In  a  proper  CRC  polynomial,  both  the  most  significant 
bit  (MSb)  and  least  significant  bit  (LSb)  are  always  a  1.  Be¬ 
cause  the  highest  bit  of  the  polynomial  is  always  a  1,  we 
are  able  to  treat  this  bit  differently  from  the  other  bits  of 
the  polynomial.  Because  the  remainder  from  a  sixteenth- 
degree  polynomial  has  only  16  bits,  a  16-bit  register  is 
sufficient  for  CRC  operations  on  a  16-bit  polynomial,  even 
though  the  polynomial  itself  actually  has  17  bits. 

A  well-constructed  CRC  polynomial  over  limited-size 
data  blocks  will  detect  any  contiguous  burst  of  errors 
shorter  than  the  polynomial,  any  odd  number  of  errors 
throughout  the  block,  any  2  bit  errors  anywhere  in  the 
block,  and  most  other  cases  of  any  number  of  errors  any¬ 
where  in  the  data.2  So  every  possible  arrangement  of  1,  2, 
or  3  bit  errors  will  be  detected.  Nevertheless,  there  re¬ 
mains  a  small  possibility  that  some  errors  will  not  be  de¬ 
tected.  This  happens  when  the  pattern  of  the  errors  re¬ 
sults  in  a  new  value  that,  when  divided,  produces  exactly 
the  same  remainder  as  the  correct  block.  With  a  properly 
constructed  16-bit  CRC,  an  average  of  one  error  pattern 
will  not  be  detected  for  every  65,535  that  would  be  de¬ 
tected.  That  is,  with  CRC-CCITT,  we  can  detect  99.998  per¬ 
cent  of  all  possible  errors.3 

There  is  no  technique  we  can  use  to  absolutely  guaran¬ 
tee  detection  of  any  error,  but  we  can  minimize  unde- 
.tected  errors  at  reasonable  cost.  Other  error-detection 
techniques  are  available,  such  as  checksum  or  voting,  but 
these  have  poorer  error-detection  capabilities.  For  exam¬ 


ple,  the  single-byte  checksum  (used  in  the  original  ver¬ 
sion  of  XMODEM)  appears  to  be  about  99.29  percent  accu¬ 
rate,4  which  seems  pretty  good.  But  for  a  single 
additional  byte,  the  CRC  technique  is  about  460  times  less 
likely  to  let  an  error  pass  undetected.  In  practice,  the  dif¬ 
ference  is  much  greater  because  the  CRC  will  detect  all 
cases  of  the  most  common  errors  at  the  cost  of  a  2-byte 
CRC  value  in  every  block.  For  example,  the  XMODEM  pro¬ 
tocol  sends  data  in  128-byte  blocks;  these  blocks  can  be 
CRC  error-checked  with  an  additional  2  bytes — an  error- 
check  overhead  of  about  1.5  percent.5 

Polynomial  Arithmetic 

The  CRC  performs  its  magic  using  polynomial  modulo 
two  arithmetic.  Polynomial  arithmetic  mod  2  allows  an 
efficient  implementation  of  a  form  of  division  that  is  fast, 
easy  to  implement,  and  sufficient  for  the  purposes  of  er¬ 
ror  detection.  (This  scheme  is  not  particularly  useful  for 
the  division  of  common  numbers.)  Polynomial  arithmetic 
mod  2  differs  slightly  from  normal  computer  arithmetic, 
and  it  is  generally  the  most  confusing  part  of  the  CRC. 

A  polynomial  is  a  value  expressed  in  a  particular  alge¬ 
braic  form,  that  of 

An  *X"  +  A„_,  *Xnl  +  .  .  .  +  A,  *X  +  A0 

Our  common  number  system  is  an  implied  polynomial 
of  base  10:  Each  digit  means  the  value  of  that  digit  is  mul¬ 
tiplied  by  the  associated  power  of  10.  The  base  2  or  bina¬ 
ry  system  of  numeration  is  another  form  of  the  general 
polynomial  concept.  When  we  see  a  number,  we  think  of 
it  as  a  single  value;  we  mentally  perform  the  polynomial 
evaluation  in  the  assumed  base  to  get  a  single  result.  On 
the  other  hand,  formal  polynomials  are  considered  to  be 
a  list  of  multiple  separate  units,  and  the  existence  or  eval¬ 
uation  of  an  ultimate  single  value  for  the  polynomial 
may  not  be  important. 

Because  decimal  arithmetic  uses  constant-base  polyno¬ 
mials,  all  of  us  already  know  how  to  do  polynomial  arith¬ 
metic  in  a  constant  base  (10);  however,  the  polynomials 
used  in  CRC  calculations  are  polynomials  modulo  two.  By 
modulo  two  we  mean  that  a  digit  can  have  only  values  0 
and  1.  Of  course,  this  is  always  the  case  with  binary  values, 
so  you  might  well  wonder  what  all  the  mumbo  jumbo  is 
about.  The  difference  is  this:  A  modulo  polynomial  has  no 
carry  operation  between  places;6  each  place  is  computed 
separately.  We  perform  mod  2  operations  logically  bit  by 
bit;  in  mod  2,  the  addition  operation  is  a  logical  exclusive- 
OR  of  the  values,  and  mod  2  subtraction  is  exactly  the 
same  (exclusive-OR)  operation. 

Modulo  arithmetic  is  used  for  CRCs  because  of  its  sim¬ 
plicity:  Modulo  arithmetic  does  not  require  carry  or  bor¬ 
row  operations.  In  computing  hardware,  the  carry  cir¬ 
cuitry  is  a  major  part  of  arithmetic  computation  and  is  a 
major  contributor  to  speed  limitations.  Of  course,  be¬ 
cause  we  have  both  subtraction  and  exclusive-OR  in 
structions  available  in  most  computer  instruction  sets, 
this  advantage  is  less  important  for  software  implemen¬ 
tations  of  CRC.  Nevertheless,  the  simplicity  of  modulo 
arithmetic  allows  several  different  software  approaches 
not  available  in  conventional  arithmetic.  Note  that  the 
modulo-type  operations  available  in  programming  lan- 
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guages  (e.g.,  the  Pascal  MOD  operator)  operate  on  entire 
numbers  rather  than  individual  bits  or  places. 

A  polynomial  division  mod  2  is  very  similar  to  common 
binary  division,  except  that  we  perform  a  logical  exclu- 
sive-OR  operation  instead  of  an  arithmetic  subtraction. 
Similarly  because  '  greater  than”  and  "less  than”  are 
meaningless  in  modulo  arithmetic,  we  can  replace  these 
operators  by  performing  the  exclusive-OR  operation  if 
the  high  bit  is  set  or  1,  driving  the  high  part  of  the  divi¬ 
dend  to  zeros. 

We  can  implement  a  polynomial  division  as  follows:  A 
polynomial  division  register  of  a  length  corresponding  to 
the  remainder  produced  by  the  polynomial  to  be  used  is 
set  up  (see  Figure  1,  below).7  Each  element  of  the  register 
should  be  able  to  hold  the  maximum  modulo  value;  in 
mod  2,  a  single  bit  suffices.  (Note  that  the  hardware  dia¬ 
grams  are  intended  only  as  examples.  Very  short  CRCs 
are  of  limited  practical  use,  and  there  are  better  ways  to 
do  the  job.) 

The  register  is  cleared,  then  the  data  is  shifted  into  the 
register  from  the  right;  each  shift  is  a  polynomial  multi¬ 
plication.  Each  shift  also  shifts  a  bit  out  of  the  register 
from  the  most  significant  bit  (MSb).  We  know  that  the 
register  value  will  exceed  our  representation  when  the 
shifted-out  bit  is  logical  1,  so  we  arrange  to  perform  our 
polynomial  subtraction  when  this  happens;  that  is,  when 
we  shift  out  a  1,  we  exclusive-OR  the  polynomial  with 
the  value  in  the  register.  Because  our  polynomial  (the 
magic  number)  always  contains  a  high-order  bit,  which 
always  forces  the  shifted-out  bit  back  to  a  logical  0,  we 
need  not  actually  operate  on  the  high-order  bit.  So  only 
zeros  shift  out,  keeping  the  mod  2  polynomial  remainder 
in  the  register. 

This  bit-level  hardware  process  is  easily  simulated. 
Turbo  Pascal  algorithms  for  the  simulation  are  shown  in 


Figure  1:  Polynomial  Divide  Hardware  for  a  4  bit  CRC 


Listing  One,  page  76.  Software  simulation  has  the  advan¬ 
tage  of  a  fast  and  easy  investigation  of  an  algorithm,  al¬ 
lowing  quick  changes  to  try  out  various  forms  of  optimi¬ 
zation.  The  program  produces  a  "trace”  of  the  execution, 
showing  the  step-by-step  operation. 

The  polynomial  division  register  does  not  hold  the  de¬ 
sired  remainder  until  the  place  containing  the  last  data 
bit  has  been  shifted  out  of  the  register.  To  do  this,  a  zero 
data  bit  must  be  shifted  in  for  every  bit  of  the  register.  In 
the  case  of  CRC-CCITT,  16  bits  (2  bytes)  of  zeros  need  to  be 
appended  to  the  data.  After  entering  the  zero  bits,  the 
result  in  the  polynomial  division  register  is  the  CRC  result. 
The  common  implementations  of  XMODEM  usually  re¬ 
quire  these  two  trailing  bytes. 

The  CRC  result  can  be  obtained  without  shifting  in  the 
two  zero  bytes  by  rearranging  the  CRC  register  and  feed¬ 
ing  the  data  in  at  the  "top  end”  of  the  system  (see  Figure  2, 
below).  By  shifting  the  CRC  register,  we  can  shift  zeros  in 
from  the  right.  The  data  bit  will  be  compared  to  the  MSb 
in  the  CRC  register,  and  only  if  they  differ  will  the  poly¬ 
nomial  be  subtracted.  As  before,  this  acts  to  keep  the  full 
remainder  in  the  register;  however,  the  remainder  is 
now  correct  after  each  bit  and  requires  no  trailing  zeros. 
A  simulatioof  this  immediate-result  algorithm  (called,  for 
lack  of  a  better  name,  the  CRC  algorithm)  is  also  given  in 
Listing  One  for  comparison  to  polynomial  division.  No¬ 
tice  that  both  the  polynomial  division  and  CRC  algorithms 
come  up  with  the  same  remainder  (or  CRC  value),  but  the 
CRC  version  does  it  faster  and  with  more  consistent  logic. 

Faster  CRCs  in  Software 

The  bit-by-bit  form  of  the  CRC  algorithm  can  be,  and  often 
is,  directly  simulated  in  software.  The  shifting  and  loop¬ 
ing  required  by  this  approach  can  be  reduced  in  several 
ways.  Both  byte-oriented8  and  table-oriented9  algo¬ 
rithms  have  been  available  in  the  technical  literature  for 
a  number  of  years.  Table-oriented  algorithms  may  (or 
may  not)  produce  somewhat  higher  speed  at  the  ex- 


Figure  2:  CRC  Hardware 
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pense  of  a  sizable  table  of  constants  that  generally 
must  be  intialized  before  use.  Examples  of  the  various 
forms  of  CRC  algorithms  are  given  in  Listing  Two  (page 
78). 

We  can  speed  up  the  algorithm  even  more  by  precom¬ 
puting  the  CRC  for  all  possible  combinations  of  a  16-bit 
CRC  and  a  data  byte  and  then  saving  the  results.  Done 
naively  this  would  be  a  transformation  of  24  bits  (16  bits 
of  the  previous  register  and  8  bits  of  data)  into  16  bits.  This 
approach  would  thus  require  225  bytes  (about  34  mega¬ 
bytes)  of  lookup  table.  In  order  to  make  the  table  ap¬ 
proach  practical,  we  must  find  a  way  to  reduce  the  size 
of  the  table. 

If  we  examine  the  CRC  hardware,  we  notice  that  the 
current  data  bit  is  always  combined  with  the  current 
MSb  of  the  CRC  register.  When  we  compute  a  whole-byte 
CRC,  we  end  up  combining  the  whole  data  byte  with  the 
high  byte  of  the  CRC.  We  can  precompute  the  exclusive- 
OR  of  the  data  byte  and  the  high  byte  of  the  CRC  register 
(this  is  a  single-byte  operation  in  software),  yielding  a  sin¬ 
gle  byte  we  can  call  the  combined  term  or  the  combina¬ 
tion  value. 

For  the  common  16-bit  CRCs,  it  turns  out  that  the  CRC 
register  changes  in  patterns  that  have  a  direct  mapping 
from  the  combination  value.  Thus,  it  is  possible  to  pre¬ 
compute  the  CRC  changes  for  all  256  possible  combination 
values.  Then,  when  we  need  to  do  a  CRC,  we  can  use  the 
1-byte  combination  value  to  look  up  a  corresponding  2- 
byte  result,  then  use  that  result  to  correctly  change  the 
CRC  register.  As  you  might  expect,  the  required  change  is 
simply  a  2-byte  exclusive-OR  operation. 

To  generate  the  data  for  the  lookup  table,  we  need  only 
generate  the  2-byte  CRC  result  for  all  256  possible  data 
bytes,  given  an  "all-zeros”  starting  CRC  register.  Each  re¬ 
sult  is  a  1  for  those  bits  in  the  CRC  register  that  are  changed 
by  a  particular  combination  code.  We  can  use  a  nontable 
implementation  of  the  CRC  to  compute  the  table  values. 

This  approach  to  generating  a  table  of  CRC  values  re¬ 
quires  a  512-byte  lookup  table.  We  must  fill  the  table  with 
the  correct  data  in  an  initialization  step  and  perform  a 
few  more  run-time  operations  than  the  straight  lookup 
process  requires  (compute  the  combination  value,  look 
up  the  result,  then  apply  the  result  to  the  CRC  register  and 
compute  the  new  CRC  value). 

Another  variation  that  is  faster  than  the  original  bit-by- 
bit  approach  and  that  also  eliminates  the  lookup  storage 
of  the  table  approach  is  the  byte  wide  shifting  algorithm. 
A  bytewide  approach  eliminates  seven  bit-by-bit  test- 
and-jump  operations,  which  are  a  significant  overhead 
in  the  bit-by-bit  version,  and  also  takes  advantage  of  fast- 
shift  and  parallel-logic  operations  available  on  most  pro¬ 
cessors  (as  well  as  some  high-level  languages  such  as  Tur¬ 
bo  Pascal  or  C). 

First,  we  need  some  more  algebra:  By  giving  each  CRC 
register  bit  and  each  data  bit  a  separate  symbol-,  we  can 
express  the  result  of  a  CRC  operation  symbolically.  Each 
bit  of  the  CRC  register  will  be  represented  by  a  formula 
showing  all  the  data  and  original  CRC  bits  that  affect  that 
bit  in  the  result.  If  we  take  the  exclusive-OR  of  the  bits 


specified  by  the  formula,  we  can  directly  calculate  any 
bit  of  the  CRC  result. 

In  order  to  generate  the  formulas  for  each  bit  of  the 
CRC  register,  we  create  an  algebraic  analog  of  the  shifting 
and  combining  process  of  the  bit-by-bit  CRC  algorithm. 
Instead  of  shifting  bit  values  (as  in  a  normal  shift  register), 
we  move  the  whole  symbolic  formula  for  each  bit  to  the 
next  higher  bit  position.  Instead  of  actually  performing 
an  exclusive-OR  operation,  we  concatenate  the  formula 
for  the  data  bit  to  each  of  the  affected  bits  in  the  CRC 
register  with  a  symbol  indicating  an  exclusive-OR  opera¬ 
tion.  If  ever  we  find  two  identical  variables  in  any  one 
formula,  we  can  cancel  and  eliminate  them  both  (be¬ 
cause  anything  exclusive-ORed  with  itself  is  zero,  and 
zero  exclusive-ORed  with  any  value  is  just  that  value). 

After  symbolically  processing  a  whole  byte  of  data  and 
eliminating  common  terms,  we  come  up  with  a  symbolic 
representation  for  each  bit  of  the  result.  By  factoring  this 
expression  into  convenient  computer  operations,  a  pro¬ 
gram  is  obtained  that  uses  the  bit  parallelism  available  in 
software. 

CRC  Deviations 

More  improvement  is  possible.  We  have  previously  as¬ 
sumed  that  the  CRC  register  is  cleared  before  starting  the 
computation  and  also  that  we  specifically  compare  the 
stored  (or  transmitted)  CRC  value  to  the  current  CRC  re¬ 
sult.  These  assumptions  are  discarded  in  protocols  other 
than  XMODEM.10 

When  a  CRC  register  contains  only  zeros,  processing  a 
zero  data  bit  does  not  change  the  CRC  remainder.  So,  if 
the  CRC  register  is  clear  and  extraneous  zero  bits  do  oc¬ 
cur,  these  data  errors  will  not  be  detected.  For  this  rea¬ 
son,  most  current  CRC  protocols  initialize  the  CRC  register 
to  all  Is  before  they  start  the  computation,  allowing  the 
detection  of  extraneous  leading  zeros. 

We  can  also  eliminate  the  need  to  detect  the  separate 
CRC  field  at  the  end  of  a  data  block.  If  the  CRC  result  is 
simply  attached  to  the  end  of  the  data,  the  receiving  CRC 
register  will  clear  itself  automatically  if  there  is  no  error; 
that  is,  each  bit  of  the  stored  or  transmitted  CRC  value 
should  cancel  the  similar  bit  in  the  CRC  register.  Although 
of  minor  importance  for  software  implementations,  this 
is  a  reasonable  simplification  for  hardware  CRC  devices 
because  it  allows  the  same  hardware  to  be  used  regard¬ 
less  of  block  length. 

When  the  CRC  remainder  is  appended  to  the  end  of  the 
data  (thus  eliminating  the  need  to  detect  it  as  a  separate 
field),  and  if  bit-level  CRC  hardware  is  also  to  be  support¬ 
ed,  CRC  software  may  need  to  use  data  in  reverse  bit  or¬ 
der.  This  is  because  bit-level  CRC  hardware  works  on  data 
after  it  has  been  serialized,  and  data  is  traditionally  serial¬ 
ized  LSb-first.  That  is,  the  parallel-to-serial  conversion  in 
an  asynchronous  serial  device  sends  the  rightmost  bit  of  a 
character  first  and  the  leftmost  bit  last.  The  bit-level  CRC 
hardware  has  little  choice  but  to  treat  the  resulting  data- 
stream  as  a  single  large  number,  but  that  data-stream  has 
its  byte-level  bit-order  changed  from  our  usual  numeri¬ 
cal  expectations. 

If  an  MSb-leftmost  CRC  routine  is  to  be  compatible  with 
bit-level  CRC  hardware,  it  may  be  necessary  to  reverse 
the  bit  order  of  every  data  byte  (before  each  is  processed 
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or  serialized)  and  also  the  CRC  remainder  bytes  (after  the 
block  ends).  Bit-order  reversal  can  be  done  in  software, 
hardware,  or  both.  Alternately,  the  CRC  algorithm  could 
be  reconstructed  so  as  to  use  and  hold  MSb-rightmost 
data. 

In  strictly  software  CRC  implementations,  however,  we 
work  on  data  before  it  is  serialized  and  after  it  is  recov¬ 
ered,  and  we  trust  any  serialization  that  occurs  to  be 
transparent.  We  can  t  afford  to  treat  the  data-stream  as  a 
single  large  value  with  MSb-leftmost,  with  MSb-leftmost 
bytes,  and  a  similar  MSb-leftmost  CRC  remainder  append¬ 
ed  on  the  right.  This  arrangement  is  most  consistent  with 
both  the  theory  and  our  numerical  conventions  and  is 
the  form  used  by  XMODEM.  The  CRC  routines  shown  in 
this  article  use  MSb-leftmost  data  and  keep  the  result  also 
in  MSb-leftmost  format. 

If  we  arrange  to  verify  the  CRC  by  processing  the  CRC 
result  as  data,  we  again  fall  prey  to  extraneous  zero  data 
bits.  In  order  to  detect  such  errors,  we  arrange  for  the 
CRC  register  to  take  on  a  unique  nonzero  value  in  the 
event  of  no  error.  By  some  quirk  of  the  algebra,  it  turns 
out  that  if  we  transmit  the  complement  of  the  CRC  result 
and  then  CRC-process  that  as  data  upon  reception,  the 
CRC  register  will  contain  a  unique  nonzero  value  depend¬ 
ing  only  upon  the  CRC  polynomial  (and  the  occurrence  of 


CRCTIME,  85/9/18 

Execution  times  for  various  CRC  implementations. 

Copyright  (c)  1985,  T.F.  Ritter;  All  Rights  Reserved. 

BEGIN  Validation  Testing. 

Reference  =  crcittby  (Pascal  Bit-By-Bit), 
crcfbbb  (Pascal  Fast  Bit-By-Bit):  No  error, 
crcitta  (Pascal  Byte):  No  error, 
crctablu  (Pascal  Table):  No  error, 
mcrcittl  (Machine  Code  Byte):  No  error. 
mcrcitt3  (Machine  Code  Table):  No  error. 

END  Validation  Testing. 

Turbo  Pascal  runs  CRC-CCITT  on  8088  under  Bare  MSDOS 
FOR  10000  OPERATIONS;  7.16  MHz  CLOCK  (multiply  by  1.5 
for  4.77  MHz) 


Empty  loop:  0.160  secs 

Empty  procedure  in  loop:  0.880  secs 


(procedure  overhead  alone  =  0.072  msec 

10,000  Uses(secs) 
Procedure  In  Line 

each) 

1  Use  (msec) 
Procedure  In  Line 

Pascal  Bit-by-Bit: 

13.790 

13.070 

1.379 

1.307 

Pascal  Fast  B-B-B: 

7.310 

6.590 

0.731 

0.659 

Pascal  Byte: 

2.150 

1.430 

0.215 

0.143 

Pascal  Table: 

1.430 

0.710 

0.143 

0.071 

Machine  Code  Byte: 

1.050 

0.330 

0.105 

0.033 

Machine  Code  Table: 

0.890 

0.170 

0.089 

0.017 

Table  1 


no  errors).  This  scheme  is  now  used  by  most  CRC  proto¬ 
cols,  and  the  magic  remainder  for  CRC-CCITT  is  $1D0F 
(hex). 

Actual  CRC  Implementations 

I  constructed  several  CRC  implementations  for  speed  and 
size  comparisons  (see  Listing  Two).  The  CRC-CCITT  poly¬ 
nomial  was  used  because  this  is  the  polynomial  used  in 
XMODEM,  as  well  as  many  other  data  communication 
uses.  I  used  Turbo  Pascal,  though  the  code  could  obvious¬ 
ly  be  rewritten  in  C.  A  couple  of  the  operations  used  are 
Turbo  Pascal  extensions:  Swap(  )  is  an  INTEGER  function 
that  exchanges  the  high  and  low  byte  of  an  integer  value; 
Lot  )  is  an  INTEGER  function  that  selects  only  the  low  byte 
of  an  integer. 

I  used  the  Pascal  Bit-by-Bit  approach  (a  direct  simula¬ 
tion  of  the  hardware  method)  to  provide  a  reference 
against  which  the  other  algorithms  are  compared.  The 
Pascal  Fast  B-B-B  is  an  improved  bit  form  comparable  to 
most  high-level  language  implementations  of  the  XMO¬ 
DEM  CRC,  except  that  this  version  requires  no  trailing  ze¬ 
ros  to  finish  the  calculation  (and  so  is  already  faster  than 
the  usual  version).  The  Pascal  Byte  version  illustrates  the 
improvement  wrought  from  algebraic  factoring;  the  Pas¬ 
cal  Table  version  shows  how  a  precomputed  table  can 
simplify  and  speed  execution-time  operation.  The  Ma¬ 
chine  Code  versions  of  Byte  and  Table  show  yet  more 
improved  speed.  The  different  approaches  illustrate  var¬ 
ious  trade-offs  of  speed,  space,  and  specialization.  The 
results  (Table  1,  left)  show  a  range  of  almost  two  orders  of 
magnitude  in  execution  speed. 

Each  CRC  implementation  was  made  into  a  Pascal  PRO¬ 
CEDURE  for  easy  testing  and  comparison.  For  validation, 
varying  amounts  of  program  code  from  main  memory 
were  processed  by  each  implementation.  All  algorithms 
achieved  the  same  results.  Several  of  these  versions  have 
been  placed  in  an  implementation  of  XMODEM  with  good 
results. 

Time  Tests 

For  the  time  tests,  each  implementation  was  executed 
10,000  times  under  Turbo  Pascal  3.01A  on  an  8088  in  a 
Leading  Edge  PC  with  a  7. 16-megahertz  (MHz)  clock;  the 
times  would  be  50  percent  longer  on  an  IBM  PC.  The  time 
was  taken  automatically  from  MS  DOS.  Because  the  MS  DOS 
timer  ticks  only  about  18.2  times  per  second,  this  method 
is  only  precise  within  about  55  milliseconds  (msec)  at  both 
the  start  and  end  of  the  timing  interval.  The  large  num¬ 
ber  of  repetitions  minimize  this  effect. 

The  time  reported  as  "10,000  uses”  is  real  time  de¬ 
creased  by  the  amount  of  time  taken  by  10,000  empty 
loops,  thus  giving  us  the  time  associated  with  the  proce¬ 
dure  call  and  execution  instead  of  also  including  the  loop¬ 
ing  structure  that  we  use  only  for  the  tests.  The  In  Line 
column  decreases  "10,000  uses”  by  the  time  taken  for 
10,000  procedure  calls  and  returns,  giving  the  time  for 
execution  only. 

Selection  Criteria 

The  time  necessary  to  process  a  byte  (including  the  CRC 
operation  and  whatever  queuing  operations  and  other 
tests  that  need  to  be  performed)  should  be  less  than  the 
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time  it  takes  to  receive  a  character.  We  could  simply  ac¬ 
cumulate  the  data  in  a  block  as  it  is  received  and  then 
CRC-process  the  whole  block,  but  this  procedure  would 
add  some  delay  or  latency  between  receiving  the  last 
data  byte  and  returning  a  response  to  the  sender  (ACK  for 
good  data  and  NAK  for  an  error  in  XMODEM).  Some  XMO¬ 
DEM  implementations  appear  to  use  this  method,  giving 
the  impression  that  the  protocol  or  the  CRC  is  responsible 
for  the  delay.  Because  fast  CRC  routines  are  obviously  pos¬ 
sible,  it  is  hard  to  rationalize  any  latency  at  all.11 

The  Pascal  Byte  version,  which  takes  only  a  few  lines 
of  code  and  is  machine  independent  (under  Turbo  Pas¬ 
cal),  may  be  suitable  for  speeds  up  to  9,600  bps  and  is  a 
reasonable  choice  for  most  use.  The  Pascal  Table  version 
is  a  little  faster,  but  the  table  generally  must  be  initialized 
before  use,  either  by  using  a  different  CRC  version,  or 
perhaps  by  reading  the  values  in  from  a  file.  Alternately 
(in  most  languages)  the  table  could  be  defined  in  the 
source  code  as  a  large  body  of  constants. 

The  faster  versions  can  generally  benefit  from  being 
used  in-line  (that  is,  not  as  procedures)  to  avoid  procedure 
call/return  overhead,  but  this  is  also  inconvenient  because 
each  use  would  involve  duplicating  the  same  code  in  dif¬ 
ferent  places.  The  Machine  Code  Table  version  is  shorter 
and  so  would  minimize  the  duplication  penalty.  The  Pas¬ 
cal  Table  version  can  also  be  used  in-line  because  it  takes  a 
minimum  amount  of  code.  I  use  an  Include  file  holding 
the  Machine  Code  Byte  version,  then  call  the  rou¬ 
tine  as  a  procedure;  the  resulting  code  is  both  small  and  fast. 

Other  Uses 

Although  this  article  has  concentrated  on  CRCs  in  commu¬ 
nications  and  data  storage,  CRCs  can  be  used  in  many  dif¬ 
ferent  applications  involving  error  detection.  Such  appli¬ 
cations  include  start-up  verification  of  ROM  code, 
load-time  verification  of  RAM  modules  (as  in  the  6809  oper¬ 
ating  system  OS9),  and  program  and  data  correctness 
validation. 

Note  that  CRC  polynomials  are  designed  and  construct¬ 
ed  for  use  over  data  blocks  of  limited  size;  larger  amounts 
of  data  will  invalidate  some  of  the  expected  properties 
(such  as  the  guarantee  of  detecting  any  2-bit  errors).  For 
16-bit  polynomials,  the  maximum  designed  data  length  is 
generally  215— 1  bits,  which  is  just  one  bit  less  than  4K 
bytes.  Consequently,  a  16-bit  polynomial  is  probably  not 
the  best  choice  to  produce  a  single  result  representing  an 
entire  file  or  even  to  verify  a  single  EPROM  device  (which 
is  now  commonly  8K  or  more).  For  this  reason,  the  OS9 
polynomial  is  24  bits  long. 

How  To  Learn  More 

A  good  introduction  to  CRCs  can  be  found  in  the  classic 
Error  Correcting  Codes,  2d  ed.,  by  Peterson  and  Weldon 
(Cambridge,  Mass.:  MIT  Press,  1972),  but  you  can  expect  to 
do  some  serious  math  to  understand  it.  A  brief  nonmathe- 
matical  chapter  on  CRC  error  detection  in  data  applica¬ 
tions  (with  some  good  figures)  is  available  in  Technical 
Aspects  of  Data  Communication,  2d  ed.,  by  J.  McNamara 
(Digital  Equipment  Corporation:  Digital  Press,  1982).  The 


very  brief  section  in  Computer  Networks  by  A.  Tanen- 
baum  is  also  fairly  good. 

Notes 

1.  The  CRC  does  not  require  a  fixed  block  size  (though 
there  is  a  built-in  maximum),  but  some  error-correcting 
protocols  do.  Larger  amounts  of  data  are  simply  parti¬ 
tioned  into  blocks  that  are  considered  separately. 
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sign  decisions  in  XMODEM  typically  add  yet  another  four 
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tionally  degraded  in  implementation. 

6.  The  general  case  of  polynomial  arithmetic,  which  al¬ 
lows  a  nonconstant  base,  generally  makes  carry  opera¬ 
tions  (between  terms)  difficult. 

7.  It  is  common  and  traditional  for  the  CRC  register  to  be 
shown  shifting  right,  which  is  the  exact  reverse  of  this 
author’s  analogy  to  binary  division.  Given  our  system  of 
numeration,  it  seems  reasonable  to  place  most  significant 
digits  of  one  value  to  the  left,  and  it  is  then  correct  for  the 
CRC  register  to  be  seen  as  shifting  to  the  left. 
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menting  Polynomial  Error  Detection  Codes.”  Computer 
Design  (March  1975):  73  —  77;  Perez,  A.  "Byte-wise  CRC  Cal¬ 
culations.”  IEEE  Micro  (June  1983):  40  —  50;  Schwaderer,  D. 
"CRC  Calculation.”  PC  Tech  Journal  (April  1985):  118  —  32. 

10.  McKee,  H.  "Improved  CRC  Technique  Detects  Errone¬ 
ous  Leading  and  Trailing  0's  in  Transmitted  Data  Blocks.” 
Computer  Design  (October  1975):  102  —  6;  Fortune,  P. 
"Two-Step  Procedure  Improves  CRC  Mechanism.”  Com¬ 
puter  Design  (November  1977):  116—29. 

11.  Some  protocols  other  than  XMODEM  allow  subsequent 
blocks  to  be  sent  before  a  previous  block  is  acknowl¬ 
edged,  thus  minimizing  the  latency  problem. 
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Fast  Integer  Powers 
for  Pascal 


Because  the  Pascal  language 
does  not  provide  any  built-in 
operation  (such  as  FORTRAN'S 
X**n)  for  powers  of  numbers,  pro¬ 
grammers  are  led  to  try  the  costly 
and  unreliable  substitute 
ey.p(n  *ln(\)).  When  n  is  an  integer, 
however,  there  are  often  ways  to 
factor  out  computation  of  powers  al¬ 
together.  When  direct  use  of  powers 
is  still  desirable,  the  Pascal  function 
Power  Nix,  n)  introduces  the  fastest 
method  known  for  general  computa¬ 
tion  of  x**n  for  n,  an  unrestricted  in¬ 
teger  not  known  in  advance. 

Increasing  llse  of  Powers 

Repetitive  computation  of  powers  of 
numbers  is  almost  commonplace 
now  that  personal  computers  and 
software  make  elaborate  arithmetic 
computations  more  affordable  and 
easier  to  express. 

Powers  do  not  occur  merely  in  the 
evaluations  of  polynomials  and  the 
summations  of  series  for  computing 
specialized  mathematical  functions. 
Powers  (especially  ones  with  variable 
exponents)  occur  routinely  in  work 
with  statistics  and  probabilities  and  in 
financial  and  economic  formulas. 

Typically  the  exponent  is  an  exact 
integer,  opening  up  the  possibility  of 
using  special  shortcuts  for  faster  and 
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more  accurate  computation.  The  Pas¬ 
cal  PowerN  function  introduced  in 
this  article  uses  just  such  shortcuts  to 
implement  the  fastest  general  com¬ 
putation  known. 

PowerN  is  extremely  efficient  on 
systems,  including  most  microcom¬ 
puters,  where  floating-point  arith¬ 
metic  is  more  costly  than  small-inte¬ 
ger  hardware  operations.  Use  of 
PowerN  is  also  almost  always  prefer¬ 
able  to  use  of  the  questionable 
ey.p(n*ln(y.))  logarithmic  method. 
(See  sources  1;  7;  15;  11,  Section  4.6.4 
for  even  better  possibilities.) 

Powers  Defined 

For  integer  exponent  value,  n,  the 
nth  power  of  the  base  value  x  is  des¬ 
ignated  here  by  the  notation  x**n 
originally  popularized  in  FORTRAN. 
These  powers  are  usefully  under¬ 
stood  in  terms  of  repeated-multipli¬ 
cation  operations  according  to  the 
scheme  proposed  in  1676  by  Isaac 
Newton: 

x**n  =  x*\*  .  .  .  *x,  n  >  0 

■*—  n  x's  — 1 * 

=  1,  n  =  0  and  x  <  >  0 

=  l/x**(  — n),  n  <  0  and  x  <  >  0 

This  formulation  of  x**n  (and  the 
mathematician's  xn)  satisfies  our  in¬ 
tuitions  (for  n  >  0  at  any  rate)  and 


allows  use  of  some  nicely  general¬ 
ized  "laws  of  exponents”  for  powers: 

x~(i+j)  =  x**i*x**j, 

x  <  >  0  or  (i  >  0  and  j  >  0) 
x**(i*j)  =  (x**i)**j, 

The  restrictions  are  significant:  Stan¬ 
dard  mathematics  defines  no  specific 
quotients  for  divisions  by  zero;  it  is 
technically  important  to  avoid  sneak¬ 
ing  any  in  as  loopholes  of  the  expo¬ 
nent  laws.  With  due  allowance  for  the 
restrictions,  satisfaction  of  these  laws 
justifies  the  shortcuts  in  practical  com¬ 
putations  with  variable,  large  n. 

Algorithm  Performance 

Pascal  function  Power N(y.,  n),  given 
in  Listing  One,  page  84,  derives  y**n 
using  exactly 

MC(n)  =  floor(lg(n) )  + 

bitsl(n)  —  1,  n  >  0 

=  0,  n  =  0 

=  MC(  — n),  n  <  0 

multiplications.  Here,  bitsl(n)  is  the 
number  of  1-bits  in  the  representa¬ 
tion  of  n  by  a  binary  integer,  lg(n)  is 
the  base  2  logarithm  of  n,  and floor(y) 
is  the  greatest  integer  that  isn’t  larger 
than  y.  Even  the  ambitious  case 
PowerN (y.,  32767)  is  computed  with 
only  28  multiplication  operations  (in¬ 
cluding  sqr(y)  =  x*x)- 

Another  part  of  the  claim  to 
PowerN’s  superiority,  despite  its  su¬ 
perficial  complexity,  involves  the  de¬ 
cision  cost  expended  in  order  to 
achieve  so  few  multiplications.  The 
number  of  questions  of  the  form 
odd(i)?  i  <  >  1?  n  <  0?  that  have  to 
be  asked  is 

DC(n)  =  MC(n)  +  4,  n  <  >  0 
where  two  are  just  for  checking  the 
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special  n  =  0  and  n  <  0  cases.  The 
two  extras  arise  when  the  not  odd(i) 
and  i  <  >  1  checks  finally  fail — it's 
time  not  to  multiply. 

PowerN  also  never  computes  any¬ 
thing  not  used  in  the  final  result.  Fail¬ 
ures  (such  as  overflow)  in  intermedi¬ 
ate  computations  occur  only  when 
failure  is  truly  inescapable. 

Accuracy  Considerations 

To  confirm  that  PowerN  does  indeed 
produce  expected  results,  I  have  in¬ 
cluded  a  Turbo  Pascal  driver  pro¬ 
gram  called  TPWRN.PAS  (See  Listing 
Two,  page  84.) 

Using  TPWRN,  7**i  is  computed  ex¬ 
actly  and  rapidly  up  to  i  =  14.  There¬ 
after,  the  39-bit  effective  precision 
(and  11-digit  output  rounding)  are  in¬ 
adequate  for  confirming  exact  re¬ 
sults  with  the  CP/M-80  edition  of  Tur¬ 
bo  Pascal. 

On  the  other  hand,  comparative 
calculations  for  (1/7)**— i,  although 
mathematically  the  same  as  7**i,  de¬ 
teriorate  quickly.  Value  1/7  cannot 
be  carried  exactly  and  the  discrep¬ 
ancy  is  quickly  magnified  in  taking 
powers.  By  i  =  14,  the  error  exceeds 
10,  even  though  minimal  error  in 
7**14  has  just  shown  up. 

The  final  column  of  TPWRN  output 
shows  how  much  more  quickly  the 
calculus  textbook  approach,  using 
eyp(i*ln(7)),  breaks  down.  Because 
this  method  is  noticeably  slower  as 
well,  there  is  nothing  to  commend  it 
for  exact-integer  exponents. 

In  making  use  of  these  results, 
keep  in  mind  that  the  PowerN  vin¬ 
tage  l.xx  algorithms  are  the  best 
available  in  terms  of  providing  a  di¬ 
rect  solution  at  minimum  cost.  Nev¬ 
ertheless,  working  with  the  same 
precision  as  the  input  data  inevitably 
dooms  you  to  some  sort  of  error.  It  is 
wise  to  be  mindful  of  the  prospective 
errors,  however  insignificant  you  re¬ 
gard  them  to  be. 

PowerN  Method 

PowerN  makes  rapid  computation  of 
integer  powers  using  the  fundamen¬ 
tal  method  of  Donald  E.  Knuth’s  algo¬ 
rithm  4.6.3A  (see  source  11).  The 
number  of  floating-point  multiplica¬ 
tions  is  reduced  by  taking  advantage 
of  the  laws  of  exponents,  in  form 

x**2i  =  sqr(x)**i,  i  >  0 

x**(2i  +  l)  =  x**2i  *  x,  i  >  0 


In  Knuth's  formulation,  as  in 
PowerN,  the  first  transformation  is 
performed  in  an  inner  loop  that 
doesn't  stop  until  an  odd  exponent  is 
inevitably  reached.  This  idea  is  ele¬ 
gantly  restated,  at  somewhat  in¬ 
creased  decision  cost,  by  Dijkstra  and 
Jensen  and  Wirth  (see  sources  3  and 
10): 

r  :  =  1.0; 

while  i  >  0 
do  begin 

while  not  odd(i) 
do  begin 
x :  =  sqr(x); 
i  :  =  i  div  2 
end; 

r  :=  r*x;  i  :=  i  —  1; 
end; 

The  lower  decision  cost  of  PowerN 
is  obtained  by  not  checking  for  even  / 
quite  so  often.  This  applies  a  sugges¬ 
tion  of  David  Gries  to  the  effect  that 
the  inner  while  can  be  replaced  by 
repeat  upon  arranging  that  i  always 
be  even  whenever  the  j >  0  test  passes 
(see  som  ce  6).  The  saving  of  decisions 
is  comparable  to  what  Knuth  obtains 
from  the  start  usinggo  to. 

The  main  new  idea  in  PowerN  in¬ 
volves  using  the  initialization  (for 
guaranteeing  that  even  powers  al¬ 
ways  remain)  to  also  replace  the  usu¬ 
al  r  :=  1.0  and  first  r  :=  r*y  by  a  well- 
timed  r  :=  y. 

The  procedure  is  further  opti¬ 
mized  by  using  i  shr  1  in  place  of  i  div 
2  on  Pascal  implementations  that 
permit  it.  Because  i  div  2  has  the  ef¬ 
fect  of  also  decrementing  odd  values 
of  i  in  the  one  operation,  separate  ad¬ 
justments  to  i  are  unnecessary. 

PowerN  (y,  0)  =  y/y  deserves  spe¬ 
cial  mention.  It  is  not  known  what 
nonstandard  assumptions  are  imple¬ 
mented  in  each  computer  arithme¬ 
tic.  If  there  is  some  provision  for  un¬ 
defined  operation  0/0,  however,  you 
would  wish  to  employ  it.  Use  of  y/y 
to  catch  y  =  0  or  y  =  nonstandard 
value  is  then  consistent  with  IEEE 
proposals  for  floating-point  arithme¬ 
tic  (see  source  2).  It  is  also  as  good  as 
any  other  approach,  assuming  con¬ 
sistent  extension  of  the  laws  of  arith¬ 
metic  and  exponentiation  to  propo- 
gate  indeterminate  results; 

x**0  =  x**-0  =  l/(x**0); 

x/x  =  l/(x/x); 


or  simply 

x**0  =  x**(l-l)  =  x/x. 

PowerN  is  contrived  to  propogate  all 
cases  without  knowing  in  advance 
which  ones  actually  apply. 

Availability 

Current  editions  of  POWERN.PLB  (List¬ 
ing  One)  and  the  TPWRN.PAS  test 
driver  are  posted  to  the  Borland  In¬ 
ternational  Forum  (page  BOR-100)  on 
the  CompuServe  Information  Ser¬ 
vice.  Database  DL1  of  the  forum  pro¬ 
vides  ready-to-run  Turbo  Pascal  ver¬ 
sions. 

I  check  onto  CompuServe  regular¬ 
ly.  You  can  contact  me  via  User 
ID  70100,271  for  open  discussions 
on  either  the  CP/M  Forum  (go  CPMSIG) 
or  the  Borland  International  Forum. 

Sources 

Because  powers  are  not  as  elemen¬ 
tary  as  the  standard  operations  of  ad¬ 
dition,  subtraction,  and  multiplica¬ 
tion,  they  (like  general  division  and 
remainder  operations)  still  lack 
widely  recognized  standard  mathe¬ 
matical  definitions.  (Despite  this  con¬ 
dition,  many  programming  language 
manuals  and  standards  continue  to 
omit  definitions  for  their  language’s 
implementation  of  powers,  long  af¬ 
ter  the  ALGOL  60  report  established 
the  standard  of  precision  I’ve  tried  to 
sustain  here.) 

This  decade  has  seen  renewed  in¬ 
terest  in  computation  of  powers  be¬ 
cause  the  high-performance  tech¬ 
nique  provides  a  lovely  algorithmic 
method  for  generalization  to  several 
other  problems.  Even  so,  recent  in¬ 
terest  in  describing  computational 
methods  for  powers  hasn't  stabi¬ 
lized:  Little  slips  are  made  in  even 
the  latest  work,  sometimes  despite 
the  existence  of  superior  versions  in 
older,  accessible  publications. 

1.  Cody,  William  J.,  Jr.,  and  Waite, 
William.  Software  Manual  for  the  Ele¬ 
mentary  Functions.  Englewood  Cliffs, 
N.J.:  Prentice-Hall,  1980.  If  computa¬ 
tional  cost  and  exclusion  of  Useful 
cases  weren’t  enough  of  an  indict¬ 
ment  of  eyp(n*ln(y))  for  y**n,  there 
are  also  accuracy  problems  to  con¬ 
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Learning  Ada  on  a  Micro 


If  you  want  to  use  the  most  tech¬ 
nically  advanced  programming 
language  available,  you  should 
learn  Ada. 

Validated  Ada  compilers  are  ex¬ 
pensive  and  run  on  mainframe  com¬ 
puters,  but  there  is  an  affordable  Ada 
subset  that  runs  on  CP/M-80  systems 
and  that  is  complete  enough  to  give 
you  some  useful  experience.  I  wrote 
and  tested  all  the  examples  in  this  ar¬ 
ticle  on  a  62K  CP/M  system  using  a 
beta-test  version  of  the  Maranatha  A 
compiler.  A  later  version  of  this  com¬ 
piler  is  now  sold  under  the  name  Su- 
persoft  A. 

Ada's  most  attractive  features 
show  up  only  in  large,  complicated 
programs.  Simple  routines,  such  as 
sorting  algorithms  and  finding  facto¬ 
rials,  don’t  demonstrate  Ada  well. 
That's  why  the  following  example  is 
not  an  example  of  a  program  but  is 
an  example  of  a  software  develop¬ 
ment  project. 

Here's  the  problem.  Imagine  that 
you  are  starting  a  video-game  busi¬ 
ness  and  that  your  first  product  is  to 
be  a  Draw  Poker  game  similar  to 
those  that  are  legal  in  Nevada. 

You  start  off  with  this  system  re¬ 
quirement:  The  player  puts  as  many 
coins  in  the  game  as  he  wants  to  bet, 
and  it  displays  five  playing  cards. 
(Throughout  this  article,  the  feminine 
pronouns  she  and  her  always  refer  to 
Ada.  The  neuter  pronouns  it  and  its 
refer  to  an  inanimate  object,  usually  a 
computer  or  computer  program.  The 
masculine  pronouns  he  and  his  refer 
to  a  male  or  female  programmer  or 
user.)  The  player  decides  to  hold  or 
discard  each  of  the  five  cards.  After 
the  player  has  made  his  decision,  the 
game  displays  the  cards  that  replace 
those  that  the  player  has  discarded 
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A  Draw  Poker 
program  provides  a 
vehicle  for  presenting 
some  features  of  the 
Defense  Department's 
favorite  language. 


and  evaluates  the  player's  hand.  If  the 
player  has  a  winning  hand,  it  dis¬ 
penses  some  coins  determined  by  the 
player’s  bet  and  the  value  of  his  hand. 

You  are  probably  anxious  to  see  the 
final  result,  so  let's  look  at  the  solution 
in  Listing  One,  page  86,  before  going 
through  the  step-by-step  develop¬ 
ment. 

Easy  to  Read 

Listing  One  contains  no  comments, 
but  because  Ada  is  so  easy  to  read, 
you  might  be  able  to  understand  the 
listing  even  if  you  have  never  seen 
an  Ada  program  before.  Ada  is  de¬ 
signed  to  be  easy  to  read  so  that  any 
programmer  (not  just  the  program 
author)  can  quickly  (and  correctly) 
modify  the  program.  This  reduces 
the  software  support  cost — a  major 
factor  in  software  life-cycle  costs. 

The  program  begins  by  opening  a 
new  deck  of  cards  called  the  STOCK.  It 
then  begins  a  loop  that  continues  as 
long  as  the  player  wants  to  place  a 
bet.  It  asks  the  player,  "How  many 
dollars  do  you  want  to  bet?”  and 
waits  for  him  to  enter  a  WAGER.  The 
loop  repeats  until  the  WAGER  is  zero, 
and  then  the  program  ends. 

If  the  player  places  a  bet,  the  pro¬ 
gram  shuffles  the  STOCK  and  deals 
five  cards  from  it  to  the  PLAYERS 
_ HAND .  The  PLAYERS-HAND  is  dis¬ 
played,  and  the  player  has  an  oppor¬ 
tunity  to  discard  as  many  cards  as  he 


likes.  The  program  then  deals  as 
many  cards  as  are  necessary  to  refill 
the  PLAYERS— HAND  and  displays  the 
PLAYERS-HAND  again. 

Next,  the  program  computes  the 
value  of  the  PLAYERS-HAND.  If  it  con¬ 
tains  a  ROYAL-FLUSH,  the  PAYOFF  is 
250  to  1.  If  the  PLAYERS-HAND  has  a 
STRAIGHT-FLUSH,  the  PAYOFF  is  50  to 
1.  The  more  common  hands  have 
lower  returns,  the  lowest  being  TWO 
—PAIR,  which  has  a  2  to  1  PAYOFF.  Any 
other  hand  (including  a  single  pair) 
does  not  pay  the  player  anything. 

If  the  PAYOFF  is  0,  the  program 
prints  the  message  "Sorry  you  lose.” 
Otherwise,  it  tells  the  player  what 
winning  combination  he  has  and  tells 
him  how  much  he  has  won.  (The 
player’s  winnings  are  equal  to  the 
WAGER  multiplied  by  the  PAYOFF .) 

After  the  program  has  told  the  play¬ 
er  how  much  he  has  won,  it  goes  back 
to  the  top  of  the  loop  and  asks  him 
how  much  he  wants  to  bet  this  time. 

The  Draw  Poker  program  illus¬ 
trates  the  concept  of  top-down  pro¬ 
gramming.  The  main  program  was 
written  from  the  design  specification 
without  much  regard  for  the  details 
of  how  the  program  will  actually  do 
what  it  needs  to  do.  At  this  point  in 
the  design,  it  is  not  necessary  to 
know  exactly  how  the  program  will 
get  the  player's  bet,  figure  out  if  he 
has  a  winning  hand,  and  drop  the 
right  number  of  silver  dollars.  The 
program  must  do  these  things  some¬ 
how  but  the  details  come  later. 

Notice  that  the  program  reads  very 
much  like  the  system  design  specifi¬ 
cation  does,  which  makes  it  easy  to 
see  if  it  addresses  all  the  design  re¬ 
quirements — you  simply  compare 
the  program  to  its  specification. 

An  Object-Oriented 
Language 

Draw  Poker  was  an  easy  program  to 
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write  in  Ada  because  Ada  is  an  ob¬ 
ject-oriented  language.  The  first  com¬ 
puter  languages  were  equation-ori¬ 
ented — they  were  designed  to  solve 
problems  that  involved  equations. 
Equations  of  motion,  equations  for 
solving  polynomials,  and  equations 
for  solving  matrices  are  well  known, 
but  what  is  the  equation  of  a  draw 
poker  game?  It's  true  that  people 
have  written  programs  to  play  card 
games  in  such  equation-oriented  lan¬ 
guages  as  BASIC  and  FORTRAN,  but 
some  mental  tricks  were  required  to 
translate  the  game  rules  into  equa¬ 
tions  and  the  cards  into  variables.  Ob¬ 
ject-oriented  languages  let  you  solve 
the  problem  directly  without  those 
mental  tricks — you  can  let  your 
imagination  run  wild  because  you 
don't  have  to  worry  about  practical 
details  right  away. 

A  Visual  Solution 

Here’s  how  I  imagine  a  card  game.  I 
see  a  deck  of  cards,  called  the  stock.  If 
I  were  imagining  a  bridge  game,  I 
would  imagine  two  decks  of  cards, 
one  with  a  red  design  on  the  back  and 
the  other  with  a  blue  design.  In  Ada  I 
would  express  this  concept  as  fol¬ 
lows: 

STOCK,  RED_DECK, 

BLUE_DECK :  Decks; 

This  indicates  that  STOCK,  RED-DECK, 
and  BLUE— DECK  are  three  different 
objects,  but  they  are  all  the  same  type 
of  thing.  They  are  all  decks  of  cards, 
so  I  have  defined  them  to  have  the 
type  Decks. 

Next,  I  remove  the  cellophane 
wrapper  from  a  deck  of  cards  and  dis¬ 
card  it  (along  with  the  jokers).  I  exam¬ 
ine  the  cards  and  find  they  consist  of 
52  cards  of  4  suits  and  13  ranks,  neatly 
sorted  by  suit  and  rank.  In  Ada,  I  can 
write  a  procedure  to  open  a  new  deck 
of  cards  using  the  simple  command 

Open_New(STOCK); 

The  dealer  picks  up  the  stock  and 
begins  to  shuffle  it. 

Shuffle(STOCK); 

The  dealer  then  begins  dealing 
cards.  He  deals  a  card  to  you,  one  to 
me,  and  finally  one  to  himself: 


Deal _ A_Card(YOUR_ HAND); 

Deal _ A_Card(MY _ HAND); 

Deal _ A_Card(DEALERS_HAND); 

Again  YOUR-HAND,  MY-HAND,  and 
DEALERS— HAND  are  individual  ob¬ 
jects  of  the  same  type.  In  order  to  dis¬ 
tinguish  each  of  these  objects  from 
decks  of  cards,  I  define  them  to  be  of 
type  Hands : 

YOUR-HAND,  MY-HAND, 
DEALERS-HAND :  Hands; 

Open— New ,  Shuffle,  and  Deal— A 
—Card  all  show  actions,  so  they  act  as 
verbs.  STOCK,  RED-DECK,  BLUE-DECK, 
YOUR-HAND,  MY-HAND,  and  DEALERS 
—HAND  are  the  objects  of  those  verbs.  I 
need  to  describe  those  objects  to  Ada 
before  I  can  tell  it  how  to  do  the  ac¬ 
tions  the  verbs  require. 

Type  Definitions 

What  is  a  deck  of  cards?  It  is  a  collec¬ 
tion  of  individual  cards.  In  Ada,  two 
data  types — an  array  or  a  record — 
can  represent  a  collection  of  things. 
An  array  is  used  to  represent  a  group 
of  items  of  the  same  type,  while  a  re¬ 
cord  represents  items  of  different 
types.  Because  of  the  fact  that  cards 
are  all  of  the  same  type,  it  seems  natu¬ 
ral  to  use  an  array  to  represent  a  deck 
of  cards: 

type  Decks  is  arrayll . .  52)  of  Cards; 

When  you  try  to  use  a  deck  of 
cards,  you  will  find  out  that  you  need 
to  know  a  little  more  about  decks  of 
cards,  so  this  type  definition  will 
have  to  be  improved,  but  let’s  let  it 
stand  as  it  is  for  a  moment.  It  says 
that  objects  that  are  Decks  have  the 
structure  of  an  array.  This  array  has 
52  elements,  and  each  element  is  an 
object  that  has  the  type  Cards.  I  must 
therefore  define  the  data  type  Cards. 

A  card  has  two  components — a 
suit  and  a  rank.  I  can’t  use  a  two-ele¬ 
ment  array  because  suits  and  ranks 
are  not  interchangeable,  so  they 
must  be  of  different  types.  (The  52  ele¬ 
ments  in  Decks  are  interchangeable, 
which  allows  me  to  shuffle  a  deck.) 
The  data  structure  that  holds  a  collec¬ 
tion  of  different  type  elements  is  a 
record: 

type  Cards  is 
record 


SUIT :  Suits; 

RANK :  Ranks; 
end  record; 

This  says  that  an  object  of  type  Cards 
consists  of  a  pair  of  objects,  one  ob¬ 
ject  is  called  SUIT,  and  the  other  is 
called  RANK.  The  object  SUIT  is  of 
type  Suits,  and  the  RANK  object  is  a 
Ranks  type  object. 

Now  I  have  to  define  Suits  and 
Ranks : 

type  Suits  is  (CLUBS,  DIAMONDS, 

HEARTS,  SPADES); 

type  Ranks  is  (TWO,  THREE,  FOUR, 

FIVE,  SIX,  SEVEN,  EIGHT,  NINE,  TEN, 
JACK,  QUEEN,  KING,  ACE); 

Suits  is  called  an  enumeration  type 
because  it  has  a  finite  number  of  val¬ 
ues  that  can  be  enumerated.  The 
four  possible  values  are  CLUBS,  DIA¬ 
MONDS,  hearts,  and  SPADES.  I  could 
have  listed  them  in  any  order  if  I 
were  only  going  to  play  poker  with 
this  deck  of  cards,  but  I  might  some 
day  want  to  play  bridge.  In  bridge, 
clubs  are  the  lowest  ranking  suit  and 
spades  are  the  highest.  By  listing 
them  in  the  order  above,  I  have  given 
them  their  conventional  order  and 
can  use  <  and  >  operators  to  com¬ 
pare  the  importance  of  two  objects  of 
type  Suits. 

Similarly,  if  I  had  said  type  Ranks  is 
(ACE,  TWO,  . . .),  then  the  ACE  would 
have  been  the  lowest  ranking  value. 
Defining  a  type  by  enumerating  val¬ 
ues  not  only  defines  what  the  per¬ 
missible  values  are,  but  it  also  defines 
their  order  of  relationship. 

Finally  I  define  Hands. 

type  Hands  is 

arrayll .  .  CARDS— IN—HAND) 
of  Cards; 

This  definition  looks  a  lot  like  the  def¬ 
inition  of  a  deck  of  cards,  except  I 
have  used  a  named  number  to  ex¬ 
press  the  number  of  cards  in  a  hand. 
The  definition  of  a  named  number  is: 

CARDS— IN_ HAND  :  constant  :=  5; 

Poker  hands  have  five  cards.  If  I 
were  playing  bridge,  I  would  substi¬ 
tute  the  number  13  for  5  in  the  defini¬ 
tion  of  CARDS— IN— HAND,  and  then 
everywhere  in  the  program,  the  cor¬ 
rect  number  of  cards  would  be  used. 
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I  Maranatha  A  differs  from  Ada  in 
that  only  the  first  ten  characters  of  a 
name  are  significant.  I  therefore  had 
to  use  CARDS— IN -HAND  and  CARDS 
- IN-DECK  instead  of  CARDS-IN-A 
-HAND  and  CARDS— IN— A— DECK  be¬ 
cause  Maranatha  A  would  interpret 
both  the  latter  as  CARDS-IN-A. 

When  I  started  writing  the  Shuffle 
and  Deal— A— Card  procedures,  I 
quickly  discovered  a  problem  with 
|  the  types  Decks  and  Hands.  When 
!  dealing  from  the  deck,  I  needed  to 
!  know  how  many  cards  were  left  in 
the  deck.  When  dealing  cards  to  a 
hand  to  replace  discards,  I  needed  to 
know  which  cards  had  been  played 
(that  is,  discarded).  I  therefore  had  to 
redefine  those  data  types.  This  did 
not,  however,  affect  any  of  the  rest  of 
the  program  that  I  had  already  writ¬ 
ten.  (If  I  had  been  writing  this  in  as¬ 
sembly  language  and  had  reserved 
only  52  bytes  for  each  deck  of  cards 
and  5  bytes  for  each  hand  of  cards,  I 
would  have  had  to  change  storage 
size  and  indexing  schemes  if  I  had 
changed  the  structure  of  Decks  and 
Hands.) 

The  complete  definition  of  a  deck 
of  cards  includes  the  number  of  cards 
left  in  the  deck  and  an  array  of  cards: 

type  Decks  is 
record 

CARDS_LEFT :  integer; 

FAN:  Fansll.  ,CARDS_IN_DECK); 

end  record; 

I  chose  to  call  an  array  of  cards  a 
fan: 

type  Fans  is 

arraylinteger  range  <  >) 

of  Cards; 


This  is  a  slightly  more  general  array 
definition  than  I  have  used  before. 
The  first  array  definition  I  used  was 
is  array ( 1 . .  52),  which  meant  that 
the  array  index  was  an  integer  in  the 
range  1  to  52.  It  may  surprise  you 
that  I  have  to  specify  the  index  as  an 
integer.  Other  languages  may  take 
this  for  granted  because  the  index 
can't  be  anything  other  than  an  inte¬ 
ger.  Ada  allows  you  to  use  any  dis¬ 
crete  data  type  as  an  index,  so  it  is 
possible  to  write  an  array  definition 
such  as  is  array ( CLU BS  ..  SPADES). 


(You  can’t  use  a  continuous  data  type 
as  an  index  because  it  doesn't  make 
sense  to  look  up  the  3.14159th  ele¬ 
ment  of  an  array.) 

The  general  form  of  the  array  defi¬ 
nition  uses  the  <  >  symbol,  which  is 
called  a  box  in  Ada.  The  general  form 
allows  you  to  define  the  array  with¬ 
out  forcing  you  to  specify  the  size 
j  that  it  should  be. 

The  complete  definition  of  the 
hand  of  cards  also  has  a  fan  of  cards, 
but  the  fan  in  a  poker  hand  has  5  ele¬ 
ments  instead  of  the  52  elements  in  a  | 
fan  in  a  deck. 

type  Hands  is 
record 
PLAYED : 

Statusll.  ,CARDS_IN_HAND); 
FAN  :  Fansd  .  .  CARDS_IN_HAND); 
end  record; 

type  Status  is 
arraylinteger  range  <  >) 

of  boolean; 

A  hand  of  cards  can  be  visualized 
|  as  two  five-element  arrays.  One  ar- 
[  ray  (the  FAN)  can  be  thought  of  as 
|  five  slots  that  can  each  hold  a  single 
|  card.  The  second  array  (the  PLAYED 
array)  can  be  imagined  as  five  signs 
placed  in  front  of  each  card  in  the 
FAN.  Each  sign  can  have  one  of  two 
messages  written  on  it — it  can  say 
"This  card  has  been  played”  or  "This 
card  has  not  been  played." 

Ada  also  has  a  predefined  data 
type  called  Boolean,  which  can  have 
one  of  two  values — TRUE  or  FALSE. 
This  allows  us  to  write  simple  ex¬ 
pressions  such  as  if  PLAYED  =  TRUE 
then.  .  . .  Some  languages  use  0  and 
—  1  to  represent  true  and  false,  so  the 
j  programmer  has  to  remember  that  0 
means  a  card  has  been  played. 

Verb  Definitions 

Ada  has  two  kinds  of  verbs — proce¬ 
dures  and  functions.  So  far,  I  have 
introduced  three  procedures 
|  (Open— New,  Shuffle,  and  Deal— A 
|  —Card)  and  no  functions.  I'll  talk 
about  functions  later. 

All  procedures  have  the  same  gen¬ 
eral  form  as  that  given  in  Listing 
Two,  page  86.  There  are  five 
keywords  ( procedure ,  is,  begin,  ex¬ 
ception,  and  end),  followed  by  infor¬ 
mation  specific  to  the  procedure.  For 
convenience  I’ve  called  the  locations 


I  that  contain  specific  procedure  in- 
|  formation  *1  through  *5.  The 
keyword  exception  and  information 
in  locations  *2,  *4,  and  *5  are  optional. 

Open-New  in  Listing  Three,  page 
86,  is  a  good  example  procedure  be¬ 
cause  it  uses  all  five  keywords  and 
has  information  in  all  five  locations. 
Open— New  creates  new  decks  of 
cards.  The  main  program  simply 
says  Open— Newt  RED— DECK );,  and  the 
procedure  creates  a  new  deck  of 
cards  called  RED— DECK. 

Notice  that  the  statement  ends 
with  a  semicolon.  Some  languages 
won  t  let  a  single  program  statement 
be  more  than  one  line  long,  but  Ada 
ignores  the  carriage-return/line-feed 
sequence,  so  you  can  use  them  freely 
to  make  the  program  as  readable  as 
possible.  It  does  mean,  though,  that 
you  have  to  tell  Ada  where  the  state¬ 
ment  ends  by  using  a  semicolon. 
(There  is  one  exception — a  carriage 
return  marks  the  end  of  a  comment.) 

A  procedure  name,  and  possibly  a 
formal  parameter,  go  in  the  location 
marked  *1.  Her e  formal  is  used  in  the 
sense  of  showing  the  form  rather 
than  meaning  prim  and  proper. 

In  Open— New,  for  example, 
Open— New  is  the  name  of  the  proce¬ 
dure,  and  the  object  DECK  is  a  formal 
parameter  that  stands  for  any  object 
of  type  Decks.  The  word  out  tells  Ada 
that  DECK  is  an  output  from  the 
Open— New  procedure  and  should  { 
not  be  erroneously  used  as  an  input. 
In  other  words,  Open— New  considers  j 
DECK  to  be  a  write-only  variable. 

Location  *2  is  used  to  create  some 
temporary  objects  that  will  cease  to 
exist  when  the  procedure  is  finished. 
Open— New  creates  two  such  ob- 
j  jects — the  variable  i  is  an  integer  used 
I  as  an  index,  and  CARD  is  a  blank  piece 
of  cardboard  on  which  Open— New 
prints  a  rank  and  a  suit  and  then  puts 
them  in  the  DECK.  You  can  give  a  vari-  | 
able  an  initial  value  when  you  create 
it.  I  gave  i  the  initial  value  0  but  did  j 
not  give  CARD  an  initial  value. 

The  work  gets  done  in  the  area 
j  marked  with  the  third  star.  You’ve 
probably  seen  FOR  ,  .  .  NEXT  loops  be¬ 
fore  but  not  ones  like  those  in 
Open— New.  Usually  FOR  .  .  .  NEXT 
loops  are  restricted  to  integers  or, 
perhaps,  real  numbers.  Ada  can  use 
any  discrete  variable  as  a  loop  index. 
The  variable  S  is  given  the  values 
CLUBS,  then  DIAMONDS,  then 
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HEARTS,  and  finally  SPADES,  as  the 
outer  loop  is  executed  four  times. 
Similarly  the  variable  R  takes  on  the 
values  TWO  through  ACE. 

Remember  that  objects  of  type 
Cards  have  two  components — a  SUIT 
of  type  Suits  and  a  RANK  of  type 
Ranks.  The  compound  name 
CARD. SUIT  is  "selected  component” 
notation  that  means  the  SUIT  object 
(or  component)  in  the  CARD  object. 

Each  of  the  four  times  the  program 
works  through  the  outer  (Suits)  loop,  it 
works  through  the  inner  (Ranks)  loop 
13  times.  The  index  counter  should  be 
4X13  when  all  the  looping  is  done,  so 
the  CARDS-LEFT  component  of  DECK 
should  receive  the  value  52. 

The  last  statement  in  the  *3  area  is 
an  error  check.  It  is  really  a  pair  of 
statements  as  far  as  Ada  is  con¬ 
cerned.  (Remember,  a  semicolon  is 
an  end-of-statement  marker.)  I  like  to 
put  simple  if  statements,  such  as  this 
one,  all  on  one  line  because  it  is  easier 
to  read.  Because  Ada  doesn't  care 
about  carriage  returns,  you  can  put 
multiple  statements  on  one  line  if 
you  wish. 

The  /=  sign  means  not  equal.  Pas¬ 
cal  programmers  would  probably 
prefer  to  use  <  >  for  that  purpose, 
but  the  designers  of  Ada  had  already 
used  that  symbol  for  unconstrained 
arrays  and  wanted  to  have  a  separate 
symbol  for  inequality.  It  is  an  easy  er¬ 
ror  for  compilers  to  catch,  so  all  the 
Ada  compilers  I  have  seen  will  tell 
you  exactly  what's  wrong  if  you  use 
<  >  by  mistake. 

The  purpose  of  the  if  statement  is  to 
raise  the  exception  DECK-ERROR  if 
the  final  value  of  the  index  (that  is,  the 
number  of  cards  created)  does  not 
equal  CARDS— IN— DECK.  An  exception 
is  simply  an  error  flag.  If  an  error  is 
detected,  the  statements  in  area  *4  are 
executed.  Normally  the  exception 
handler  is  skipped,  and  program 
jumps  down  to  the  end  statement. 
The  end  statement  repeats  the  proce¬ 
dure  name  at  *5  so  Ada  can  check  to 
see  if  you  accidentally  left  out  an  end 
if  or  end  loop  statement  somewhere. 
The  name  in  area  *5  must  match  the 
name  in  *1  exactly  except  that  upper¬ 
case  and  lowercase  differences  are  ig¬ 
nored.  (OPen—New  matches  Open 
—new,  for  example.) 


|  Packaging  General-Purpose  i 
Routines 

|  Listing  Four  is  an  Ada  construct 
called  a  package.  A  package  is  a  col¬ 
lection  of  data  types  and  objects  (con¬ 
stants  and  variables)  that  are  specific 
instances  of  those  data  types  and  op¬ 
erations  that  manipulate  those  ob¬ 
jects.  The  package  has  a  name 
( PLAYING-CARDS )  and  can  be  used  by 
other  programs  that  ask  for  it  by  j 
name.  It  is  divided  into  two  parts. 
The  package  specification  (Listing 
Four  A,  page  86)  explains  what  the 
objects  and  operations  are  but  does 
not  give  all  the  intricate  details  about 
the  objects  nor  explain  how  the  oper- 
I  ations  work.  The  second  part  (Listing 
Four  B,  page  88)  is  the  package  body 
and  it  contains  all  those  details. 

There  are  several  reasons  for 
breaking  the  package  in  two.  Most  of  } 
them  are  because  Ada  was  designed 
for  large  programs  that  require  more 
than  three  programmers.  Two  or 
three  programmers  can  usually  | 
work  together  easily  but  when  a  | 
program  turns  into  a  committee  pro-  j 
!  ject,  it  is  harder  for  individual  pro- 
J  grammers  to  keep  track  of  the  whole 
program.  Ada's  package  specifica¬ 
tion  allows  work  to  be  partitioned 
and  assigned  logically.  In  this  exam¬ 
ple,  it  tells  one  programmer  that  he 
j  must  write  a  procedure  called  Open 
I  —New,  which  creates  an  object  of  the 
type  Decks,  and  it  tells  the  second 
programmer  that  he  can  assume  the 
existence  of  a  procedure  called  Open 
—New  that  will  create  decks  of  cards 
for  him.  The  second  programmer 
therefore  does  not  need  to  wait  for 
the  first  programmer  to  write  Open 
j  —New  before  he  can  begin  his  part  of 
the  job. 

Another  advantage  of  Ada's  pack- 
|  age  specification  is  that  if,  for  exam-  | 
j  pie,  I  discover  a  better  way  to  shuffle 
cards,  I  can  change  the  implementa-  j 
j  tion  of  Shuffle  in  the  package  body  J 
!  without  affecting  any  other  part  of  j 
the  program.  I  can  also  be  sure  that  | 
j  no  other  programmer  has  made  use 
of  some  special  quirk  in  my  previous 
method  because  no  one  knew  how  I 
did  it  before. 

From  a  software  vendor’s  point  of 
view,  the  advantage  in  separating 
the  body  from  the  specification  is 
that  the  body  can  be  supplied  in  ob¬ 
ject  code.  The  purchaser  of  the  pack¬ 
age  then  does  not  know  how  the  | 


package  works,  so  he  can't  copy  the 
design.  If  he  wants  to  modify  it,  he 
has  to  pay  the  vendor  to  change  it. 

Dlested  Packages 

The  first  two  statements  in  the  pack-  ! 
age  body  of  PLAYING-CARDS  (file 
CARDB.ADA  in  Listing  Two)  are: 

with  CON_lO;  use  CON_IO; 

CON—IO  is  a  collection  of  console  in¬ 
put  and  output  routines.  I  could  have 
used  a  common  Ada  package  called 
TEXT—IO,  but  I  chose  not  to.  Mara- 
natha  A  doesn't  check  to  see  which  j 
package  routines  are  needed,  so  it 
loads  all  of  the  TEXT-JO  package  rou¬ 
tines  whether  it  needs  them  or  not.  I 
made  a  copy  of  TEXT—IO,  deleted  all 
the  disk  interface  routines,  and  re¬ 
named  it  CON—IO,  to  reduce  the  size 
of  the  object  code  generated. 

TEXT-JO  is  not  the  only  I/O  package 
allowed  in  Ada,  it  is  just  one  that  is 
guaranteed  to  make  your  programs 
portable.  (TEXT-IO  is  the  equivalent  of 
CP/M  BIOS — it  provides  a  universal 
I/O  interface  to  a  specific  hardware 
configuration.)  I  was  not  worried 
about  portability  because  the  final 
product  will  need  special  I/O  routines 
that  input  and  output  silver  dollars, 
which  can't  possibly  be  portable  be-  I 
cause  of  hardware  limitations. 
CON—IO  is  just  a  temporary  I/O  pack¬ 
age  that  lets  me  substitute  a  CRT  for  a 
coin  detector  and  a  dollar  dispenser. 

Maranatha  A  does  not  support  ge¬ 
neric  routines,  so  CON-IO  includes  an 
instantiated  INTEGER— IO  package 
(rather  than  the  generic  package  Ada 
would  use). 

The  with  clause  tells  Ada  that  a 
package  named  CON—IO  is  stored  in  a 
file  on  the  system  disk.  Ada  should  I 
read  this  file  to  find  out  what  data 
types,  procedures,  and  functions  ! 
have  been  defined  by  that  package.  \ 
The  use  clause  tells  Ada  that  she  can  , 
use  these  items  as  necessary  to  satisfy 
the  program  requirements. 

CON—IO  contains  a  procedure  to 
output  a  character  string.  The  form 
of  the  procedure  is: 

putC'A  text  string."); 

Because  Ada  has  been  told  to  compile 
the  Draw  Poker  program  in  the  con¬ 
text  of  the  CON—IO  package,  she 
knows  the  definition  of  put  so  I  do 
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not  need  to  define  it. 

mimicking  Other  Languages 

You  may  have  noticed  that  the  pack¬ 
age  body  of  the  PLAYING-CARDS 
package  includes  the  phrase  with  APL; 
use  APL;.  The  computer  language  APL 
is  different  from  most  other  lan¬ 
guages  because  it  has  a  function 
called  Deal  that  is  useful  in  programs 
that  play  cards.  The  Deal  function  re¬ 
turns  a  random  sequence  of  numbers 
without  repeating  any  number, 
which  makes  shuffling  cards  easy. 
Because  I  have  already  written  a 
package  to  simulate  some  APL  func¬ 
tions  (the  pertinent  part  is  given  in 
Listing  Five,  page  90),  all  I  have  to  do  is 
tell  Ada  that  the  PLAYING-CARDS 
package  needs  to  be  compiled  with 
APL,  so  all  APL  data  types,  procedures, 
and  functions  are  available. 

Unlike  Maranatha  A,  true  Ada 
would  allow  me  to  omit  the  phrase 
use  APL;.  Instead,  I  could  use  dot  nota- 
|  tion  to  tell  it  which  package  to  use — 
that  is,  I  could  Write  a  statement  such 
as 

SEQUENCE : = 

APL.Deal(CARDS_IN_DECK, 

CARDS_IN_DECK); 

This  means  that  the  variable  SE¬ 
QUENCE  gets  a  value  computed  by  a 
function  in  the  APL  package  called 
Deal.  The  sequence  (the  first  CARDS 
-IN— DECK  in  the  argument  list)  con¬ 
tains  52  numbers  in  the  range  1  to  52 
(the  second  CARDS— IN— DECK  in  the 
argument  list). 

Ada  knows  where  to  find  the  Deal 
j  function,  but  a  human  reading  the 
program  might  not.  I  wanted  to  use 
the  dot  notation  to  help  remind  me 
'  that  Deal  is  an  APL  function.  Mara¬ 
natha  A  does  not  allow  the  dot  nota¬ 
tion,  so  I  had  to  use  a  use  clause  in- 
,  stead. 

Nested  Functions 

In  the  Draw  Poker  program,  I  need  to 
know  if  two  (or  more)  cards  have  the  j 
same  rank  to  see  if  I  have  two-,  three-, 

I  or  four-of-a-kind.  If  I  couldn't  nest 
functions  (that  is,  if  I  could  do  only 
one  function  at  a  time),  I  would  have 
■  to  use  several  statements  to  find  out  if 
j  two  cards  have  the  same  rank.  For 
example,  if  I  wanted  to  find  out  if 
cards  3  and  4  in  MY— HAND  have  the 
same  rank,  I  would  have  to  do  some¬ 


thing  like 

FIRST_CARD  :  = 

Card— Number(3,  MY_HAND); 
FIRST_RANK  :  = 

Rank _ of(FIRST_CARD); 

SECOND— CARD : = 

Card— Number(4,  MY_ HAND); 
SECOND-RANK := 

Rank _ of(SECOND_CARD); 

if  FIRST-RANK  = 

SECOND-RANK  then . .  . 

It  is  clearer  to  put  it  all  in  one  state¬ 
ment,  though: 

if  Rank_of(Card_Number(3, 
MY-HAND)  =  Rank— of 
(Card— Number(4,  MY_ HAND) 
then  .  . . 

The  function  Card— Number  pulls 
card  3  (or  4)  out  of  MY— HAND,  and 
then  the  Rank— of  function  reads  the 
rank  of  that  card. 

The  Whole  Program 

The  whole  program  is  given  in  List¬ 
ing  Six,  page  91.  It  begins  with  three 
comment  lines  that  give  the  file 
name  of  the  program,  the  date  when 
it  was  written  (or  revised),  and  the 
author’s  name.  The  context  clauses 
tell  Ada  that  the  Draw— Poker  proce¬ 
dure  should  be  compiled  in  the  con¬ 
text  of  the  CON—IO  and 
PLAYING-CARDS  packages,  so  all  the 
procedures,  functions,  and  data 
types  in  those  packages  are  defined 
and  usable. 


Draw— Poker  requires  a  special 
data  type,  called  Values.  The  value  of 
j  a  poker  hand  can  be  NOTHING  up  to 
ROYAL— FLUSH,  so  this  type  definition 
enumerates  all  the  possible  values  in 
ascending  order  of  importance. 

Draw— Poker  also  requires  five 
variables  (objects)— a  STOCK ;  one 
PLAYERS-HAND ;  a  WAGER  and  a  PAY- 
j  OFF,  which  are  both  integers;  and  a 
|  VALUE,  which  can  have  any  of  the 
values  NOTHING  through  ROYAL 
'  - FLUSH . 

Next,  the  procedure  put  is  defined 
for  what  seems  to  be  the  millionth 
I  time.  Procedures  that  have  more 
than  one  meaning  are  called  over- 
|  loaded  procedures.  CON—IO  has  a  put 
|  for  individual  characters,  a  put  for 
|  character  strings,  a  put  for  integers,  a 
I  put  for  floating-point  numbers,  and  a 
put  for  Boolean  values.  Listing  Four 
contains  a  put  for  suits,  a  put  for 
I  ranks,  a  put  for  cards,  and  a  put  for 
hands.  Finally,  I  now  have  a  put  for 
values  of  poker  hands. 

If  Ada  wasn't  smart  enough  to  fig¬ 
ure  out  which  put  to  use,  I  would 
have  to  make  up  separate  names  to 
output  integers,  floating-point  num¬ 
bers,  characters,  strings,  Booleans, 
suits,  ranks,  cards,  hands,  and  values. 
Then  I  would  have  to  remember 
which  name  I  used  for  each  data 
type.  Because  Ada  allows  me  to  reuse 
names,  though,  all  I  have  to  remem¬ 
ber  is  that  put  outputs  anything,  and 
Ada  has  to  remember  how  to  output 
each  object. 

If  an  external  package  name  is  giv¬ 
en  (for  example,  APL. Deal),  Ada  will 
look  only  in  that  package  for  the  pro¬ 
cedure.  If  no  external  package  name 
is  given,  she  will  look  for  a  definition 
of  the  procedure  in  the  declarative 
region  (the  area  marked  *2  in  Listing 
Two). 

If  Ada  can’t  find  the  procedure  in 
its  list  of  procedures  currently  de¬ 
fined  by  the  program,  and  there  is  a 
use  clause,  she  will  look  for  the  pro- 
i  cedure  in  the  "used  package."  If 
there  are  two  used  packages  and 
both  have  a  procedure  with  the  cor¬ 
rect  name  and  formal  parameters, 
then  Ada  won’t  know  which  one  to 
use.  She  will  explain  her  dilemma 
during  the  compilation  of  the  pro¬ 
gram  (rather  than  just  picking  one  at 
random),  and  you  will  have  to  pro¬ 
vide  an  external  package  name  to  let 
her  know  which  procedure  to  use. 
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Separate  Compilation 

The  Draw— Poker  procedure  needs  tc 
compute  the  value  of  a  hand.  I  chose 
to  compile  this  separately  so  I  wrote 
a  "body  stub”  where  the  function 
would  normally  go.  The  body  stub  is: 

function  Value_of(HAND :  Hands) 
return  Values  is  separate; 

This  tells  Ada  that  a  function  called  Va¬ 
lue— of  operates  on  a  HAND  and  re¬ 
turns  an  object  of  type  Values  (that  is, 
NOTHING  through  ROYAL-FLUSH)  and 
that  this  function  will  be  compiled 
separately.  (See  Listing  Seven,  page  91.) 

Compiling  Value— of  separately  has 
three  advantages.  First,  it  divides  the 
labor  effectively.  Sometimes  adding 
more  programmers  to  a  project 
slows  progress  because  each  pro¬ 
grammer  has  to  know  how  another1 
programmer  has  written  part  of  the' 
program  before  starting  his  own 
part.  Separate  compilation  defines 
the  interfaces  between  program 
modules  clearly  and  allows  all  the 
programmers  to  work  in  parallel, 
thus  shortening  development  time. 

Second,  separate  compilation 
makes  it  easier  to  test  procedures  and 
functions.  If  the  Value— of  function 
were  an  inseparable  part  of  the 
Draw— Poker  procedure,  think  how 
long  it  would  take  you  to  find  out  if 
Value— of  recognizes  when  a  hand 
contains  a  ROYAL— FLUSH.  Because  Va- 
lue—of  is  compiled  separately, 
though,  you  can  write  a  program 
that  tests  Value— of  by  asking  what 
five  cards  are  in  the  hand  and  then 
calling  Value— of  to  see  if  it  figures  out 
the  value  of  the  hand  correctly. 

Third,  separate  compilation  makes 
it  easy  to  fix  mistakes.  As  a  matter  of 
fact,  Value— of  does  have  a  mistake.  I 
don't  play  poker,  so  it  wasn’t  until  I 
showed  the  program  in  class  that  I 
found  out  aces  can  be  high  or  low. 
Value— of  doesn’t  realize  that  TWO, 
THREE,  FOUR,  FIVE,  ACE  is  really  the 
same  as  ONE,  TWO,  THREE,  FOUR,  FIVE 
and  should  be  considered  to  be  a 
STRAIGHT.  Because  Value— of  is  sepa¬ 
rate  from  Draw— Poker,  it  was  easily 
fixed,  recompiled,  and  relinked  to 
the  other  modules.  (See  Listing  Eight, 
page  92,  for  corrections.) 

Separate  compilation  and  inclusion 


of  packages  makes  it  difficult  to  com¬ 
pare  Ada  compiler  speeds  with  other 
language  compilers.  It’s  fair  to  com¬ 
pare  one  Ada  compiler  to  another  on 
the  basis  of  number  of  lines  compiled 
per  minute,  but  it  isn’t  fair  to  compare 
Ada  lines  per  minute  to  Pascal  lines 
per  minute  (for  example)  because  a 
Pascal  compiler  has  to  compile  the 
whole  program  every  time  a  change  is 
made,  while  Ada  just  has  to  compile 
the  part  that  has  been  changed.  For  a 
very  long  Ada  program  that  has  been 
properly  divided  into  many  modules, 
it  might  make  more  sense  to  measure 
the  linker  speed  than  the  compiler 
speed. 

The  Final  Product 

Hemember  that  this  case  study  in¬ 
volved  making  a  video  Draw  Poker 
game  that  would  be  sold  for  profit. 
The  program  described  here  has  no 
graphics,  doesn’t  accept  coins,  and 
the  user  interface  is  through  a  termi¬ 
nal.  The  product,  as  it  now  stands, 
isn’t  commercially  viable. 

If  I  were  going  to  market  the  prod¬ 
uct,  I  would  get  a  mechanical  engi¬ 
neer  to  design  a  coin  detector  that 
could  reject  slugs  and  count  the  num¬ 
ber  of  genuine  silver  dollars  entered. 
Meanwhile,  I  would  write  another 
procedure  get  so  that  get(WAGER); 
would  accept  input  from  the  coin  de¬ 
tector.  I  would  put  this  procedure  in 
a  package  called  HARDWARE— IO.  I 
would  then  write  a  simple  program 
based  on  this  sequence  of  statements: 

loop 

HARDWARE_IO.get(WAGER 

CON_IO.put(  WAGER); 

end  loop; 

I  could  then  drop  coins  in  the  slot  and 
see  if  the  CRT  screen  displayed  the 
correct  number  of  dollars. 

The  mechanical  engineer  would 
also  design  a  dollar  dispenser,  which 
would  require  a  HARDWARE— IO. put 
routine.  When  the  dollar  dispenser 
and  put  procedure  were  finished,  I 
could  test  them  using  a  program  con¬ 
taining  these  statements: 

loop 

CON_IO.put("How  much  should  I 

pay?”); 

CON_IO.get(  WINNINGS); 

HARDWARE_IO.put(  WINNINGS); 

end  loop; 


Simultaneously  an  electrical  engi¬ 
neer  would  work  on  a  graphics  in¬ 
terface  that  could  display  playing 
cards.  It  would  need  a  HARDWARE 
—IO.put  procedure  for  Cards,  which 
would  replace  the  PLAYING— 
CARD.put  procedure. 

From  Host  to  Target 

I  think  you  can  see  how  Ada’s  modu¬ 
lar  nature  makes  it  easy  to  put  a  sys¬ 
tem  together.  After  you  have  tested 
each  interface,  you  can  integrate  it 
into  the  Draw  Poker  program  simply 
by  replacing  the  CON—IO  procedure 
with  the  corresponding  HARDWARE 
— IO  procedure. 

Imagine  how  difficult  it  would  be 
to  get  a  working  system  if  the  Draw 
Poker  program  (including  HARDWARE 
-IO,  PLAYING-CARDS,  APL,  and  Val¬ 
ue— of)  were  one  long  spaghetti-code 
program  written  by  a  team  of  pro¬ 
grammers.  Someone  would  always 
be  waiting  for  someone  else  to  finish 
something,  and  the  program 
couldn't  be  tested  until  all  the  hard¬ 
ware  was  finished. 

Ada's  modular  form  lets  you  devel¬ 
op  embedded  system  software  on  a 
host  computer  (even  a  micro)  using 
simulated  I/O  drivers.  You  can  devel¬ 
op  test  procedures  using  these  simu¬ 
lated  drivers,  which  you  can  then  re¬ 
place  by  real  drivers  in  any  order. 
You  can  test  the  real  drivers  quickly 
using  the  methods  you  used  to  test 
the  simulated  drivers.  Integration 
should  be  a  trivial  task. 

In  the  ideal  case  (that  is,  with  un¬ 
limited  manpower  and  resources), 
the  time  taken  to  complete  the  pro¬ 
ject  is  not  much  longer  than  the  time 
taken  to  complete  the  longest  task. 
The  concept  of  a  critical  path  (where 
one  task  cannot  begin  until  another 
is  finished)  disappears. 

Micro  Limitations 

Maranatha  A  is  not  a  true  Ada  com¬ 
piler.  It  lacks  overloaded  operators, 
generics,  and  tasking,  so  you  can't 
use  it  to  develop  programs  that  need 
these  features.  CP/M-80  systems  typi¬ 
cally  have  about  48K  to  57K  of  usable 
program  memory,  so  that  limits  the 
size  of  the  program  you  can  actually 
run  on  the  micro  host.  Remember 
that  Ada’s  modular  form  lets  you 
compile  and  test  modules  separately 
so  you  could  test  all  the  pieces  of  a 
huge  program  even  if  you  couldn’t 
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run  the  whole  program  on  the  host. 

I  didn’t  feel  hampered  by  Mara- 
natha  A.  When  I  was  beta-testing  it,  I 
didn’t  bother  to  read  the  whole 
Maranatha  A  Language  Reference 
Manual  (LRM).  I  read  just  the  Ada 
LRM  and  assumed  Maranatha  A 
would  do  what  Ada  does.  I  referred 
to  the  Maranatha  manual  only  when 
Maranatha  A  wouldn't  do  something 
that  Ada  should  do. 

Maranatha  A  did  not  then  have 
overloaded  operators  (it  may  have 
them  by  the  time  you  read  this),  so  I 
couldn’t  use  the  plus  sign  to  add 
cards  to  a  hand.  I  would  have  liked  to 
have  been  able  to  write 

PLAYERS—HAND  :  = 

PLAYERS—HAND 
+  Top_of(STOCK); 

but  as  I  couldn’t,  I  used 


Deal _ A_Card(PLAYERS_HAND, 

STOCK); 

instead. 

I  wanted  to  use  dot  notation  to  em¬ 
phasize  that  the  Deal  function  is  in 
the  API  package,  but  I  suppose  that  I 
could  have  just  as  easily  used  a  com¬ 
ment  to  do  that. 

Maranatha  A  doesn’t  have  an  IM¬ 
AGE  attribute,  which  made  the  put 
procedures  for  Suits  and  Ranks  more 
complicated  than  they  need  be.  For 
enumeration  types  with  4  to  13  val¬ 
ues,  it  isn’t  too  bad  to  have  to  use  a 
case  statement  as  I  did,  but  if  the  enu¬ 
meration  type  had  50  or  100  values,  it 
could  be  annoying  to  have  to  output 
values  in  that  way. 

The  extraneous  semicolon  in  sepa¬ 
rate  (Draw— Poker);  confused  me  for 
a  while,  but  I  think  that  error  has 
been  removed  from  the  version  that 
Supersoft  is  now  selling.  The  excep¬ 
tion  handler  also  contained  a  bug, 
which  forced  me  to  include  the 


guard  in  the  expression: 

when  DECK_ERROR  I 

CONSTRAINT-ERROR  =  > 
raise  DECK-ERROR; 

If  not  for  the  bug  I  could  simply  have 
written  raise  DECK— ERROR;.  I  think 
that  bug  has  also  been  fixed  in  Super- 
soft’s  version. 

It  is  a  minor  inconvenience  that 
only  the  first  ten  characters  of  a 
name  are  significant.  I  lived  for  years 
with  a  FORTRAN  language  that  per¬ 
mitted  only  six-character  names,  and 
it  was  picky  about  what  the  first  let¬ 
ter  was. 

Now  that  I  have  a  real  Ada  compiler 
with  generics  and  tasking,  I  realize 
how  valuable  they  are,  but  when  I 
wrote  the  Draw  Poker  program  I 
didn’t  know  what  I  was  missing,  so  it 
didn’t  bother  me  much.  The  Draw 
Poker  program  didn’t  need  them,  any¬ 
way. 

The  worst  problem  with  my  beta- 
test  version  is  that  a  missing  semi¬ 
colon  causes  the  compiler  to  crash. 
This  was  a  real  nuisance  at  first  be¬ 
cause  I  did  not  know  any  Pascal  be¬ 
fore  I  learned  Ada,  so  I  wasn’t  in  the 
habit  of  ending  statements  with  semi¬ 
colons,  and  it  crashed  often. 

The  built-in  random-number  gen¬ 
erator  is  not  standard  with  Ada,  and 
it  was  a  handy  function  to  have  for 
Draw  Poker.  If  I  ever  want  to  run  this 
program  on  a  validated  Ada  compil¬ 
er,  I  will  have  to  write  a  random- 
number  generator  to  replace  RND  in 
the  API  package. 

Using  a  micro  to  develop  Ada  pro¬ 
grams  isn’t  ideal.  It  would  be  better 
to  use  a  validated  Ada  compiler  on  a 
mainframe  computer,  but  if  you 
don’t  have  $30,000  to  spend  on  a  com¬ 
piler  (and  a  VAX-780  to  run  it  on),  then 
Maranatha  A  is  a  good  alternative. 
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Overview  of  the 
DOD  Ada 

Software  Repository 


A  repository  of  Ada  programs, 
Ada  software  components, 
educational  material,  and 
Ada-oriented  information  has  been 
established  on  the  SIMTEL20  host 
computer  on  the  Defense  Data  Net¬ 
work  (DDN).  This  repository,  estab¬ 
lished  on  November  26, 1984,  is  acces¬ 
sible  to  thousands  of  host  computers 
on  the  more  than  80  subnetworks 
that  comprise  the  DDN.  Access  to  this 
repository  will  be  provided  to  the 
Ada  community  at  large  in  the  near 
future;  with  validated  Ada  compilers 
becoming  available  for  popular  mi¬ 
crocomputers,  this  large  base  of  pub¬ 
lic-domain  Ada  software  and  infor¬ 
mation  will  be  a  good  way  to 
introduce  yourself  to  Ada  and  learn 
more  about  it. 

The  repository  on  SIMTEL20  serves 
two  purposes:  to  promote  the  ex¬ 
change  and  use  of  Ada  programs  and 
tools  (including  reusable  Ada  soft¬ 
ware  components)  and  to  promote 
Ada  education  by  providing  several 
working  examples  of  programs  in 
source  form  for  people  to  study  and 
modify.  It  also  contains  other  useful 
information. 

The  repository  is  divided  into  sever¬ 
al  subdirectories  by  topic.  Table  1, 
page  61,  shows  the  general  topic  ar¬ 
eas,  the  subdirectory  names,  and  the 
sizes  of  the  documentation  and 
source-code  files  in  each  subdirec¬ 
tory.  Today  the  DOD  Ada  Software 
Repository  contains  more  300  files,  to¬ 
taling  more  than  20  megabytes  in  size. 


Bichard  Conn,  6300  Roundrock,  Apt. 
3008,  Plano,  TX  75023 


by  Richard  Conn 
With  Ada  becoming 
available  for  micros , 
this  base  of  public- 
domain  software  is  a 
good  way  to  learn. 
The  Ada  Software  Re¬ 
pository  is  over  20 
megabytes  in  size. 


Tour  of  the  Ada  Repository 

In  the  following  paragraphs,  I  will 
take  you  on  a  brief  tour  of  the  Ada 
Software  Repository.  I  will  cover 
only  selected  points  of  interest  and 
follow  Table  1. 

The  first  topic  is  "General  Informa¬ 
tion,"  under  which  is  the  Education 
subdirectory.  A  glossary  of  Ada 
terms,  a  listing  of  Ada  and  Ada-relat¬ 
ed  textbooks,  a  bibliography  of  Ada 
textbooks  (which  includes  comments 
on  the  books  and  their  audiences),  an 
example  of  object-oriented  design, 
productivity  data  (which  presents 
data  from  live  projects  coded  in  Ada), 
and  an  example  of  how  Ada  can  in¬ 
terface  with  other  languages  are 
some  of  the  items  of  information 
available  here. 

The  General  subdirectory  contains 
many  tidbits  of  information,  ranging 
from  databases  on  the  repository  to 
tutorials  on  how  to  transfer  files  on 
the  DDN. 

The  Pointers  subdirectory  contains 
information  on  where  to  look  for 
sources  of  information  and  Ada  soft¬ 
ware  outside  the  repository.  The 


large  collection  of  Ada  compiler 
benchmarks  on  USC’s  ECLB  host  com¬ 
puter,  the  address  of  the  DOD  Soft¬ 
ware  Engineering  Institute,  the  INFO- 
ADA  database  on  ECLB  (which 
provides  listings  of  conferences  and 
current  events),  and  a  list  of  all  vali¬ 
dated  Ada  compilers  are  some  of  the 
items  contained  or  referenced  in  this 
subdirectory. 

The  second  topic  is  "Reusable 
Components."  Reusability  of  soft¬ 
ware  without  the  need  for  a  com¬ 
plete  redesign  is  supported  by  Ada, 
and  subdirectories  such  as  Compo¬ 
nents,  Math,  and  Virterm  were  estab¬ 
lished  to  contain  software  compo¬ 
nents  that  may  be  reused  time  and 
again  in  various  applications. 

Three  dynamic  string  packages,  a 
generic  quick-sort,  two  linked-list 
packages,  a  Unix-style  ARGC/ARGV 
parser,  and  a  command-line  inter¬ 
preter  are  some  of  the  items  found  in 
Components.  Math  includes  a  math 
library  of  log,  trig,  exponential,  and 
other  functions  and  libraries  of  ma¬ 
trix-,  bit-,  and  set-manipulation  rou¬ 
tines.  Virterm  contains  virtual  termi¬ 
nal  packages,  including  a  Curses 
package  modeled  after  the  Curses  of 
Berkeley  Unix. 

The  third  topic,  "Software  Devel¬ 
opment  Aids,”  includes  toolsets  for 
compilation  order,  Ada  style,  and 
metrics  analysis  of  Ada  programs; 
software  project-management  tools; 
Ada  cross-reference  programs;  three 
Ada  pretty  printers;  and  a  library  file 
manipulation  tool  (Pager,  which 
groups  smaller  files  into  larger  li¬ 
brary  files). 
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The  communications  software  in¬ 
cludes  an  implementation  of  the  TCP/ 
IP  communications  protocol  (the  DOD 
standard)  and  file  transfer  (FTP),  mail 
handling  (SMTP),  and  host-to-host  (TEL¬ 
NET)  communications  programs. 

For  graphics  fans,  the  Graphical 
Kernel  System  (GKS)  has  been  imple¬ 
mented  in  almost  2  megabytes  of  Ada 
code. 

Finally  a  library  of  Ada  compiler 
benchmarks  (different  from  the  one 
on  ECLB),  two  text-file  editors,  a  spell¬ 
ing  checker/corrector,  an  LALR(l) 
grammar  for  Ada  that  may  be  pro¬ 
cessed  under  the  LEX/YACC  tools  of 
Unix,  an  EMACS  front-end  for  the  de¬ 
velopment  of  Ada  software,  and  a 
program  that  can  configure  a  TVI970 
terminal  are  some  of  the  items  found 
under  the  "Other  Topics"  category. 

How  to  Get  Software 

If  you  access  a  computer  on  the  DDN 
(on  the  ARPANET,  MILNET,  or  any 
other  DDN  subnet),  you  may  subscribe 
to  the  Ada  Software  Repository  mail¬ 
ing  list  by  sending  an  electronic  mail 
message  to  ADA-SW-REQUEST@SIM- 
TEL20.  In  response  to  your  message, 
you  will  be  placed  on  the  ADA-SW 
mailing  list,  over  which  notices  of 
changes,  updates,  bugs,  and  other  re¬ 
pository-oriented  information  are  dis¬ 
tributed.  You  will  also  receive  a  wel¬ 
come  message  that  details  how  to 
access  the  repository  from  a  DDN  host 
computer. 

If  you  do  not  have  access  to  a  DDN 
host  computer,  a  nine-track  magtape 
distribution  facility  is  being  estab¬ 
lished  from  which  any  member  of 
the  Ada  community  will  be  able  to 
acquire  a  tape  of  the  entire  Ada  Soft¬ 
ware  Repository.  Also,  submission  of 
some  or  all  of  the  software  and  docu¬ 
mentation  in  the  repository  to  the 
public-domain  PC-BLUE  library  is  be¬ 
ing  considered.  /DDJ  will  announce 
these  public-access  opportunies  when 
they  become  official. — edj 

Limited  DDN  access  is  available  to 
members  of  the  Ada  community  with 
approval  of  the  Ada  Information 
Clearinghouse.  A  public  account 
sponsored  by  the  AdalC  on  a  DDN  host 
computer  at  the  University  of  South¬ 
ern  California  (USC-ECLB)  host  com¬ 
puter  provides  access  to  current  in¬ 
formation  on  the  Ada  initiative  and 
the  ability  to  link  with  the  SIMTEL20 
host  computer,  scan  the  subdirector¬ 


ies  of  the  DOD  Ada  Software  Reposi¬ 
tory  and  transfer  files  from  the  re¬ 
pository.  These  files  can  then  be 
viewed  on  the  ECLB  computer  or 
transferred  to  a  PC.  To  obtain  the  tele¬ 
phone  number  and  access  codes  re¬ 
quired  to  access  the  ECLB  ADA-INFOR- 
MATION  account  maintained  by  the 
AdalC,  send  conventional  mail  or 
telephone: 

Ada  Information  Clearinghouse 
IIT  Research  Institute 
Ada  Joint  Program  Office 
Room  3D139  (400  AN) 

The  Pentagon 
Washington,  DC  20301 
(703)  685-1477 


The  DOD  Ada  Software  Repository 
is  supported  by  the  U.S.  Department 
of  Defense,  U.S.  Army  White  Sands 
Missile  Range. 
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242,840 

977,501 

273,662 

2,936,600 

Graphics  and  Display  Tools 

FORMGEN 

305,823 

632,772 

GKS 

322,595 

1 ,991 ,575 

MENU 

367,593 

450,093 

996,01 1 

3,074,440 

Other  Topics 

BENCHMARKS 

73,733 

302,163 

EDITORS 

113,372 

144,099 

EXTERNAL-TOOLS 

25,043 

80,520 

SPELLER 

387,012 

1 ,777,350 

STARTER-KIT 

18,409 

83,903 

TOOLS 

59,876 

323,340 

677,445 

2,711,375 

TOTAL 

5,014,011 

15,037,090 

Table  1 
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ARTICLES 


Data  Abstraction 
with  Modula-2 


Introduction 

his  short  article  is  intended  to 
illustrate  the  concept  of  data 
abstraction  via  the  use  of  the 
programming  language  Modula-2. 
We  accomplish  this  by  presenting  a 
sample  program  that  may  prove  use¬ 
ful  in  its  own  right. 

We  must  understand  the  notion  of 
data  abstraction  before  we  can  ap¬ 
preciate  the  utility  of  the  methods 
presented  here.  Let  us  define  a  prior¬ 
ity  queue  as  a  collection  of  data, 
along  with  two  operations,  add  and 
fetch,  which  maintain  that  data  on  a 
smallest-item-first  (or  largest-item- 
first)  basis. 

Suppose  we  have  a  magic  jar  that 
we  are  free  to  add  or  remove  data 
items  to  or  from  any  time  we  please. 
The  data  we  add  to  the  jar  is  random¬ 
ly  ordered.  When  we  reach  into  the 
jar  and  grab  a  data  item,  we  are  guar¬ 
anteed  that  the  item  will  be  the 
smallest  data  item  in  the  jar.  It  may 
not  be  the  smallest  that  we  have  seen 
because  we  have  no  idea  what  data 
has  already  been  removed  from  or 
added  to  the  jar.  Our  magic  jar  is  act¬ 
ing  as  a  priority  queue. 

Of  major  importance  is  the  fact  that 
we  have  no  knowledge  of  the  mecha¬ 
nism  of  the  jar.  Internally  we  do  not 
know  if  the  jar  operates  by  maintain¬ 
ing  a  computer  sorting  procedure 
that  is  in  constant  operation  or  by 
keeping  an  especially  industrious  col¬ 
lection  of  elves.  Nor  do  we  care. 

We  are  interested  only  in  the  ac¬ 
tion  of  the  jar  itself,  not  in  its  internal 
mechanism.  We  may  regard  the  jar 
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The  ability  to  sepa¬ 
rate  the  definition  of 
a  data  structure  from 
the  details  of  imple¬ 
mentation  is 
important. 


as  an  abstraction  of  a  priority  queue. 

We  should  be  aware  that  the  jar 
has  many  uses.  We  can  use  it  as  a 
sorter,  for  example,  by  dumping  a 
whole  collection  of  numbers  into  it 
and  then  fetching  them  one  at  a  time. 

Languages  to  Support  Data 
Abstraction 

Almost  any  computer  language  in  use 
today  will  allow  us  to  write  a  comput¬ 
er  program  that  will  implement  a  pri¬ 
ority  queue  either  by  using  a  static  ar¬ 
ray  or  by  creating  a  dynamically 
allocated  linked  list.  The  problem 
with  most  of  these  languages  is  that 
the  method  of  handling  the  priority 
queue  is  intimately  wedded  to  the  ab¬ 
straction  of  the  queue.  There  is  no 
convenient  method  of  making  a  pri¬ 
ority  queue  available  to  a  user  with¬ 
out  also  making  the  unnecessary  de¬ 
tails  of  the  implementation  available. 
A  few  languages,  or  more  commonly 
language  implementations,  represent 
exceptions. 

The  ability  to  separate  the  defini¬ 
tion  of  a  data  structure  from  the  de¬ 
tails  of  implementation  is  an  impor¬ 
tant  one.  This  ability  is  present  in 
several  modern  languages  and  in 


particular  is  present  in  the  language 
Modula-2,  which  has  recently  re¬ 
ceived  considerable  attention. 

An  Example 

Modular  design  charts  as  presented 
in  Software  Engineering  with  Modula- 
2  and  Ada  by  Sincovec  and  Wiener1 
represent  a  natural  expression  of  ab¬ 
stract  solutions  to  software  prob¬ 
lems.  It  follows  that  modular  design 
charts  are  particularly  well  suited 
for  use  in  projects  employing  pro¬ 
gramming  languages  that  allow  high 
levels  of  abstraction.  Figure  1,  page 
63,  illustrates  a  modular  design  chart 
of  a  small  software  system. 

The  system  represented  will  be 
used  to  generate  random  numbers 
and  sort  them  using  a  priority  queue. 
By  examining  the  chart,  we  see  that 
the  system  will  consist  of  a  module  to 
generate  the  pseudorandom  num¬ 
bers;  a  module  to  provide  the  means 
for  handling  our  abstract  priority 
queue;  and  a  program,  Sorter,  to  tie 
together  the  functions  supplied  by 
our  small  "library.” 

Note  that  the  software  bus  details 
the  pathways  of  communication  re¬ 
quired  by  the  separate  modules  of 
our  system.  The  software  bus  is  analo¬ 
gous  to  a  hardware  communications 
bus  found  on  modern  computers. 

In  the  design  of  our  chart,  we  have 
been  careful  to  minimize  the  com¬ 
munication  required  between  the 
modules.  By  minimizing  communi¬ 
cation,  we  have  contributed  greatly 
to  the  dependability  and  maintain¬ 
ability  of  our  system. 

We  present  a  Modula-2  program 
that  follows  the  scheme  of  our  modu¬ 
lar  design  chart.  Our  program  will 
generate  100  pseudorandom  num- 
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bers  and  place  them  each  into  a  pri¬ 
ority  queue.  After  the  queue  is  built, 
we  will  remove  the  numbers  from 
the  structure  and  print  them  one  at  a 
time.  The  definition  of  a  priority 
queue  assures  us  that  the  numbers 
will  be  in  ascending  (or  perhaps  de¬ 
scending)  order.  The  step  from  the 
modular  design  chart  to  actual  Mo¬ 
dula-2  code  is  often  a  surprisingly 
small  one. 

In  this  example  program,  we  have 
‘'imported”  the  functions  that  are  de¬ 
signed  to  deal  with  the  priority 
queue.  We  consider  that  this  pro¬ 
gram  is  a  client  of  MODULE  Queues, 
which  supplies  required  queue-han¬ 
dling  functions.  When  we  write  the 
program,  we  are  entirely  ignorant  of 
the  method  used  to  implement  the 
priority  queue.  We  can  make  the 
same  comments  about  the  random 
number  generator  randuf  )  and  its 
parent  module  RandomNumbers. 
We  have  no  idea  at  all  how  it  works, 
just  that  it  does.  Notice  that  the  pro¬ 
gram  is  a  direct  reflection  of  the  ab¬ 
stract  design. 

The  two  modules  Random- 
Numbers  and  PriorityQueue  provide 
procedures  that  support  the  MODULE 
Sorter  (Listing  One,  page  94).  The  fol¬ 
lowing  section  provides  a  rather 
complete  description  of  the  informa¬ 
tion  a  programmer  needs  to  make 
use  of  these  two  modules. 

The  Definition  Modules 

Let  us  first  turn  our  attention  to  DEFI¬ 
NITION  MODULE  RandomNumbers 
(Listing  Two,  page  94).  In  this  module, 
we  find  that  a  function  procedure 
named  randu  is  exported  (made  visi¬ 
ble)  so  that  other  modules  can  use  it. 
We  see  that  the  function  procedure 
randu  does  not  require  any  parame¬ 
ters  and  that  the  result  type  is  INTE¬ 
GER.  We  have  been  able  to  glean  all 
this  information  by  examining  the 
definition  module  alone.  It  was  not 
necessary  to  have  any  knowledge  at 
all  of  how  the  random  number  gen¬ 
erator  does  its  job.  The  module  Ran¬ 
domNumbers  is  able  to  provide  ser¬ 
vices  to  its  clients  while  masking 
(protecting!)  its  own  internal  func¬ 
tions  from  those  clients. 

In  a  like  manner,  DEFINITION  MOD¬ 
ULE  Queues  provides  us  with  all  the 
tools  we  need  to  utilize  priority 
queues  without  providing  any  access 
to  the  internal  workings  of  those 


queues.  This  module  exports  the 
type  PriorityQueue  so  that  user  pro¬ 
grams  may  declare  compatible  ob¬ 
jects  of  this  type.  It  also  provides  a 
means  of  initializing  such  queues 
(PROCEDURE  InitPriorityQueue)  and 
for  adding  items  to  a  queue  or  fetch¬ 
ing  an  item  from  a  queue.  There  is 
also  a  function  procedure  that  can 
determine  if  a  given  queue  is  empty. 
(In  a  production  environment,  MOD¬ 
ULE  Queues  would  probably  contain 
additional  queue-handling  proce¬ 
dures.  For  purposes  of  illustration, 
this  subset  should  be  sufficient.) 

These  procedures  provide  us  with 
a  system  for  manipulating  priority 
queues.  MODULE  Sorter  is  an  example 
of  how  we  can  use  the  objects  from 
RandomNumbers  and  Queues  to 
make  a  useful  program. 

Please  note  that  in  most  recent  ver¬ 
sions  of  Modula-2,  the  EXPORT  lists 
are  not  required.  In  these  newer  ver¬ 
sions,  the  declarations  themselves 
serve  as  the  EXPORT  list  for  the  defini¬ 
tion  modules2.  In  MacModula-2  (from 
Modula  Corporation),  the  EXPORT 
lists  are  required. 

Compiling  the  Programs 

Modula-2  allows  for  the  compilation 
of  both  the  definition  modules  and 
the  client  program  Sorter  without 
concern  for  the  details  of  implemen¬ 
tation.  This  is  important  because  it  al¬ 


lows  us  to  detect  any  errors  in  the 
design  of  the  interface  of  our  system. 
For  instance,  if  Sorter  incorrectly 
provides  us  with  the  wrong  number 
of  parameters  to  one  of  the  imported 
procedures,  the  compiler  will  supply 
us  with  ample  warning.  This  feature 
is  in  contrast  to  such  languages  as  C, 
which  would  not  flag  such  an  error. 

The  compiler  is  sufficiently  sophis¬ 
ticated  to  allow  explicit  type  check¬ 
ing  across  the  boundaries  of  sepa¬ 
rately  compiled  files.  It  is 
commonplace  to  compile  each  of  the 
definition  modules  individually  and 
to  provide  them  as  libraries  for  the 
use  of  the  main  program. 

At  this  point,  we  compiled  each  of 
the  above-listed  programs  under 
MacModula-2  on  a  512K  Macintosh.  It 
is  necessary  that  both  definition 
modules  be  compiled  before  MODULE 
Sorter  because  Sorter  is  a  client  of 
these  modules.  The  order  of  compila¬ 
tion  of  the  definition  modules  is  arbi¬ 
trary  because  neither  is  dependent 
upon  the  other. 

Implementation  Issues 

In  this  section  we  provide  implemen¬ 
tation  modules  for  each  of  the  above- 
defined  modules  RandomNumbers 
and  Queues. 

A  library  module  consists  of  an  in¬ 
terface  (definition  module)  and  an 
implementation  (implementation 


Figure  l 
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(Continued  from  page  63) 


module).  After  compiling  the  imple¬ 
mentation  modules,  we  have  com¬ 
plete  library  modules  that  are  avail¬ 
able  to  any  client.  In  production 
environments  it  is  important  that 
system  maintenance  be  convenient. 
Modula-2 's  library  concept  allows 
for  this  needed  convenience. 

Now  we  will  discuss  the  implemen¬ 
tation  components  of  our  small  li¬ 
brary  and  illustrate  the  exceptional 
ease  of  maintenance  afforded  by  Mo¬ 
dula-2. 

Note  that  the  procedures  and  mod¬ 
ules  listed  in  Listings  Three  and  Four 
(page  95)  that  are  not  discussed  are 
part  of  a  standard  library  of  inter¬ 
faces  provided  with  the  MacModula- 
2  system.  It  is  necessary  to  import  the 
utilities  Allocate  and  Deallocate  from 
storage  in  order  to  use  the  standard 
procedures  New  and  Dispose.  A  dis¬ 
cussion  of  these  standard  utilities 
may  be  found  in  Niklaus  Wirth's  Pro¬ 
gramming  in  Modula-2 2.  We  feel  that 


the  mnemonic  value  of  these  decla¬ 
rations  is  great  enough  that  further 
discussion  of  them  is  not  required. 

We  have  chosen  to  implement 
Queues  via  the  mechanism  of  a  dy¬ 
namically  allocated  linked-list  struc¬ 
ture.  Upon  examining  the  imple¬ 
mentations,  we  see  first  that  the  code 
is  easily  read  and  much  akin  to  Pas¬ 
cal.  Upon  closer  examination  we  dis¬ 
cern  that  the  Add  procedure  is  a 
well-known  recursively  defined  al¬ 
gorithm.  At  this  point  we  recognize 
that  we  might  later  wish  to  change 
this  procedure  to  a  nonrecursive  al¬ 
gorithm.  If  we  do  so,  it  will  not  be 
necessary  to  recompile  either  the  of 
the  definition  modules  or  the  MOD¬ 
ULE  Sorter.  The  only  recompilation 
necessary  will  be  that  of  IMPLEMEN¬ 
TATION  MODULE  Queues. 

The  random  number  generator  in 
IMPLEMENTATION  MODULE  Random- 
Numbers  is  an  example  of  the  classic 
linear  congruential  multiplicative 
pseudorandom  number  generator  of 
the  type  discussed  in  Knuth's  text3, 
among  others.  However,  we  have 


chosen  the  coefficients  for  the  recur¬ 
rence  relation  poorly.  If  we  recog¬ 
nize  this,  say  after  using  MODULE 
Sorter  for  six  months  or  so  in  a  pro¬ 
duction  environment,  we  can  simply 
replace  the  coefficients  with  more 
appropriate  ones  and  recompile  the 
IMPLEMENTATION  MODULE  Random- 
Numbers.  Because  it  is  not  necessary 
to  recompile  Sorter,  a  user  of  the  sys¬ 
tem  might  be  totally  unaware  that 
we  have  made  any  changes. 

If  we  find  that  the  uses  of  our  sys¬ 
tem  are  not  well  suited  to  recursion, 
we  may  change  PROCEDURE  Add  of 
IMPLEMENTATION  MODULE  Queues  to 
a  nonrecursive  routine.  Once  again, 
it  will  be  necessary  to  recompile  only 
IMPLEMENTATION  MODULE  Queues  to 
effect  the  change. 

Before  the  changes  were  made, 
our  system  was  capable  of  sorting 
fewer  than  1,000  pseudorandom 
numbers;  however,  after  we  in¬ 
stalled  the  nonrecursive  version  of 
Add,  we  used  the  system  to  sort  more 
than  4,000  random  numbers.  (This 
feat  was  accomplished  overnight.  In¬ 
sertion  sorting  is  as  slow  sorting 
method!)  In  addition,  the  range  of  the 
pseudorandom  numbers  generated 
by  randu  was  increased  from  0  .  .  6  to 
0  .  .  4095. 

Conclusion 

In  addition  to  the  features  of  the  lan¬ 
guage  shown  here,  Modula-2  also  of¬ 
fers  procedure  types,  generics,  open 
array  parameters,  low-level  facili¬ 
ties,  concurrent  processes,  and  many 
other  resources  too  numerous  to 
mention  in  this  article.  Those  readers 
interested  in  further  study  of  Mo¬ 
dula-2  are  invited  to  examine  the  fol¬ 
lowing  list  of  sources. 

Notes 
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_ C  CHEST 

LISTING  TWO  (Text  begins  on  page  16) 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 


# include  <stdio.h> 
# include  <ctype.h> 


/* 


HIST.C  Support  for  Unix-like  history.  In  addition,  if  ! 

replaced  with  a  A  you'll  be  in  edit  mode  before 
re-executing  the  command.  Legal  syntaxes  are: 


is 


Copyright  (C)  1985  Allen  I.  Holub.  All  rights  reserved. 


non-edit 

mode: 


!<num> 

! <pat> 
!>  file 
! <  file 


edit  function 

mode:  performed: 

AA  repeat  previous  command 

A<num>  repeat  cmd  with  hist  number  <num> 

A<pat>  repeat  cmd  that  matches  pat. 

Save  history  list  to  file 
Restore  history  list  from  file 


Externally  accessable  routines  are: 


void 

FILE 


int 


print  hist (fp) 
*fp; 

get_hnum() 


void  history (  buf , 
char  *buf; 


Print  the  history  list  along  with 
associated  nums  (for  the  !<num>  command). 

Returns  the  history  number  that  will  be 
associated  with  the  next  call  to  history. 

maxbuf) 

Add  the  contents  of  buf  to  the  history 
list.  If  buf  contains  a  history  request 
(!!  etc.)  expand  it  too.  In  this  case, 
overwrite  buf  with  the  entry  from  the 
history  list.  No  more  than  maxbuf 
characters  will  be  copied. 


39 

extern 

char 

* strsave 

(  char* 

40 

extern 

int 

strmatch 

(  char*. 

char* 

41 

extern 

char 

*efgets 

(  char*. 

int,  FILE* 

42 

43 

44 


) ; 
) ; 
) ; 


/* 


32 

Hist  list 
&HisT_list [MAXHIST-1 


45  idefine  MAXHIST 

46  # define  START 

47  #define  END 

48  #def ine  HIST  CH 

49  #def ine  EDIT- CH 

50  #def ine  READ- CH  '<’ 

51  # define  WRITE  CH  •>' 

52 

53  #define  DEF  HNAME  "/histlist" 

54 

55 

56  / 


/*  Size  of  history  list  */ 


/*  Default  place  to  save  history  list  with 
*  !>  or  ! <  commands,  (ie.  no  file  given) . 
*/ 

- */ 

*/ 


57  /*  History  list,  maintained  as  a  ring  buffer: 

58 

59  static  char  *Hist  list [MAXHIST] = 

60  { 

NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL, 

NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL, 

NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL, 

NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL,  NULL 


61 
62 

63 

64 

65  } ; 


add  hist (  cmd  ) 

*cmH; 

If  cmd  is  non-null,  add  it  to  the  history  list. 
Commands  are  copied  into  a  malloced  buffer. 


*/ 

if  ( 

{ 


66 

67  static  char 

68  static  int 

69 

70  /* - 

71 

72  static  void 

73  char 

74  { 

75  /* 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93  } 

94 

95  /* - 

96 

97  static  int 

98  register  int 

99  char 
100  { 

101 
102 

103 

104 

105 

106 
107 


**Hist_ptr 
Hist  num 


START; 

1; 


/*  Pointer  into  history  list 
/*  Current  history  number 


*/ 

*/ 


cmd  ) 


if (  *Hist  ptr  ) 

free  (  *Hist_ptr  ) ; 


if  ( 


else 

{ 


(*Hist  ptr  =  strsave (cmd) )  ) 
prinff ("Out  of  memory  !!\n"); 


Hist  num++  ; 

if(  T+Hist  ptr  >  END  ) 

Hist_ptr  =  START  ; 


} 


get  hist (buf,  maxbuf,  desired) 
desired; 

*buf; 

Copy  the  string  associated  with  the  indicated  history 
number  into  buf  if  possible.  Return  1  on  success  &  0  if 
the  number  isn't  in  the  list  (is  too  old).  Negative 
numbers  are  treated  as  an  offset  from  the  current 
history  number.  If  "desired"  is  0  then  we  are 
searching  for  a  pattern  rather  than  getting  a  particular 
number.  In  this  case  the  patern  starts  at  buf[l]; 


/* 
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108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161 
162 

163 

164 

165  } 

166 

167  /* - 

168 

169  static 

170  char 

171  { 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184  } 

185 

186  /* - 

187 

188  int 

189  { 

190 

191  } 

192 

193  /* - 

194 

195  void 

196  FILE 

197  { 

198 

199 

200 
201 
202 

203 

204 

205 

206 

207 

208 

209  } 

210 
211 

212  /* - 


*/ 


register  char  **p; 


if(  ! desired  ) 

/*  A  pattern  was  requested.  Return  0  if  you  can't 

*  find  it.  Otherwise,  when  the  loop  is  done  *p  will 

*  point  at  the  correct  string.  Search  the  list 

*  backwards  starting  at  the  most  recently  entered 

*  number. 

*/ 

for(  p  =  Hist  ptr,  ++buf  ;  1  ;  ) 

{ 

p  =  (p  ==  START)  ?  END  :  p  -  1  ; 

if(  ! strmatch (buf ,  *p)  ) 
break; 


} 


if (  p  ==  Hist_ptr  ||  !*p  ) 
return  0; 


— buf; 

} 

else 

/*  An  actual  history  number  has  been  requested: 

* 

*  1)  Convert  a  negative  offset  into  an  actual 

*  history  number  if  necessary. 

*  2)  Then  convert  the  history  number  into  an 

*  offset  into  the  history  list.  Note  that 

*  this  will  be  a  negative  offset  even  though 

*  the  result  of  this  operation  is  positive. 

*  3)  If  the  offset  is  out  of  range,  return  a  0 

*  4)  Else  convert  the  offset  into  a  pointer  into 

*  the  history  list.  If  the  pointer  is  off  the 

*  list  wrap  around  to  the  other  end. 

*/ 


} 


if  (  desired  <  0  )  /*  1  */ 

desired  +=  Hist_num; 

desired  =  Hist_num  -  desired;  /*  2  */ 

if (  desired  <1  | |  desired  >  MAXHIST  )  /*  3  */ 

return  0; 

if (  (p  =  Hist  ptr  -  desired)  <  START  )  /*  4  */ 

p  +=  MAXHIST; 


strncpy  (  buf,  *p,  maxbuf  ) ; 
return  1; 


*/ 


int  eget  hist (  buf,  maxbuf,  desired  ) 

*buf; 

/*  Works  just  like  get  hist  except  lets  you  edit  the 

*  command.  Note  that  Ifhe  string  returned  by  this  routine 

*  will  be  overwritten  by  the  next  call.  Copy  it  somewhere 

*  if  you  need  to  save  it. 


register  int  rval; 

if (  rval  =  aet_hist (buf ,  maxbuf,  desired)  ) 

rval  =  (int)  ef gets (buf ,  maxbuf,  stdin)  ; 

return  rval  ; 


*/ 


get_hnum  () 
return  Hist  num  ; 


*/ 


print_hist  (  stream  ) 

♦stream; 

register  char  **hp  -  Hist  ptr  ; 
register  int  i  =  Hist_num  -  MAXHIST  ; 

do  { 

if(  i  >«  1  ) 

fprintf (stream,  "%3d:  %s\n",  i,  *hp  ); 

if (  ++hp  >  END  ) 

hp  =  START; 

}  while (  ++i  <  Hist_num  )  ; 


■*/ 


213 

214  char  *hist_name  (  fname  ) 

215  register  char  * fname; 

216  { 

217  /* 

218  * 

219  * 

220  * 


Strip  leading  white  space  from  fname  and  then 
return  a  pointer  to  either  the  first  non-white 
character  or  to  DEF_HNAME  if  there  is  no 
non-white  character 
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LISTING  TWO  (Listing  continued;  text  begins  on  page  16) 


221 

222 

223 

224 

225 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 

239 

240 

241 

242 

243 

244 

245 

246 

247 

248 

249 

250 

251 

252 

253 

254 

255 

256 

257 

258 

259 

260 
261 
262 

263 

264 

265 

266 

267 

268 

269 

270 

271 

272 

273 

274 

275 

276 

277 

278 

279 

280 
281 
282 

283 

284 

285 

286 

287 

288 

289 

290 

291 

292 

293 

294 

295 

296 
297. 

298 

299 

300 

301 

302 

303 

304 

305 

306 

307 

308 

309 

310 

311 

312 

313 

314 

315 

316 

317 

318 

319 

320 

321 

322 

323 

324 

325 

326 

327 

328 


V 


while  (  i s spa ce (*f name)  ) 
fname++; 

return  (  *  fname  )  ?  fname  :  DEF  HNAME  ; 

} 

/* - */ 

save_hist (  fname  ) 
register  char  * fname; 

/*  Save  the  current  history  list  in  either  the  indicated 

*  file  or  in  DEF  HNAME  if  no  file  is  given. 

V 


register  FILE  *fp; 

fname  *  hist_name(  fname  ); 

if(  ! (fp  =  f open (fname, "w") )  ) 
perror  (fname) ; 

else 

print_hist (fp) ; 
fclose (fp) ; 

} 

/* - */ 


restore_hist (  fname  ) 
char  * fname; 

{ 

/*  Add  the  contents  of  fname  (or  DEF_HNAME  if  fname  is 

empty)  to  the  history  list.  Don't  execute  the 
*  commands . 

V 


register  FILE  *fp  ; 

register  char  *p  ; 

char  *ouf  ; 

fname  =  hist_name(  fname  ); 

if (  !  (fp  ■  fopen(  fname,  "r"  ))  ) 
perror  (fname) ; 

else  if (  ! (buf  =  malloc(1024)  )) 

fprintf (stderr, "Not  enough  memory\n") ; 

else 

{ 

while (  efgets(buf,  1024,  fp)  ) 

for(p  *  buf;  isdigit  (*p)  ||  isspace(*p);  p++  ) 


/*  Skip  a  :<blank>  if  */ 
/*  one  is  present  */ 


%s\n",  Hist_num  -  1,  p  ); 

} 


p++; 


#ifdef  DEBUG 

U^r^A  T  f 


if(  *p 
if(  *P 

P++; 

add_hist (  p  )  ; 
printf ("adding  %3d: 


) 


free (  buf  ) ; 


) 


/* 


•*/ 


void  history!  buf,  maxbuf  ) 

register  char  *buf; 

register  lnt  i  -  1  ; 
register  char  *p.  =  buf; 

/*  If  buf  contains  a  history  request  (!!  AA  !<num>  or  A<num>) 

*  replace  its  contents  as  indicated.  In  any  event  add  the 

*  contents  of  buf  (after  the  replacement  if  one  was  done)  to 

*  the  history  list.  Blank  lines  are  ignored.  If  a  history 

*  expansion  occures,  the  expanded  line  is  printed. 

*  Null  stings  won't  be  added  to  the  history  list. 


if (  !*P  ) 

return; 


if  ( 

I 


*p  ==  HIST_CH  ||  *p  —  EDIT_CH  ) 


/* 

h 

* 

*/ 


First  increment  p  to  point  at  the  second  character 
in  the  buffer.  If  the  second  character  in  the  buffer  is 
a  !  or  A  then  i  -  -1,  otherwise  it  gets  the  history  #. 


if (  *++p  =«  READ_CH  ) 

{ 


) 

else  if ( 

( 


restore  hist (  p  +  1 
♦buf  -  "AO 1 ; 

*p  ==  WRITE_CH  ) 


save  hist  (  p  +  1  )  ; 
♦buf--  '  \0 1  ; 


) ; 
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LISTING  TWO  (Listing  continued;  text  begins  on  page  16) 


329 

330 

331 

332 

333 

334 

335 

336 

337 

338 

339 

340 

341 

342 

343 

344 

345 

346 

347 

348 

349 

350  } 

351 

352  /* - 

353 

354  #ifdef 

355 

356  main  () 

357  { 

358 

359 

360 

361 

362 

363 

364 

365 

366 

367 

368 

369 

370 

371 

372 

373 

374 

375 

376 

377  } 

378 

379  #endif 


} 

else 

{ 

i  =  (*P  ==  HI ST_CH  ||  *p  ==  EDIT_CH)  ?  -1:  atoi  (p) ; 

if (  *buf  --  EDIT_CH  ) 

i  =  eget_hist (  buf,  maxbuf,  i) ; 

else  if  (  i  =  get  hist  (  buf,  maxbuf,  i)  ) 
puts  (bufT; 


if  (  ! i  ) 

{ 

fprintf (stderr,  "\"%s\"  not  in  history  list\n",  buf); 
*buf  =  ' \ 0 ' ; 

} 

} 

add_hist (  buf  ) ; 


■*/ 


DEBUG 


/*  Test  the  history  function.  Everything  typed  at  the 

*  console  is  added  to  the  history  list  and  all  of 

*  the  history  expansion  functions  should  work. 

*/ 

char  buf [132] ; 

while (1) 

{ 

printf("[%d]  ",  get_hnum()  ); 

if(  ! gets (buf)  ) 
break; 

history  (  buf,  132  ); 

if(  *buf  ==  'h'  &&  !buf [1]  ) 

print_hist(  stdout,  0  ); 


End  Listing  Two 

LISTING  THREE 


1  #include  <stdio.h> 

2  # include  <ctype.h> 


3 

4  /* 

5  * 

6  * 
7  * 


VAR.C  Support  for  shell  variables  and  aliases. 

Copyright  (c)  1985,  Allen  I.  Holub.  All  rights  reserved. 


9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 


Externally  accessible  routines: 

void  unsetvar(  name  ) 
int  setvar(  name,  val  ) 
void  printalias () 
void  printvars () 

int  getvar(srcp,  destp,  maxcount) 

The  same  routines  are  used  for  both  shell  variables  and  aliases.  The 
flatter  have  the  high  bit  of  the  first  character  in  the  name  set. 

Isname  is  true  if  c  is  legal  in  a  name.  NAMELEN  is  the  maximum 
length  of  a  name  (additional  characters  are  truncated) . 


Delete  a  variable  or  alias 
Create/init  a  variable  or  alias 
Print  all  aliases 
Print  all  shell  variables 
Expand  a  variable  or  alias 


#define  isname (c) 
#define  isalias(p) 

fdefine  NAMELEN  8 


(isalnum(c)  ||  (c)  == ' 

(  * (p)  &  0x80  ) 


II  (c) ==•-'  ||  (c)  ==':•) 


29  typedef  struct  var 

30  { 

31  char  name [NAMELEN] ; 

32  struct  var  *next; 

33  char  val[l]; 

34  ) 

35  VAR; 

36 

37  static  VAR  *Varlist  =  NULL  ; 

38  static  VAR  *Lastvar  =  NULL  ; 

39  extern  char  *getenv (  char*  ); 

40 

41  /* - 

42 

43  static  VAR  *findvar(  name  ) 

44  char  *name; 

45  { 


/ 
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LISTING  THREE  (Listing  continued,  text  begins  on  page  16) 


Do  a  search  in  the  Varlist  linked  list  for  a 
variable  called  "name."  Return  a  pointer  to  it  if 
it  exists  or  0  if  it  doesn't. 


register  VAR  *p; 

for(  p  ■  Varlist;  p  !-  NULL  ;  p  =  p->next) 

if (  Istrncmp (name,  p->name,  NAMELEN)  ) 
return  p; 

return  (VAR  *)  0  ; 


unsetvar(  name  ) 

*name; 

/*  If  the  variable  called  name  exists,  delete  it. 


register  VAR 
register  VAR 


Varlist  ; 
Varlist  ; 


if(  !p  ||  ! (*name  &  0x7f)  ) 
return; 

for (  p  -  Varlist;  p  !-  NULL  ;  ) 

if(  !strncmp(name,  p->name,  NAMELEN)  ) 

/*  If  lastp  —  p  then  there's  only  one 
*  node  in  the  list. 

*/ 

if(  lastp  —  p  ) 

Varlist  =  Lastvar  -  NULL; 

else 

if(  ! (lastp->next  =  p->next)  ) 
Lastvar  -  lastp; 


free (  p  ) ; 
break; 


lastp  =  p  ; 
p  -  p->next; 


varcpy  (  dest 
register  char 


src  ) 

♦dest,  *src; 


Copy  src  to  dest,  stripping  backslashes  and  quotes, 
as  appropriate  (ie  a  \  within  a  quoted  string  isn't 
stripped. 

inquote  =0; 


while (  *src  ) 


if(  *src 


if  (  Unquote  ) 
src++; 

else 

*dest++  =  *src++; 

if(  *src  ) 

*dest++  -  *src++; 


else  if  (*src 


|  |  *src  —  ' \" ) 


inquote  =  ~inquote; 
src++; 


setvar  (  name,  val  ) 
♦name,  *val; 


Set  the  value  of  the  variable  "name"  to  "val".  If  it 
already  exists,  delete  it. 


register  VAR  *vp; 

if (  !*name  ) 

return  0; 

unsetvar  (  name  ) ; 

if(  ! (vp  =  (VAR  *)  malloc(sizeof (VAR)  +  strlen  (val) ) )  ) 
return  0; 


2 
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strncpy (  vp->name,  name,  NAMELEN  ) ; 
varcpy  (  vp->val  ,  val  ) ; 
vp->next  -  NULL; 

1 f (  IVarlist  ) 

Varlist  -  vp; 

else 

Lastvar->next  -  vp; 

Lastvar  -  vp; 
return  1; 


*  All  routines  in  this  module  may  be  used  for  both  aliases  and  shell 

*  variables  except  for  the  two  print  routines.  Alias's  have 

*  the  high  bit  if  the  first  character  of  the  name  string  set. 

*/ 

void  printalias () 

register  VAR  *p; 

for(  p  -  Varlist;  p  !-  NULL  ;  p  -  p->next) 
if  (  isalias (p->name)  ) 

printf  ("%c%-8.8s:  %s\n", 

*  (p->name)  &  0x7f,  p->name  +1,  p->val  ); 


void  printvars () 


register  VAR  *p; 

for(  p  -  Varlist;  p  !-  NULL  ;  p  -  p->next) 
if (  ! isalias (p->name)  ) 

printf ("%-8. 8s;  %s\n",  p->name,  p->val  ); 


193 

194  int 

195  char 

196  int 

197  { 

198 

199 

200 
201 
202 

203 

204 

205 

206 

207 

208 

209 

210 
211 
212 

213 

214 

215 

216 

217 

218 

219 

220 
221 
222 

223 

224 

225 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 

239 

240 

241 

242 

243 

244 

245 

246 

247 

248 

249 

250 

251 

252 

253 

254 

255 

256 

257 

258 

259 

260 
261 
262 
263 


getvar(  srcp,  destp,  maxcountp  ) 

**destp,  **srcp; 

*maxcountp; 

/*  Expand  variable  at  "*srcp"  into  destp.  Do  nothing  if 

*  the  variable  doesn't  exist,  otherwise  update  srcp  to 

*  point  past  the  variable  name,  update  destp  to  point 

*  past  tne  end  of  the  expanded  variable,  and  decrement 

*  maxcountp  by  the  proper  amount. 

* 

*  Both  shell  variables  and  enviornment  variables  will  be 

*  expanded.  However,  shell  variables  take  presendance 

*  over  enviornments  (they're  looked  for  first). 

* 

*  A  name  can  consist  of  any  character  in  the  set 

*  {a-zA-ZO-9-  }. 

* 

*  If  the  name  is  for  an  alias  it  will  be  copied  to  dest  if 

*  it  can't  be  expanded,  otherwise  the  name  is  discarded 

*  if  it  can't  be  expanded. 

V 

register  VAR  *vp; 

char  name [ NAMELEN+1 ] ; 

register  char  *p  -  name; 

int  i  -  NAMELEN; 

/*  If  the  source  string  is  empty  or  doesn't  contain  a  legit. 

*  name  then  return,  doing  nothing  to  dest. 

V 

if  (  !**srcp  ||  ! isname (**srcp  &  0x7f)  ) 
return  0; 

/*  Extract  the  name  from  the  string  at  *srcp,  updating 

*srcp  to  point  past  it. 

for(  **srcp;  isname (**srcp  &  0x7f)  &&  — i>«0;  *p++  -  *(*srcp)++  ) 


Now  look  for  the  name.  If  findvar  returns  true  it's 
a  variable  or  alias. 


-  findvar (name)  ) 

/*  Expand  the  alias.  Note  that  the  since  we 

*  are  called  from  exp  vars,  this  next 

*  call  is  a  second  orcfer  recursion. 

*/ 

i  -  exp  vars(  *destp,  vp->val,  *maxcountp,  2  ); 
*destp  +-  i  ; 

♦maxcountp  —  i  ; 


/*  It's  not  in  the  variable  table.  If  we're  processing 

*  an  alias,  copy  the  name  to  dest.  If  we're  not 

*  processing  an  alias,  but  the  variable  is  in  the 

*  er.voirnment,  then  copy  the  contents  of  the  enviornment 

*  else  do  nothing. 

*/ 

if  (  p  -  isalias  (name)  ?  name  ;  getenv(name)  ) 
while  (  *maxcountp  >1  &&  *p  ) 
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LISTING  THREE  (Listing  continued;  text  begins  on  page  16) 


264 

265 

266 

267 

268 

269 

270 

271 

272 

273 


{ 

**destp  -  *p++ 
(*destp  )++; 
(*maxcountp) — ; 

}  } 

) 

**destp  -  1 \0 1 ; 


End  Listing  Three 

LISTING  FOUR 


Concatantate  all  argv  entries  into  a  single 
string. 


1  #include  <stdio.h> 

2 

3  /*  UNARGV.C 

4  * 

5  */ 

6 

7  int  unargv(  argc,  argv,  dest,  maxcount  ) 

8  char  **argv,  *dest; 

9  register  int  maxcount; 

10  { 

/*  Turn  argv  into  a  single  string,  with  a  single  '  '  seperating 

*  each  entry,  maxcount  is  the  maximum  size  of  dest.  Return 

*  the  number  of  characters  put  into  dest. 


11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30  } 


register  char 
char 


*src; 

*sdest 


while  (  — argc  >=  0 


{ 


dest ; 

&&  maxcount  >  0  ) 


for(  src  -  *argv++;  *src  &&  — maxcount  >  0;  ) 
*dest++  -*  *src++  ; 


if(  — maxcount  >  0 
*dest++  -  ' 


*dest  -  0; 

return (  dest  -  sdest  ); 


&&  argc  >  0  ) 


End  Listing  Four 


LISTING  FIVE 


1  extern  int  strcpy  (  char*,  char*  ); 

2  extern  char  *malloc  (  unsigned  ); 

3  extern  int  strlen  (  char*,  ); 

4 

5 

6  char  *strsave(  str  ) 

7  char  *str; 


8  { 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24  } 


/*  Save  the  indicated  string  in  a  malloc()ed  section 

*  of  static  memory.  Return  a  pointer  to  the  copy  or 

*  0  if  malloc  failed 
*/ 

register  char  *rptr; 
extern  char  *malloc(); 

if (  rptr  -  malloc (  strlen (str)  +1  )) 

{ 

strcpy (  rptr,  str  ); 
return  rptr; 


return  (char  *)0; 


End  Listings 
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LISTING  ONE  (Text  begins  on  page  36) 

{  file  polydiv .pas,  85/9/18/tfr  (from  9/15,13)  ) 

{  "x  Shi  1"  must  itself  be  "x  +  x";  init  x  to  1  first  ) 

(  simulation  of  CRC-type  operations  ) 

BEGIN 

{  Copyright  (c)  1985,  T.F.  Ritter;  All  Rights  Reserved  ) 

an  ((a  AND  (1  SHL  n) )  <>  0)  ; 

END; 

(  generates  a  binary  trace  through  the  polynomial  division 
{  and  crc  algorithms  to  illustrate  equivalent  results 
(  (this  assumes  we  init  the  remainder  reg.  to  0)  ) 

{  start  crc-type  algorithms  ) 

{ $R+ )  {  Range  Checks  ON  ) 

PROCEDURE  pdiv; 

(  mod-2  polynomial  division  (for  remainder  only)  ) 

PROGRAM  polydiv; 

BEGIN 

IF  an (deg  -  1)  THEN 

a  (a  Shi  1)  XOR  p  XOR  dn 

{  first,  output  through  MSDOS,  and  define  binary  display  } 

ELSE 

a  (a  Shi  1)  XOR  dn; 

END;  (pdiv) 

TYPE 

PROCEDURE  crc; 

regs  -  RECORD 

(  mod-2  remainder  without  extra  zeros  ) 

ax,bx, cx, dx,bp, si, di, da, es, flags :  INTEGER; 

BEGIN 

END; 

IF  (an (deg  -  1)  XOR  (dn  <>  0))  THEN 

PROCEDURE  bdosch (  ch:  CHAR  ); 

a  (a  Shi  1)  XOR  p 

ELSE 

a  :-  (a  Shi  1); 

{  output  through  MSDOS;  allow  Ctrl-P  toggle  ) 

END;  (crc) 

VAR  r:  regs; 

BEGIN 

r.ax  $0200; 

r . dx  : -  ORD ( ch ) ; 

(  start  trace  displays;  show  one  or  the  other  ) 

MsDos (  r  ); 

END; 

TYPE 

PROCEDURE  showpdiv {  dbits:  BYTE  ) ; 

VAR  i:  BYTE; 

BEGIN 

small  -  0  .  . 15; 

WRITE!  "M'J 1  POLYNOMIAL  DIVIDE;  Polynomial  -  1  ) ; 

PROCEDURE  showbin (  x:  INTEGER;  from,  too;  small  ); 

showbin (  p,  deg,  0  ); 

WRITE (  '■'M'' J 1  Remainder  Data'  ); 

showad (  deg  ); 

(  display  subset  of  integer  as  binary  bits  ) 

FOR  i  1  TO  dbits  DO 

(  from  and  too  are  place  values  (15  -  0)  left  to  right  ) 

BEGIN 

VAR  i:  small; 

pdiv; 

BEGIN 

showad  (  deg  ) ; 

WRITE (  '  ' 

END; 

FOR  i  i-  15  DOWNTO  0  DO 

WRITELN; 

BEGIN 

END; 

IF  i  IN  [too.. from]  THEN 

IF  (X  <  0)  THEN 

WRITE (  '  1*  ) 

PROCEDURE  showcrc(  dbits:  BYTE  ); 

ELSE 

VAR  i:  BYTE; 

WRITE (  '  O'  ) 

BEGIN 

{ 

WRITE!  "M'J'CRC  OPERATION;  Polynomial  -  '  ) ; 

ELSE 

showbin (  p,  deg,  0  ); 

WRITE (  J 1  Remainder  Data'  ); 

WRITE (  '  X'  ) 

); 

showad (  deg  ); 

x  :-  x  Shi  1; 

FOR  i  1  TO  dbits  DO 

END; 

BEGIN 

WRITE (  '  '  ); 

crc; 

END;  (showbin) 

showad (  deg  ) ; 

VAR  {  global s  ) 

a;  INTEGER;  (  the  remainder  value  register;  right-aligned  ) 
p:  INTEGER;  (  the  polynomial;  right-aligned  ) 
d:  INTEGER;  (  the  data;  left-aligned  ) 

END; 

WRITELN; 

END; 

PROCEDURE  init  (  i:  BYTE  ); 

deg:  small;  {  the  degree  of  the  polynomial  ) 

(  select  one  of  the  initializations  ) 

dbits:  BYTE;  {  the  number  of  data  bits  to  process  ) 

PROCEDURE  init 1 ; 

{  simulating  long  division  example  ) 

{  from  Peterson  &  Brown,  Proc.  of  the  IRE,  Jan.  1961, 

p.  232  ) 

PROCEDURE  showad (  pb:  small  ); 

BEGIN 

{  show  current  remainder  and  next  data  bit  (only)  ) 

p  :-  $0005; 

{  the  data  bit  on  the  last  step  is  meaningless  ) 

deg  :-  2; 

BEGIN 

d  :-  $e800; 

WRITELN; 

dbits  :-  6; 

showbin (  a,  (pb  -  1),  0  ); 

END;  linitl) 

showbin (  d,  15,  15  ); 

END; 

{  start  bit-level  utilities  for  crc-type  algorithms  ) 

PROCEDURE  init 2; 

{  simulating  generation  of  check  code  ) 

{  Peterson  &  Brown,  1961,  p.  229  ) 

{  data  are  shifted  left,  so  are  in  reversed  order  from 

article  } 

TYPE 

BEGIN 

p  $0035;  (  the  classical  example  polynomial'  } 

deg  :-  5; 

abit  -  0. .1; 

d  :-  $8940; 

FUNCTION  dn:  abit; 

{  value  of  next  data  bit  ) 

(  since  d  is  an  INTEGER,  "d  Shi  1"  -  "d  +  d"  ) 

dbits  10; 

END;  (init2) 

PROCEDURE  init3; 

{  use  "d  d  +  d"  in  other  Pascals  } 

{  simulating  published  tables  } 

BEGIN 

(  K.  Rallapalli,  EDN,  Sept.  5  1978,  pp.  119  -  123  ) 

IF  (d  <  0)  THEN 

BEGIN 

dn  1 

p  $0035;  (  here  it  is  again  } 

ELSE 

deg  :-  5; 

dn  0; 

d  :-  SdlbO; 

d  d  Shi  1; 

dbits  :-  12; 

END; 

END;  ( init3 ) 

FUNCTION  an (  n:  small  ):  BOOLEAN; 

BEGIN  (init) 

CASE  i  OF 

(  value  of  particular  remainder  bit  ) 

1:  initl ; 

(  for  other  Pascals,  use  a  loop  and  do  "x  Shi  1"  n  times  ) 

21  lnit2''  (Continued  on  page  78) 
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{  METHOD  4:  Pascal  Table  } 

{  pull  changes  from  table,  indexed  by  composite  value  ) 

{  still  faster,  but  requires  the  table,  and  filling  the  table  } 
{  may  be  even  faster,  relatively,  in  another  Pascal  } 

{  a  slower  routine  is  fine  to  fill  the  table  ) 


VAR 

crctab:  ARRAY [0. .255]  of  INTEGER; 


PROCEDURE  crctablu (  VAR  crcreg :  INTEGER;  data:  INTEGER); 
BEGIN 

crcreg  Swap (crcreg)  XOR  data; 

crcreg  (crcreg  AND  $ff00)  XOR  crctab[  Lo (crcreg)  ]; 
END; 


PROCEDURE  initctab; 

{  use  method  3  to  init  the  table  ) 

VAR 

i:  INTEGER; 

BEGIN 

FOR  i  0  TO  255  DO 
BEGIN 

crctab[i]  :-  0; 
crcitta<  crctab [i],  i  ); 

END; 

END;  (initctab) 

{  METHOD  5:  Machine  Code  Byte  } 

{  method  3  in  "Inline"  machine  code  (MSDOS)  ) 

{  typically  hidden  away  in  an  "Include"  file  ) 

{  other  Pascals  may  need  to  modify  the  stack  interface  ) 


PROCEDURE  mcrcittl (  VAR  dx :  INTEGER;  data:  INTEGER  ); 

{  a  :-  crcTransform(  dx;  data  )  ) 

(  for  MSDOS  ) 

{  polynomial  -  $11021  } 

BEGIN  {  mcrcittl  } 

INLINE  ( 

$c4/$7e/<dx/  {  es : di  :-  [bp  +"dx"]  ) 

$26/$8b/$05/  {  ax  :-  [es:di]  ) 

(  dx  :-  SWAP(dx)  XOR  data;  } 

$86/$e0/  (  ah  <->  al  ) 

$33/$46/<data/  {  ax  :-  ax  XOR  [bp  +  "data"]  } 
$89/$c2/  {  dx  :-  ax  } 

{  dx  :-  dx  XOR  (  LO (dx)  SHR  4  );  } 

$d0/$e8/  {  al  :-  al  SHR  1  ) 

$d0/$e8/  (  al  :-  al  SHR  1  } 

$d0/$e8/  {  al  :-  al  SHR  1  ) 

$d0/$e8/  {  al  :-  al  SHR  1  ) 

$32/$d0/  {  dl  :-  dl  XOR  al  ) 

{  dx  :-  dx  XOR  (  (SWAP (  LO(dx)  )  SHL  4  );  ) 

$88/$d4/  {  ah  :-  dl  ) 

$d0/$e4/  {  ah  :-  ah  SHL  1  ) 

$d0/$e4/  (  ah  :-  ah  SHL  1  ) 

$d0/$e4/  {  ah  :-  ah  SHL  1  ) 

$d0/$e4/  (  ah  :-  ah  SHL  1  ) 

$32/$f 4/  (  dh  :-  dh  XOR  ah  ) 

{  dx  :-  dx  XOR  (  (  LO(dx)  )  SHL  5  ) ;  ) 

$88/$d0/  (  al  :-  dl  } 

$b4/$00/  |  ih  :-  0  ) 

$dl/$e0/  {  ax  :-  ax  SHL  1  ) 

$dl/$e0/  {  ax  :-  ax  SHL  1  } 

$dl/$e0/  (  ax  :-  ax  SHL  1  ) 

$dl/$e0/  (  ax  ax  SHL  1  } 

$dl/$e0/  {  ax  :-  ax  SHL  1  ) 

$33/$d0/  (  dx  :-  dx  XOR  ax  ) 

$26/ $89/$15  (  es: [di]  dx  )  ); 

END;  {  mcrcittl  ) 


{  METHOD  6:  Machine  Code  Table  } 

{  here  the  stack  parameter  interface  becomes  significant  ) 
(  note  the  exchange  notation  "x  :-:  y"  in  the  comments  ) 


PROCEDURE  mcrcitt3(  VAR  dx:  INTEGER;  data:  INTEGER  ); 

{  a  :-  crcTransform(  dx;  data  )  ) 

{  for  MSDOS  } 

{  polynomial  -  $11021  ) 

BEGIN  (  mcrcitt3  ) 

INLINE  ( 

$c4/$7e/<dx/  {  es:di  :-  [bp  +"dx"]  } 

$26/$8b/$15/  {  dx  :-  [es:di]  ) 

{  dx  :-  Swap(dx)  XOR  data;  ) 

$86/$d6/  (  dh  :-:  dl  ) 

$33/ $56/<data/  (  dx  :-  dx  XOR  [bp  +  "data"]  ) 

{  bx  :-  Lo (dx)  SHL  1;  dl  :-  0;  ) 

$31/$db/  {  bx  :-  bx  XOR  bx  ) 

$86/$d3/  {  bl  :-:  dl  } 

$dl/$e3/  (  bx  :-  bx  SHL  1  ) 

(  dx  : ■  dx  XOR  crctab [  bx  ] ;  ) 

$33/$97/>crctab/  {  dx  :-  dx  XOR  [bx  +  "crctab"]  } 

$26/ $89/$15  {  [es : di]  :-  dx  }  ); 

END;  (  mcrcitt3  ) 

(Continued  on  nejtt  page) 


CRC 


LISTING  TWO 

(Listings  continued,  text  begins  on  page  26) 


(  start  of  validation  testing  } 


PROCEDURE  fultest (  beg:  INTEGER  ); 

CONST 

maxpass  -  5; 

TYPE 

St40  -  STRING [40] ; 

passtype  -  ARRAY [  1.. maxpass  ]  of  INTEGER; 

VAR 

adi,  pass:  INTEGER; 
adr,  adt:  passtype; 

PROCEDURE  overall (  VAR  a:  passtype;  t:  INTEGER  ); 

x,  en,  loc:  INTEGER; 
data:  BYTE; 

BEGIN 

FOR  pass  :-  1  to  maxpass  DO 
BEGIN 
x  :-  adi; 

CASE  pass  OF 
1 :  en  :-  beg; 

2:  en  :-  beg  +  1; 

3:  en  :-  beg  +  127; 

4 :  en  :-  beg  +  511; 

5:  en  :-  beg  +  81; 

END; 

FOR  loc  :-  beg  TO  en  DO 
BEGIN 

{  a  source  of  data  "random"  enough  for  our  purposes  ) 
{  is  available  in  the  program  code  area  ) 
data  :-  MEM [  Cseg:  loc  ]; 

CASE  t  OF 

1 :  crcittby (  x,  data  ) ; 

2:  crcfbbb(  x,  data  ); 

3:  crcitta (  x,  data  ); 

4 :  crctablu (  x,  data  ) ; 

5 :  mcrcittl (  x,  data  ) ; 

6 :  mcrcitt3 (  x,  data  ) ; 

END;  (case) 

END; 

a[pass]  : -  x; 

END; 

END;  (overall) 

PROCEDURE  pbin (  value:  INTEGER  ); 

VAR 

i:  INTEGER; 

BEGIN 

FOR  i  :-  15  DOWNTO  0  DO 
BEGIN 

IF  value  <  0  THEN 
WRITE (  '1'  ) 

ELSE 

WRITE  (  '0*  ) ; 
value  :-  value  SHL  1; 

END; 

END;  (pbin) 

PROCEDURE  showres(  s:  st40  ); 

VAR 

errfound:  BOOLEAN; 

BEGIN 

errfound  FALSE; 

WRITE (  AMAJ'  s  ) ; 

FOR  pass  :-  1  TO  maxpass  DO 

IF  (adt [pass]  <>  adr [pass])  THEN 
BEGIN 

errfound  :-  TRUE; 

WRITE (  AMAJ 'Pass  ',  pass,  ':  CRC  error.'  ); 

WRITE (  AMAJ,  'Reference:  ');  pbin(  adr [pass]  ); 
WRITE (  AMAJ,  'Under  Test:  ');  pbin(  adt [pass]  ); 

END; 


IF  NOT  errfound  THEN 

WRITE (  ' :  No  error. 1  )  ; 

END;  (showres) 

BEGIN  (fultest) 

WRITE (  AMAJAJ'BEGIN  Validation  Testing.'  ); 
adi  :-  -1; 


overall (  adr,  1  ); 

WRITE (  AMAJ'  Reference  -  crcittby  (Pascal  Bit-By-Bit).'  ); 
overall (  adt,  2  ); 

showres (  'crcfbbb  (Pascal  Fast  Bit-By-Bit)'  ); 

overall (  adt,  3  ); 

showres (  'crcitta  (Pascal  Byte)'  ); 

overall (  adt,  4  ); 

showres(  'crctablu  (Pascal  Table)'  ); 
overall (  adt,  5  ); 

showres (  'mcrcittl  (Machine  Code  Byte)'  ); 
overall (  adt,  6  ); 

showre8(  'mcrcitt3  (Machine  Code  Table)'  ); 

WRITELN (  AMAJ'END  Validation  Testing. '  ); 

END;  (  fultest  ) 
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{  start  of  timing  } 


WRITELN; 

END;  { timet est) 


PROCEDURE  timetest (  loop*:  INTEGER  ); 

{  organize  the  time  testing  of  various  routines  } 

VAR 

a,  b:  timearty; 
i,  xs  INTEGER; 
by;  BYTE; 

empty;  REAL;  {  time  for  empty  loops  } 

calltime:  REAL;  {  time  for  loops  and  empty  procedure  ) 


PROCEDURE  crcmt (  VAR  dx:  INTEGER;  data:  INTEGER); 
BEGIN 
END; 


PROCEDURE  showtimedif (  a,  b:  timearty;  c:  INTEGER  ); 

{  display  a  line  of  time  results  } 

VAR 

dif.  Noloop,  NoloopNocall :  REAL; 

BEGIN 

dif  :-  timedif(  a,  b  ); 

Noloop  :-  dif  -  empty; 

NoloopNocall  :-  dif  -  calltime; 

WRITE ( 

Noloop; 7 : 3,  1  NoloopNocall: 7:3,  ' 

Noloop  *  (1000.0  /  c):7:3,  '  ',  NoloopNocall  *  (1000.0 

END;  (showtimedif) 


(1000.0  /  c) : 7 : 3  ) ; 


BEGIN  (timetest) 

calltime  0.0;  (the  global) 

by  :-  $a5;  (your  typical  data  byte) 

WRITELN ( 

AMAJAJ' Turbo  Pascal  runs  CRC-CCITT  on  8088  under  Bare  MSDOS', 

AMAJ'  FOR  ',  loops,'  OPERATIONS;  7.16  MHz  CLOCK 

(multiply  by  1.5  for  4.77  MHz) •  ); 

WRITE (  AMAJ'Empty  loop:  '  ); 
readhms!  a  ); 

FOR  i  1  TO  loops  DO 

readhms (  b  ) ; 

empty  :-  timedif(  a,  b) ;  (the  global) 

WRITE (  empty: 5:3,  1  secs'  ); 

WRITE  (  AMAJ' Empty  procedure  in  loop:  '  ); 
readhms (  a  ); 

FOR  i  :-  1  TO  loops  DO 
crcmt (  x,  by  ) ; 
readhms (  b  ) ; 

calltime  :-  timedif(  a,  b  );  (another  global) 

WRITE (  calltime: 5:3,  '  secs'  ); 

WRITE (  AMAJ'  (procedure  overhead  alone  -  ', 

(calltime  -  empty)  *  (1000.0  /  loops) :6:3, 

'  msec  each) '  ) ; 


PROCEDURE  datatimes; 

(  data  character  times,  for  comparison  } 

CONST 

rates:  ARRAY [1.. 7)  of  INTEGER  - 

(  12,  24,  48,  96,  192,  384,  576  ); 

VAR  i:  INTEGER; 

BEGIN 

WRITELN (  AMAJAJ' Character  Times  for  Various  Bit  Rates:  '  ); 
WRITE (  AMAJ'  bits/sec  char/sec  msec/char'); 

FOR  i  :-  1  TO  7  DO 

WRITE (  AMAJ,  "  : 4 ,  (100.0  *  rates ( i) ) : 5 : 0,  ' ' : 8, 

(10.0  *  rates [i] ) : 5 : 0,  "  :8, 

(100.0  /  rates [i] ) : 5 : 3  ); 


WRITELN; 

END;  (datatimes) 


BEGIN  {  main:  crctime  } 
WRITELN; 


ConOutPtr  :-  OFS (  bdosch  );  (output  through  MSDOS) 


ownership; 
fultest(  100  ); 
timetest (  10000  ); 


End  Listings 


loops :5,  '  Uses  (secs) 


Procedure  In  Line 


1  Use 
(msec)  ' , 
In  Line '  ) ; 


WRITE ( 

AMAJ' Pascal  Bit-by-Bit:  '  ); 

readhms (  a  ); 

FOR  i  :-  1  TO  loops  DO 
crcittby (  x,  by  ) ; 
readhms (  b  ); 

showtimedif (  a,  b,  loops  ) ; 
WRITE ( 

AMAJ' Pascal  Fast  B-B-B:  '  ); 

readhms (  a  ) ; 

FOR  i  :-  1  TO  loops  DO 
crcfbbb(  x,  by  ); 
readhms (  b  )  ; 

showtimedif (  a,  b,  loops  ) ; 
WRITE ( 

AMAJ'Pascal  Byte:  '  ); 

readhms (  a  ) ; 

FOR  i  :-  1  TO  loops  DO 
crcitta (  x,  by  ) ; 
readhms (  b  ) ; 

showtimedif (  a,  b,  loops  )  ; 
WRITE ( 

AMAJ' Pascal  Table:  '  ); 

readhms (  a  ); 

FOR  i  :-  1  TO  loops  DO 
crctablu (  x,  by  ) ; 
readhms (  b  ) ; 

showtimedif (  a,  b,  loops  ) ; 
WRITE ( 

AMAJ'Machine  Code  Byte:  '  ); 

readhms (  a  ); 

FOR  i  :-  1  TO  loops  DO 
mcrcittl (  x,  by  ) ; 
readhms!  b  ); 

showtimedif  (  a,  b,  -loops  ) ; 
WRITE ( 

AMAJ' Machine  Code  Table:  '  ) ; 

readhms (  a  ); 

FOR  i  1  TO  loops  DO 

mcrcitt3 (  x,  by  ) ; 
readhms!  b  ); 

showtimedif (  a,  b,  loops  ) ; 
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LISTING  ONE  (Text  begins  on  page  36) 


(POWERN.PLB  #1.08  85-11-18  INTEGER  POWERS  OF  REALS 

V01  L08  85-11-18  presentation  streamlinina  by  DEH. 
L03  update  on  85-06-18  by  DEH  to  eliminate  one 
always-trivial  multiplication  by  expanding 
on  an  idea  of  David  Gries. 

LOO  created  on  85-06-05  by  Dennis  E.  Hamilton 
to  answer  a  number  of  electronic  requests 
for  help  with  Pascal  powers.  } 

function 

PowerN (x:  real;  (initial  value:  x0} 
n:  integer  {required  exponent}  ) 

:real  {value  of  x0**n}; 

var  i:  integer  {non-negative  power  of  x  remaining 
to  be  computed}; 

r:  real  {running  intermediate-result  value}; 

BEGIN  {PowerN} 
if  n  -  0 

then  PowerN  :-  x/x 
else  begin  {n  <>  0} 
i  abs (n) ; 

{x**i  -  x0**abs  (n) } 
while  not  odd(i) 

do  begin  {(x*x)**(i  div  2)  -  x**i} 
x  :-  sqr(x);  i  :-  i  shr  1; 
end; 
r  :-  x; 

{maintain  odd(i)  and  r*x**(i-l)  -  x0**abs  (n) , 
taking  r*x**  (i-1)  -  r  upon  reaching  i  -  1} 
while  i  <>  1 
do  begin 
repeat 

{  (x*x) **  (i  div  2)  -  x**  (i  -  i  mod  2) } 
x  :-  sqr(x);  i  :-  i  shr  1; 
until  oda(i); 

{odd(i)  and  r*x**i  -  x0**abs(n)} 
r  :-  r*x; 
end; 

{finally  i-1  and  r  -  x0**abs(n)} 
if  n  <  0 

then  PowerN  1.0/r 

else  PowerN  r; 

end; 

END  {PowerN  -  x0**n}; 


End  Listing  One 


LISTING  TWO 


program  TPWRN  (out) ; 

{TPWRN.PAS  #1.08  85-11-18  TEST  POWERN.PLB  CALCULATION  OF  POWERS 

V01  L08  pretty-print  update  on  85-09-15  with  tidier  test  output. 

L02  update  on  85-06-20  by  DEH  to  exhibit  precision-maintenance 
difficulties  with  (l/7)**-i  and  exp(i*ln(7))  variations. 

LOO  created  on  85-06-05  by  Dennis  E.  Hamilton,  just  for 
simple  confirmation  of  POWERN* s  method.} 

var  i:  integer  {counter  of  trial  exponents}; 

p7:  real  {intermediate  power  of  7  to  be  checked}; 
ln7:  real  (loaarithm  of  7  used  in  comparison  with  exp  (In)  method}; 
rv7:  real  {value  of  1/7  used  in  showing  precision  loss}; 
out:  text  {file  variable  used  for  direction  of  output  as  needed}; 

{$1  POWERN.PLB  }  {Vintage  1.00} 

{Include  PowerN  here  by  whatever  method  the  Pascal  system  supports. 

The  above  $1  pragmat,  used  with  Borland  International's  Turbo  Pascal, 
causes  a  copy  of  POWERN.PLB  to  be  included  at  this  point.} 

BEGIN  {Testing  the  basic  features  of  POWERN.PLB} 
assign  (out,  'CON:'); 

{Chanae  to  a  disk-file  name  when  you  want  to  capture  the  report  in 
a  file  for  comparison,  uploading,  etc.  Implementation-dependent.} 
rewrite  (out) ; 

writeln  (out,  *TPWRN>  #1.08  85-11-18  TEST  OF  POWERN  FUNCTION  RESULTS'); 
writeln (out) ; 

( _ : _ 1 _ : _ 2 _ : _ 3 _ : _ 4 _ : - 5 - :.} 

writeln  (out, 

writeln (out) ; 

ln7  :-  In  (7.0);  rv7  :-  1. 0/7.0; 

for  i  :-  0  to  17 
do  begin 

write (out,  i  :8,  PowerN (— 1, i)  :11:0); 
p7  :-  PowerN (7 .0,  i) ; 

{It  is  important  to  use  a  number  that  is  prime  to  the  floating-point 
radix.  Although  5  is  easier  to  check  mentally,  it  doesn't  show  enough 
about  accuracy  when  decimal  arithmetic  is  used,  as  with  Turbo-BCD.} 
write (out,  p7  :16:0); 

write (out.  PowerN  (rv7. -i)  -  p7  :20:13); 

{Use  the  known-to-be-inexact  reciprocal  to  show  how  errors  magnify} 
writeln (out,  exp(i*ln7)  -  p7  :21:13); 

{Show  deviation  of  the  inefficient  exp(i*ln(7))  on  the  same  basis} 
end; 

close (out) ; 

END. 


_ : _ 1 _ : _ 2 _ : _ 3 _ :.. 

i  <-l)**l  p  -  7**1 

..4 _ : _ 5 _ 

(1/7) **-i  -  p' 

exp  (i*ln  (7) )  -  p’>; 
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{  .  .  .  } 

{ 

TPWRN>  MODIFIED  #1.02  85-06-20  TEST  OF  POWERN  FUNCTION  RESULTS 


I 

(-1)** 

I  p  -  7**1 

(1/7) **-I  -  p 

exp(I*ln(7) )  -  p 

0 

1 

1 

0.0 

0.0 

1 

-1 

7 

0.0 

-0.0000000000  146 

2 

1 

49 

0.0000000000  582 

-0.000000000  3492 

3 

-1 

343 

0.000000000  9313 

-0.00000000  32596 

4 

1 

2401 

0.00000000  74506 

-0.0000000  298023 

5 

-1 

16807 

0.0000000  596046 

-0.000000  3874302 

6 

1 

117649 

0.000000  8344650 

-0.00000  26226044 

7 

-1 

823543 

0.00000  57220459 

-0.0000  362396240 

8 

1 

5764801 

0.0000  457763672 

-0.000  1296997070 

9 

-1 

40353607 

0.000  3662109375 

-0.000  9155273438 

10 

1 

282475249 

0.00  29296875000 

-0.0  126953125000 

11 

-1 

1977326743 

0.0  234375000000 

-0.0  859375000000 

12 

1 

13841287201 

0.  1875000000000 

-0.  6250000000000 

13 

-1 

96889010407 

1.  3750000000000 

-4.  2500000000000 

14 

1 

678223072850 

11.  0000000000000 

-58.  0000000000000 

15 

-1 

4747561509900 

80.  0000000000000 

-400.  0000000000000 

16 

1 

33232930570000 

640.  0000000000000 

-1472.  0000000000000 

17 

-1 

232630513990000 

4864.  0000000000000 

-20224.  0000000000000 

These  results  were  obtained  by  assign  (out,  ' TPWRN.PRN' )  and  compiling  with 
POWERN. PLB  #1.03.  CP/M-80  Turbo  Pascal  version  3.00A  was  used.  The  report 
file  was  then  incorporated  into  this  edition  of  TPWRN.PAS  as  part  of  final 
editing  as  a  MicroPro  WordStar  document.  (The  WordStar  edition  is  converted 
back  to  a  verified  compilable  form  by  "printing"  to  disk  and  filtering  out 
all  printing-control  information  using  a  simple  utility  program.)  The  num¬ 
bers  in  the  error  columns  have  been  doctored  by  addition  of  spacing  to  make 
the  growth  of  differences  easier  to  discern. 

Similar  results  should  be  obtained  using  MS-DOS,  CP/M-86  and  IBM  PC 
versions  of  Turbo  Pascal.  Turbo-8087  should  obtain  better  results  in  all 
columns  because  of  the  greater  precision  maintained  internally.  Turbo-BCD 
should  also  show  improvements,  with  decreased  speed,  after  the  last  column  is 
either  dropped  or  library  procedures  for  BCD  ln()  and  exp()  are  obtained. 
(For  Turbo-BCD  and  Turbo-8087  both,  it  is  instructive  to  increase  the  number 
of  decimal  positions  in  the  last  two  columns  in  order  to  see  what  error  there 
is,  however  much  smaller  it  turns  out  to  be.)  } 


(*  end  of  tpwrn.pas  *)  End  Listings 
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LISTING  ONE  (Text  begins  on  page  42) 


LISTING  1  -  Draw  Poker  Program  written  in  Ada 


begin 

Open_New (STOCK) ; 
loop 

put ("How  many  dollars  do  you  want  to  bet?  ");  get  (WAGER) ; 
exit  when  WAGER  -  0; 

Shuffle  (STOCK)  ; 

Open  New (PLAYERS  HAND); 
for  T  in  1  . .  5  loop 

Deal  A  Card  (PLAYERS_HAND,  STOCK) ; 
end  loUp T 
put (PLAYERS  HAND); 

Discard_FroHi(PLAYERS_HAND)  ; 
loop 

exit  when  Filled  (PLAYERS  HAND); 

Deal  A  Card  (PLAYERS_HAND7  STOCK)  ; 
end  loSp 7 
put  (PLAYERS  HAND); 

VALUE  VaTue  Of  (PLAYERS  HAND); 
case  VALUE  is  ~ 

when  ROYAL  FLUSH  ->  PAYOFF  250; 
when  STRAIGHT  FLUSH  ->  PAYOFF  50; 

when  FOUR  OF  A  KIND  ->  PAYOFF  25; 

when  FULL-HOUSE  ->  PAYOFF  6; 
when  FLUSH  ->  PAYOFF  5; 
when  STRAIGHT  ->  PAYOFF  4; 
when  THREE  OF  A  KIND  ->  PAYOFF  3; 
when  TWO  PAIR- -N  PAYOFF  2; 
when  othSrs  ->  PAYOFF  0; 
end  case; 
if  PAYOFF  -  0 

then  put  line ("Sorry,  you  lose."); 

else  putT'You  have  ")  ;put  (VALUE)  ;put  ("  I  ")  ;new  line; 

put ("You  win");  put (WAGER*PAYOFF) ;  put_lTne("  dollars!"); 

end  if; 
end  loop; 
end  Draw  Poker; 


End  Listing  One 


LISTING  TWO 


LISTING  2  -  The  general  form  of  a  procedure 

procedure  *1  is 
*2 

bejin 

exception 

*4 

end  *5; 


LISTING  THREE 


End  Listing  Two 


LISTING  3  -  The  Open_New  procedure 


procedure  Open  New (DECK  :  out  Decks)  is 
i  :  Integer  T-  0; 

CARD  :  Cards; 
begin 

for  S  in  Suits  loop 
for  R  in  Ranks  loop 
CARD. SUIT  S; 

CARD. RANK  R; 
i  i+1; 

DECK. FAN (i)  CARD; 

end  loop; 
end  loop; 

DECK. CARDS  LEFT  i; 

if  i  /-  CAHDS_IN_DECK  then  raise  DECK_ERROR;  end  if; 
exception 

—  CONSTRAINT  ERROR  or  DECK  ERROR  may  be  raised  by  this 

—  procedure  Tf  the  number  of  cards  In  a  deck  does  not 

—  equal  the  number  of  cards  generated, 
when  DECK  ERROR  I  CONSTRAINT  ERROR  -> 

raise  DECK_ERROR;  —  convert  all  errors  to  DECK_ERROR; 
end  Open_New; 


End  Listing  Three 


LISTING  FOUR  A 


Listing  4  (Part  A)  -  P LAY I NG_CARD S  package  specification 


CARDS. ADA 
19  JULY  1984 
DO-WHILE  JONES 

package  PLAYING_CARDS  is 

CARDS  IN  DECK  :  constant  integer  52; 

CARDS~IN^HAND  :  constant  integer  5; 

DECK  ERROR  :  exception;  —  raised  by  Open_New 

DECK”EXHAUSED  :  exception;  —  raised  by  Deal_A_Card 

HANDTULL  :  exception;  —  raised  by  Deal_A_Card 
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type  Suits  is  (CLUBS,  DIAMONDS,  HEARTS,  SPADES); 

type  Ranks  is  (TWO,  THREE,  FOUR,  FIVE,  SIX,  SEVEN,  EIGHT,  NINE,  TEN, 
JACK,  QUEEN,  KING,  ACE); 

type  Cards  is 
record 

SUIT  :  Suits; 

RANK  :  Ranks; 
end  record; 

type  Fans  is  array (integer  range  <>)  of  Cards; 

type  Status  is  array  (integer  range  <>)  of  boolean; 

type  Decks  is 
record 

CARDS  LEFT  :  integer; 

FAN  ”  :  Fans (1. ,CARDS_IN_DECK) ; 

end  record; 

type  Hands  is 
record 

PLAYED  :  Status (1. .CARDS  IN  HAND); 

FAN  :  Fans (1 . . CARDS_IN_HAND) ; 
end  record; 

function  Card_N umber (X  ;  integer;  HAND  :  Hands)  return  Cards; 

function  Played_Card_Number (X  :  integer;  HAND  :  Hands)  return  boolean; 

function  Suit_of(CARD  :  Cards)  return  Suits; 

function  Rank_of (CARD  :  Cards)  return  Ranks; 


procedure  put (SUIT  :  Suits); 
procedure  put (RANK  :  Ranks) ; 
procedure  put (CARD  :  Cards) ; 
procedure  put (HAND  :  Hands) ; 


procedure  Open  New (DECK  :  out  Decks);  —  create  a  new  deck 

procedure  ShufTle (DECK  :  in  out  Decks);  —  shuffle  a  deck 

procedure  Open  New (HAND  :  out  Hands);  —  create  a  new  hand 

procedure  Sort  "(HAND  :  in  out  Hands);  —  sort  by  rank,  ignore  suits 
procedure  Discard  From (HAND  :  in  out  Hands); 

function  Filled (HAND  ;  Hands)  return  boolean;  —  is  the  hand  full? 
procedure  Deal_A_Card (HAND  :  in  out  Hands;  DECK  :  in  out  Decks); 
end  PLAYING  CARDS; 


End  Listing  Four  A 

( Continued  on  neyt  page) 
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LISTING  FOUR  B  (Listing  continued;  text  begins  on  page  42) 


LISTING  4  (Part  B)  -  PLAYING_CARDS  package  body 


CARDB . ADA 
19  JULY  1984 
DO-WHILE  JONES 

with  CON  10;  use  CON  10; 

with  APL;  use  APL; 

package  body  PLAYING_CARDS  is 

CONSTRAINT_ERROR  ;  exception;  —  required  only  by  Maranatha  A 

function  Card_Number (X  :  integer;  HAND  :  Hands)  return  Cards  is 
begin 

return  HAND . FAN  (X) ; 
end  Card_Number; 

function  Played_Card_Number (X  :  integer;  HAND  :  Hands)  return  boolean  is 
begin 

return  HAND. PLAYED  (X) ; 
end  Played_Card_Number; 

function  Suit_of (CARD  :  Cards)  return  Suits  is 
begin 

return  CARD. SUIT; 
end  Suit_of; 

function  Rank_of (CARD  :  Cards)  return  Ranks  is 
begin 

return  CARD. RANK; 
end  Rank_of; 

Procedure  put (SUIT  :  Suits)  is 
agin 

case  SUIT  is 

when  CLUBS  »>  put ("CLUBS") ; 
when  DIAMONDS  ->  put  ("DIAMONDS" ) ; 
when  HEARTS  =>  put ("HEARTS") ; 
when  SPADES  ->  put ("SPADES") ; 
end  case; 
end  put; 


procedure  put (RANK  :  Ranks)  is 
begin 

case  RANK  is 

when  TWO  ->  put ("TWO") ; 
when  THREE  ->  put ("THREE" ) ; 
when  FOUR  ->  put ("FOUR"); 
when  FIVE  o  put ("FIVE") ; 
when  SIX  *=>  put  ("SIX"); 
when  SEVEN  ->  put ("SEVEN") ; 
when  EIGHT  «>  put ("EIGHT") ; 
when  NINE  ->  put ("NINE") ; 
when  TEN  “>  put ("TEN"); 
when  JACK  ->  put ("JACK") ; 
when  QUEEN  =>  put ("QUEEN") ; 
when  KING  »>  put ("KING"); 
when  ACE  ->  put ("ACE"); 
end  case; 
end  put; 

procedure  put (CARD  :  Cards)  is 
RANK  :  Ranks; 

SUIT  :  Suits; 

begin 

put (Rank_of (CARD) ) ;  put("  of  ");  put (Suit_of (CARD) ) ; 
end  put; 

procedure  put (HAND  :  Hands)  is 
begin 

for  i  in  1.. CARDS  IN  HAND  loop 

if  Played_Card  NumB'er (i, HAND)  then 

null;  —  don^t  display  a  card  that  isn't  there 
else 

put  (Card  Number (i, HAND) ) ; 

put  ("  'T;  —  separate  cards  with  two  blanks 

end  if; 
end  loop; 
new_line; 
end  put; 


procedure  Open_New (DECK  :  out  Decks)  is 
i  :  integer  :»  0; 

CARD  :  Cards; 
begin 

for  S  in  Suits  loop 
for  R  in  Ranks  loop 
CARD. SUIT  :=  S; 

CARD. RANK  R; 
i  i+1; 

DECK. FAN (i)  :=  CARD; 
end  loop; 
end  loop; 

DECK  CARDS  LEFT  • =  i • 

if  i’/*  CAKDS_IN_]_DECK  then  raise  DECK_ERROR;  end  if; 
exception 

—  CONSTRAINT  ERROR  or  DECK_ERROR  may  be  raised  by  this 

—  procedure  Tf  the  number  of  cards  in  a  deck  does  not 

—  equal  the  number  of  cards  generated, 
when  DECK  ERROR  |  CONSTRAINT  ERROR  => 
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raise  DDCK_ERROR;  —  convert  all  errors  to  DECK_ERROR; 
end  Open_New; 

procedure  Shuffle (DECK  :  in  out  Decks)  is 

SEQUENCE  :  Random  Sequence (1 . .CARDS  IN  DECK); 

TEMP  :  DECKS;-  “  - 

begin 

TEMP. CARDS  LEFT  :=  CARDS  IN  DECK; 

SEQUENCE  :=  Deal (CARDS  IN  DECK,  CARDS  IN  DECK) ; 
for  i  in  1.. CARDS  IN  DECK- Loop  -  - 

TEMP .FAN  (i)  :=  DECK. FAN (SEQUENCE (i) ) ; 
end  loop; 

DECK  :=  TEMP; 
end  Shuffle; 


procedure  Deal_A_Card (HAND  :  in  out  Hands;  DECK  :  in  out  Decks)  is 
X  :  integer  :=  0; 
begin 

—  find  an  empty  slot  in  the  hand 


A  . —  ATX , 

if  X  >  CARDS_IN  HAND  then  raise  HAND  FULL;  end  if; 
exit  when  Playe3_Card_Number (X,  HANDT; 
end  loop; 

—  draw  a  card  from  the  deck  and  put  it  in  the  empty  slot 
if  DECK. CARDS  LEFT  <1 

then  raise  DECK  EXHAUSED; 

else  DECK.CARDS- LEFT  :=  DECK. CARDS  LEFT-1; 
end  if; 

HMD. FAN  (X)  :=  DECK. FM  (CARDS  IN  DECK  -  DECK.CARDS  LEFT); 

HMD. PLAYED  (X)  :=  FALSE;  “  - 

end  Deal_A_Card; 

procedure  Sort  (HAND  :  in  out  Hands)  is 
SORTED  :  boolean; 

TEMP  :  Cards; 
begin 
loop 

SORTED  :=  TRUE; 

for  i  in  1.. CARDS  IN  HMD  loop 

if  Rank  of  (CarcTNumber  (i,  HAND))  >  Rank  of  (Card  Number (i+1,  HMD))  then 
TEMP  T=  Card  Number (i,  HAND) ; 

HAND .  FM  (i)  :=  Card  Number  (i+1,  HAND); 

HAND . FM  (i+1)  :=  TEMP; 

SORTED  :=  FALSE; 
end  if; 
end  loop; 
exit  when  SORTED; 
end  loop; 
end  Sort; 

(Continued  on  next  page) 
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LISTING  FOUR  B  (Listing  continued,  text  begins  on  page  42) 


Srocedure  Open_New (HAND  :  out  Hands)  is 
agin 

for  i  in  1.. CARDS  IN  HAND  loop 

HAND. PLAYED (i)  :=  TRUE;  —  hand  is  empty  (all  cards  have  been  played) 
end  loop; 
end  Open_New; 


procedure  D i sea rd_From (HAND  :  in  out  Hands)  is 
RESPONSE  :  character; 
begin 

for  i  in  1.. CARDS  IN_HAND  loop 

put ("Do  you  want  to  discard  the  "); 
put  (Card  Number  (i,  HAND)); 
put  ( " ?  (YVN)  "); 
get (RESPONSE) ;  new  line; 
if  RESPONSE  =  *  Y '  or  RESPONSE  =  'y' 
then  HAND. PLAYED (i)  :=  TRUE; 
end  if; 
end  loop; 
end  Discard_From; 

function  Filled (HAND  :  Hands)  return  boolean  is 
begin 

for  i  in  1.. CARDS  IN  HAND  loop 

if  Played  CardJRumber (i,  HAND)  then 

return  FALSE;  —  if  any  card  is  played,  hand  is  not  filled 
end  if; 
end  loop; 

return  TRUE;  —  if  no  cards  played,  hand  is  filled 
end  Filled; 


end  PLAYING  CARDS; 


End  Listing  Four  B 


LISTING  FIVE  A 


LISTING  5  (Part  A)  -  APL  package  specification 


APLS.ADA 
20  JULY  1984 
DO-WHILE  JONES 

This  package  simulates  some  APL  functions. 

Roll  (X)  returns  a  random  integer  in  the  range  1..X. 

Deal(X,Y)  returns  a  random  sequence  of  X  elements  all 
of  which  are  in  the  range  1..Y.  No  element  appears 
twice  in  the  random  sequence. 

package  APL  is 

subtype  positive  is  integer  range  1 .. integer ' last ; 

—  The  above  line  is  not  required  in  Ada. 

—  (It  is  required  for  Maranatha  A.) 

type  Random_Sequence  is  array (positive  range  <>)  of  positive; 

function  Roll  (LIMIT  :  positive)  return  positive; 

function  Deal (NUMBER,  LIMIT  :  positive)  return  Random_Sequence; 


End  Listing  Five  A 


LISTING  FIVE  B 


LISTING  5  (Part  B)  -  APL  package  body 


AP  LB . ADA 
20  JULY  1984 
DO-WHILE  JONES 

This  package  simulates  two  APL  functions. 

Note:  Roll  uses  the  RND  function  which  returns  a  random 
real  number  between  0.0  and  1.0.  The  RND  function  is 
implementation  specific  to  Maranatha  A. 

package  body  APL  is 

function  Roll (LIMIT  :  positive)  return  positive  is 
RANDOM  :  float; 
begin 

RANDOM  :=  float (LIMIT) *RND (0.0) ;  —  RND  is  implementation  specific, 

return  positive (RANDOM+0. 5) ; 
end  Roll; 

function  Deal (NUMBER,  LIMIT  :  positive)  return  Random_Sequence  is 
MAX  :  positive  :=  LIMIT; 

RS  :  Random  Sequence  (1 . .NUMBER) ; 

SOURCE  :  Random  Sequence  (1 .. LIMIT) ; 

RANDOM_INDEX  :  positive; 
begin 

for  i  in  1.. LIMIT  loop 

SOURCE (i)  :=  i;  —  SOURCE  has  one  of  every  number 
end  loop; 
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for  i  in  1.. NUMBER  loop 

RANDOM  INDEX  :=  Roll  (MAX) ; 

RS (i)  T=  SOURCE (RANDOM  INDEX);  --  pick  a  random  number  from  SOURCE 
for  j  in  RANDOM  INDEX. 7MAX-1  loop 

SOURCE (j)  :=  "SOURCE ( j+1) ;  —  remove  that  number  from  the  SOURCE 
end  loop; 

MAX  :=  MAX-1;  —  there  is  now  1  less  number  in  the  source  array 
end  loop; 
return  RS; 
end  Deal; 


End  Listing  Five  B 


LISTING  SIX 


LISTING  6  -  Complete  Draw  Poker  program 

DPOKER. ADA 
19  JULY  1984 
DO-WHILE  JONES 

with  CON  10;  use  CON  10; 

with  P LAY! N G_C ARD S ;  use  PLAYING_CARDS; 

procedure  Draw_Poker  is 

type  Values  is  (NOTHING,  TWO  PAIR,  THREE  OF  A  KIND,  STRAIGHT, 

FLUSH,  FULL_HOUSE,  FOUR_OF“A_KIND,  STRAIGffTTLUSH,  ROYAL_FLUSH) ; 

STOCK  :  Decks; 

PLAYERS  HAND  ;  Hands; 

WAGER,  PAYOFF  :  integer; 

VALUE  :  Values; 

procedure  put (X  :  Values)  is 
begin 

case  X  is 

when  TWO  PAIR  =>  put ("Two  Pair"); 
when  THREE  OF  A  KIND  =>  put ("Three  of  a  Kind"); 
when  STRAIGHT-^  put  ("a  Straight"); 
when  FLUSH  =>  put ("a  Flush"); 
when  FULL  HOUSE  =>  put ("a  Full  House"); 
when  FOUR  OF  A  KIND  =>  put ("Four  of  a  Kind"); 
when  STRAIGHT  FLUSH  =>  put ("a  Straight  Flush"); 
when  ROYAL  FLUSH  =>  put  ("a  Royal  Flush"); 
when  NOTHING  =>  put  ( 11  a  losing  hand"); 
end  case; 
end  put; 

function  Value_of (HAND  :  Hands)  return  Values  is  separate; 
begin 

OpenJNew (STOCK) ; 
loop 

put ("How  many  dollars  do  you  want  to  bet?  ") ;  get (WAGER) ; 
exit  when  WAGER  =0; 

Shuffle (STOCK) ; 

Open  New (PLAYERS  HAND); 
for  T  in  1  . .  5  loop 

Deal_A_Card ( P  LAYE  RS_HAND , STOCK) ; 
end  loop; 

put (PLAYERS  HAND); 

Discard_From  (PLAYERS_HAND)  ; 
loop 

exit  when  Filled (PLAYERS  HAND); 

Deal_A_Card(PLAYERS_HAND7  STOCK); 
end  loop; 

put (PLAYERS  HAND) ; 

VALUE  :=  VaTue  Of  (PLAYERS  HAND); 
case  VALUE  is 

when  ROYAL  FLUSH  =>  PAYOFF  :=  250; 
when  STRAIGHT  FLUSH  =>  PAYOFF  :=  50; 
when  FOUR  OF  A  KIND  =>  PAYOFF  :=  25; 
when  FULL- HOUSE  =>  PAYOFF  :=  6; 
when  FLUSH  =>  PAYOFF  :=  5; 
when  STRAIGHT  =>  PAYOFF  :=  4; 
when  THREE  OF  A  KIND  =>  PAYOFF  :=  3; 
when  TWO  PAIR-=^  PAYOFF  :=  2; 
when  others  =>  PAYOFF  :=  0; 
end  case; 
if  PAYOFF  =  0 

then  put  line  ("Sorry,  you  lose."); 

else  putT'You  have  Tl)  ;put  (VALUE)  ;put  ("!"); new  line; 

put ("You  win");  put (WAGER* PAYOFF ) ;  put  lTne("  dollars!"); 

end  if; 
end  loop; 
end  Draw  Poker; 

-  End  Listing  Six 


LISTING  SEVEN 


LISTING  7  -  Value_of  subprogram 


VALUE. ADA 
19  JULY  1984 
DO-WHILE  JONES 


separate  (Draw_Poker) ;  —  real  Ada  doesn't  have  a  semicolon  here 
function  Value  of (HAND  ;  Hands)  return  Values  is 


PATTERN  :  String (1. .CARDS  IN  HAND-1); 

X  :  Hands; 

function  Flush_in  (HAND  :  Hands)  return  boolean  is 


(Continued  on  nejct  page) 
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for  i  in  1.. CARDS  IN  HAND-1  loop 

if  Rank s' pos (Rank  of  (Card  Number (i,  HAND))) 

/=  Ranks  'pos  (RariTc_of  (Card_Number  (i+1,  HAND)))-1  then 
return  FALSE; 
end  if; 
end  loop; 
return  TRUE; 
end  Straight_in; 


begin 

X  :=  HAND;  —  make  a  copy  of  HAND  so  it  can  be  sorted 
Sort  (X)  ; 

for  i  in  1.. CARDS  IN  HAND-1  loop 

if  Rank  of  (Card- Number  (i,  X))  =  Rank  of  (Card  Number (i+1,  X))  then 
PATTERN  (i)  :=  'S';  —  adjacent  cards  have  'SAME  rank 
else 

PATTERN  (i)  :=  'D';  —  adjacent  cards  have  DIFFERENT  rank 
end  if; 
end  loop; 

if  Flush  in  (X)  and  Straight  in  (X)  then 

if  RanTc  of  (Card  Number  (4, “X) )  =  KING  then 
return  ROYAL_FLUSH; 
else 

return  STRAIGHT  FLUSH; 
end  if; 
end  if; 

if  PATTERN  =  "SSSD"  or  PATTERN  =  "DSSS"  then 
return  FOUR  OF  A  KIND; 
end  if; 

if  PATTERN  =  "SSDS"  or  PATTERN  =  "SDSS"  then 
return  FULL  HOUSE; 
end  if; 

if  Flush  in  (X)  then 
return- FLUSH; 
end  if; 

if  Straight  in(X)  then 
return  STRAIGHT; 
end  if; 

if  PATTERN  =  "SSDD"  or  PATTERN  =  "DSSD"  or  PATTERN  =  "DDSS"  then 
return  THREE  OF  A  KIND; 
end  if; 

if  PATTERN  =  "SDSD"  or  PATTERN  -  "DSDS"  or  PATTERN  =  "SDDS"  then 
return  TWO  PAIR; 
end  if; 

return  NOTHING; 

end  Value_of;  End  Listings 


MODULA-2 

LISTING  ONE  (Text  begins  on  page  62) 


MODULE  Sorter; 

(*  Sorter  utilizes  modules  RandomNumbers  and  Queues  to  demonstrate  *) 
(*  the  utility  of  data  abstraction.  *) 

FROM  InOut  IMPORT 

ClearScreen, 

Writelnt, 

WriteLn, 

WriteString; 


FROM  RandomNumbers 

IMPORT 

(*  PROC  *) 

randu; 

FROM  Queues  IMPORT 

(*  PROC  *) 

InitPriorityQueue 

QueueEmpty, 

Add, 

Fetch, 

(*  TYPE  *) 

PriorityQueue; 

VAR  Count  :  CARDINAL; 
x  :  INTEGER; 

Q  :  PriorityQueue; 

BEGIN  (*  MAIN  *) 

ClearScreen; 

InitPriorityQueue (Q)  ;  (*  Initialize  the  Priority  Queue  Q  *) 

(*  Add  100  pseudo-random  numbers  to  the  Priority  Queue  Q  *) 

FOR  Count  :=  1  TO  100  DO 
Add(Q,  randuO); 

END; 

(*  Empty  the  Priority  Queue  Q  and  display  each  removed  element  *) 
WriteLn; 

WriteLn; 

WriteString ("Sorted  Pseudo-Random  Numbers . ")  ; 

WriteLn; 

WHILE  NOT  QueueEmpty (Q)  DO 
x  :=  Fetch (Q); 

Writelnt  (x,  10); 

WriteLn 

END; 

END  Sorter. 


End  Listing  One 
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LISTING  TWO 


DEFINITION  MODULE  Queues; 

EXPORT  QUALIFIED 

(*  TYPE  *)  PrlorityQueue, 

(*  PROC  *)  InitPriorityQueue, 

Add, 

Fetch, 

QueueEmpty; 

TYPE  PrlorityQueue;  (*  Opaque  Type  *) 

PROCEDURE  I nit PrlorityQueue (VAR  Q  :  PriorityQueue); 

(*  Initializes  the  Priority  Queue  Q  *) 

PROCEDURE  Add (VAR  Q  ;  PrlorityQueue;  datum  :  INTEGER); 

(*  Adds  the  data  item  to  the  Priority  Queue  Q  *) 

PROCEDURE  Fetch (VAR  Q  :  PrlorityQueue)  ;  INTEGER; 

(*  Fetches  the  smallest  element  from  the  Priority  Queue  Q  *) 

PROCEDURE  QueueEmpty (Q  :  PrlorityQueue)  :  BOOLEAN; 

(*  QueueEmpty  RETURNS  TRUE  if  PrlorityQueue  Q  is  empty;  FALSE  otherwise  *) 
END  Queues. 


DEFINITION  MODULE  RandomNumbers; 

EXPORT  QUALIFIED 

(*  PROC  *)  randu; 

PROCEDURE  randu ()  :  INTEGER; 

(*  randu  RETURNS  a  pseudO-random  INTEGER  *) 

END  RandomNumbers. 

End  Listing  Two 


LISTING  THREE 


IMPLEMENTATION  MODULE  Queues; 

FROM  Storage  IMPORT  ALLOCATE,  DEALLOCATE; 

TYPE  PrlorityQueue  =  POINTER  TO  PriNode; 

PriNode  =  RECORD 

data  :  INTEGER; 
link  :  PrlorityQueue; 

END; 


PROCEDURE  InitPriorityQueue (VAR  Q  :  PriorityQueue) ; 

LISTING  FOUR 

BEGIN 

Q  :=  NIL 

END  InitPriorityQueue; 

IMPLEMENTATION  MODULE  Queues; 

PROCEDURE  Add (VAR  Q  :  PriorityQueue;  datum  :  INTEGER); 

FROM  Storage  IMPORT  ALLOCATE,  DEALLOCATE; 

VAR  T  :  PriorityQueue; 

BEGIN 

TYPE  PriorityQueue  =  POINTER  TO  PriNode; 

IF  QueueEmpty  (Q)  THEN 

PriNode  =  RECORD 

NEW  (Q) ; 

data  :  INTEGER; 

QA.link  :=  NIL; 

QA.data  :=  datum; 

link  :  PriorityQueue; 

END; 

ELSIF  datum  <  QA.data  THEN 

NEW  (T) ; 

TA.link  :=  Q; 

PROCEDURE  InitPriorityQueue (VAR  Q  :  PriorityQueue); 

TA.data  :=  datum; 

Q  :=  NIL 

Q  :=  T 

END  InitPriorityQueue; 

Add (QA. link,  datum) 

PROCEDURE  Add (VAR  Q  :  PriorityQueue;  datum  :  INTEGER) ; 

END; 

END  Add; 

VAR  T,  Tl,  NewNode  :  PriorityQueue; 

BEGIN 

IF  QueueEmpty (Q)  THEN 

PROCEDURE  Fetch (VAR  Q  :  PriorityQueue)  :  INTEGER; 

NEW  (Q)  ; 

VAR  tempi nt  :  INTEGER; 

QA.link  :=  NIL; 

tempQ  :  PriorityQueue; 

QA.data  :=  datum; 

BEGIN 

ELSIF  datum  <  QA.data  THEN 

tempo  :=  Q; 

NEW  (T) ; 

templnt  :=  QA.data; 

TA .  link  :=  Q; 

Q  :=  QA. link; 

DISPOSE  (tempQ)  ; 

Q  :=  T 

RETURN  templnt 

ELSE 

END  Fetch; 

T  :=  Q; 

WHILE  (T  #  NIL)  &  (datum  >=  TA.data)  DO 

PROCEDURE  QueueEmpty (Q  :  PriorityQueue)  :  BOOLEAN; 

Tl  :=  T; 

BEGIN 

T  :=  TA. link; 

RETURN  Q  =  NIL 

END; 

END  QueueEmpty; 

NEW (NewNode) ; 

NewNode A. link  :=  T; 

END  Queues. 

NewNodeA.data  :=  datum; 

TlA.link  :=  NewNode; 

END; 

IMPLEMENTATION  MODULE  RandomNumbers; 

END  Add; 

VAR  x  :  INTEGER; 

PROCEDURE  Fetch (VAR  Q  :  PriorityQueue)  :  INTEGER; 

PROCEDURE  randu  ()  :  INTEGER; 

VAR  templnt  :  INTEGER; 

BEGIN 

tempQ  :  PriorityQueue; 

x  :=  (3  *  x  +  31)  MOD  7; 

BEGIN 

RETURN  x 

tempQ  :=  Q; 

END  randu; 

templnt  QA.data; 

Q  :=  QA . link; 

BEGIN 

DISPOSE (tempQ) ; 

x  :=  7; 

RETURN  templnt 

END  Fetch; 

END  RandomNumbers. 

End  Listing  Three 
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PROCEDURE  QueueEmpty (Q  :  PriorityQueue)  :  BOOLEAN; 
BEGIN 

RETURN  Q  =  NIL 
END  QueueEmpty; 

END  Queues. 


IMPLEMENTATION  MODULE  RandomNumbers; 

VAR  x  :  INTEGER; 

PROCEDURE  randu()  :  INTEGER; 

BEGIN 

x  :=  (5  *  x  +  31)  MOD  4096; 
RETURN  x 
END  randu; 


END  RandomNumbers. 


End  Listings  I 


8080  SIMULATOR 


LISTING  TWO  (Continued  from  January) 

fullcy  add.b  /$60,rega 
ori  /I ,ccr 

enddaa  move  sr.regf 
swap  regcon0e 
and.w  regcon0f ,regf 
move.b  0(flagptr,regf .w) ,regf 
jmp  (return) 
nofull  tst.b  rega 
bra  enddaa 


bra  illegl 


;  28  Illegal  for  8080 


move.w  regh(regs) ,d0 
add.w  d0,regh(regs) 
bra  docyf 

move.b  1  (pseudopc) ,d0 
rol.w  /8,d0 
move . b  ( pseudopc ) , d0 
addq.l  /2, pseudopc 
move.l  d0,a0 
adda.l  targbase,a0 
move.b  (a0)+,regl(regs) 
move.b  (a0) .regh(regs) 

Jmp  (return) 

dec.w  regh(regs) 
jmp  (return) 

inc.b  regl(regs) 

move  sr,d0 

and.w  regcon0e,d0 

and.w  regcon01 ,regf 

or.b  0(flagptr,d0.w) ,regf 

jmp  (return) 


29  Dad  H 


;  2A  Lhld  addr 


;  2B  Dcx  H 


;  2C  Inr  L 
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dcrl 

dec.b  regl(regs) 
move  sr,d0 
and.w  regcon0e,d0 
and.u  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

;  2D  Dcr  L 

mvil 

move.b  (pseudopc)+,regl(regs) 
jmp  (return) 

;  2E  Mvi  L,nn 

cma 

not.b  rega 
jmp  (return) 

;  2F  Cma 

nop30 

bra  illegl 

;  30  Illegal  for  8080 

lxis 

move.b  1 (pseudopc) ,d0 
rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
move.l  d0,pseudosp 
adda.l  targbase, pseudosp 
jmp  (return) 

;  31  Lxi  S,nnnn 

sta 

move.b  1  (pseudopc) ,d0 

rol.w  /8,d0 

move.b  (pseudopc) ,d0 

addq.l  /2, pseudopc 

move.b  rega,0(targbase,d0.1) 

jmp  (return) 

;  32  Sta  addr 

inxs 

addq.l  /l.pseudosp 
jmp  (return) 

;  33  Inx  S 

inrm 

move.v  regh(regs) ,d0 
inc.b  0 (targbase, d0.1) 
move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w),regf 
jmp  (return) 

;  34  I nr  M 

derm 

move.w  regh(regs) ,d0 
dec.b  0(targbase,d0.1) 
move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

;  35  Dcr  M 

mvim 

move.w  regh(regs) ,d0 

move . b  (pseudopc ) + , 0 ( targbase , d0 . 1 ) 

jmp  (return) 

;  36  Mvi  M,nn 

stc 

bset  /0,regf 
jmp  (return) 

;  37  Stc 

nop38 

bra  illegl 

;  38  Illegal  for  8080 

dads 

move.l  pseudosp,d0 
sub . 1  targbase , d0 
add.w  d0,regh(regs) 
bra  docyf 

;  39  Dad  S 

Ida 

move.b  1 (pseudopc) ,d0 

rol.w  /8,d0 

move.b  (pseudopc) ,d0 

addq.l  /2, pseudopc 

move.b  0( targbase, d0.1) ,rega 

jmp  (return) 

;  3A  Lda  addr 

dexs 

subq.l  /l.pseudosp 
jmp  (return) 

;  3B  Dcx  S 

inra 

move . b  rega , regop 1 (r egs ) 
move.b  regcon01 ,regop2(regs) 
move.b  regcon0e,regop3(regs) 
inc.b  rega 
move  sr,d0 
and.w  regcon0e,d0 
and.w  regcon01 ,regf 
or.b  0(flagptr,d0.w) ,regf 

;  3C  Inr  A 

I  Continued  on  nejet  page) 
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8080  SIMULATOR 


LISTING  TWO  (Continued  from  January  ) 


jmp  (return) 

jmp  (return) 

dcra 

dec.b  rega 

;  3D  Dcr  A 

moveba 

move.b  rega.regb(regs) 

;  47  Mov  B,A 

move  sr,d0 

jmp  (return) 

and.u  regcon0e,d0 

and.u  regcon01 ,regf 

movecb 

move.b  regb(regs) ,regc(regs) 

;  48  Mov  C,B 

or.b  0(flagptr,d0.u) ,regf 

jmp  (return) 

jmp  (return) 

movecc 

move.b  regc(regs) .regc(regs) 

;  49  Mov  C,C 

mvia 

move.b  (pseudopc)+,rega 

;  3E  Mvi  A,nn 

jmp  (return) 

jmp  (return) 

movecd 

move.b  regd(regs) .regc(regs) 

;  4A  Mov  C,D 

cmc 

bchg  /0,regf 

;  3F  Cmc 

jmp  (return) 

jmp  (return) 

movece 

move.b  rege(regs) .regc(regs) 

;  4B  Mov  C,E 

movebb 

move.b  regb(regs) .regb(regs) 

;  40  Mov  B,B 

jmp  (return) 

jmp  (return) 

movech 

move.b  regh(regs) .regc(regs) 

;  4C  Mov  C,H 

movebc 

move.b  regc(regs) .regb(regs) 

;  41  Mov  B,C 

jmp  (return) 

jmp  (return) 

moved 

move.b  regl(regs) .regc(regs) 

;  4D  Mov  C,L 

movebd 

move.b  regd(regs) .regb(regs) 

;  42  Mov  B,D 

jmp  (return) 

jmp  (return) 

movecm 

move.w  regh(regs) ,d0 

;  4E  Mov  C,M 

movebe 

move.b  rege(regs) .regb(regs) 

;  43  Mov  B,E 

move.b  0(targbase,d0.1) .regc(regs) 

jmp  (return) 

jmp  (return) 

movebh 

move . b  regh ( regs ) , regb ( regs ) 

;  44  Mov  B,H 

moveca 

move.b  rega, regc (regs) 

;  4F  Mov  C, A 

Jmp  (return) 

jmp  (return) 

movebl 

move.b  regl(regs) ,regb(regs) 

;  45  Mov  B,L 

movedb 

move.b  regb(regs) .regd(regs) 

;  50  Mov  D,B 

jmp  (return) 

jmp  (return) 

movebm 

move.v  regh ( regs ) ,d0 

;  46  Mov  B,M 

movedc 

move.b  regc(regs) .regd(regs) 

;  51  Mov  D,C 

move.b  0(targbase,d0.1) .regb(regs) 

jmp  (return) 

movedd 

move.b  regd(regs) .regd(regs) 

;  52  Mov  D,D 

moveea 

move.b  rega, rege (regs) 

;  5F  Mov  E,A 

jmp  (return) 

jmp  (return) 

movede 

move.b  rege(regs) .regd(regs) 

;  53  Mov  D,E 

movehb 

move.b  regb(regs) .regh(regs) 

;  60  Mov  H,B 

jmp  (return) 

jmp  (return) 

movedh 

move.b  regh(regs) .regd(regs) 

;  54  Mov  D,H 

movehc 

move.b  regc(regs) .regh(regs) 

;  61  Mov  H.C 

jmp  (return) 

jmp  (return) 

movedl 

move.b  regl(regs) .regd(regs) 

;  55  Mov  D,L 

movehd 

move.b  regd(regs) .regh(regs) 

;  62  Mov  H,D 

jmp  (return) 

jmp  (return) 

movedm 

move.u  regh(regs) ,d0 

move.b  0(targbase,d0.1) .regd(regs) 

jmp  (return) 

;  56  Mov  D,M 

movehe 

move.b  rege(regs) .regh(regs) 
jmp  (return) 

;  63  Mov  H,E 

movehh 

move.b  regh(regs) .regh(regs) 

;  64  Mov  H,H 

moveda 

move.b  rega.regd(regs) 
jmp  (return) 

;  57  Mov  D,A 

jmp  (return) 

movehl 

move.b  regl(regs) ,regh(regs) 

;  65  Mov  H,L 

moveeb 

move . b  regb ( regs ) , rege ( regs ) 
jmp  (return) 

;  58  Mov  E,B 

jmp  (return) 

movehm 

move.w  regh(regs) ,d0 

;  66  Mov  H.M 

moveec 

move.b  regc(regs) .rege(regs) 

;  59  Mov  E,C 

move.b  0(targbase,d0.1) ,regh(regs) 

jmp  (return) 

jmp  (return) 

moveed 

move.b  regd(regs) .rege(regs) 

;  5A  Mov  E,D 

moveha 

move.b  rega.regh(regs) 

;  67  Mov  H.A 

jmp  (return) 

jmp  (return) 

raoveee 

move.b  rege(regs) .rege(regs) 

;  5B  Mov  E,E 

movelb 

move.b  regb(regs) .regl(regs) 

;  68  Mov  L,B 

jmp  (return) 

jmp  (return) 

moveeh 

move.b  regh(regs) .rege(regs) 

;  5C  Mov  E,H 

movelc 

move.b  regc(regs) .regl(regs) 

;  69  Mov  L,C 

jmp  (return) 

jmp  (return) 

moveel 

move.b  regl(regs) .rege(regs) 

;  5D  Mov  E,L 

moveld 

move.b  regd(regs) ,regl(regs) 

;  6A  Mov  L,D 

jmp  (return) 

jmp  (return) 

moveem 

move.w  regh(regs) ,d0 

;  5E  Mov  E,M 

movele 

move.b  rege(regs) .regl(regs) 

;  6B  Mov  L,E 

move.b  0(targbase,d0.1) .rege(regs) 

jmp  (return) 

jmp  (return) 

(Continued 

on  page  102) 
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8080  SIMULATOR 

LISTING  TWO  (Continued  from  January) 

movelh 

move.b  regh(regs) .regl(regs) 

;  6C  Mov  L.H 

addc 

move.b  regc(regs) ,d0 

;  81 

Add  C 

jmp  (return) 

move.b  d0,regop1 (regs) 
move.b  rega,regop2(regs) 

movell 

move.b  regl(regs) .regl(regs) 

;  6D  Mov  L,L 

move.b  regcon0e,regop3(regs) 

jmp  (return) 

add.b  d0,rega 
move  sr,d0 

movelm 

move.w  regh(regs) ,d0 

;  6E  Mov  L.M 

and.w  regcon0f,d0 

move.b  0 ( targbase, d0. 1) ,regl (regs) 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

jmp  (return) 

movela 

move.b  rega.regl(regs) 

;  6F  Mov  L.A 

addd 

move.b  regd(regs) ,d0 

;  82 

Add  D 

jmp  (return) 

move.b  d0 , regop 1 (regs) 
move.b  rega,regop2(regs) 

movemb 

move.w  regh(regs) ,d0 

;  70  Mov  M,B 

move.b  regcon0e,regop3(regs) 

move . b  regb ( regs ) , 0 ( targbase , d0 . 1 ) 

add.b  d0,rega 

jmp  (return) 

move  sr,d0 
and.w  regcon0f,d0 

movemc 

move.w  regh(regs) ,d0 

move . b  regc(regs ) , 0 ( targbase , d0 . 1 ) 

jmp  (return) 

;  71  Mov  M,C 

move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

adde 

move . b  rege ( regs ) , d0 

;  83 

Add  E 

movemd 

move.w  regh(regs) ,d0 

j  72  Mov  M,D 

move.b  d0,regop1 (regs) 

move.b  regd(regs) ,0(targbase,d0.1) 

move.b  rega,regop2(regs) 

jmp  (return) 

move.b  regcon0e,regop3(regs) 
add.b  d0,rega 

moveme 

move.w  regh(regs) ,d0 

;  73  Mov  M.E 

move  sr,d0 

move.b  rege(regs) ,0( targbase, d0. 1) 
jmp  (return) 

and.w  regcon0f,d0 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

movemh 

move.w  regh(regs) ,d0 

move.b  regh(regs) ,0(targbase,d0.1) 

;  74  Mov  M,H 

addh 

move.b  regh(regs) ,d0 

;  84 

Add  H 

jmp  (return) 

move.b  d0,regop1 (regs) 
move.b  rega, regop2( regs) 

moveml 

move.w  regh(regs) ,d0 

move . b  regl (regs ) , 0 ( targbase , d0 . 1 ) 

;  75  Mov  M.L 

move.b  regcon0e,regop3(regs) 
add.b  d0,rega 

jmp  (return) 

move  sr,d0 
and.w  regcon0f,d0 

halt 

bsr  service 

;  76  Hit 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

jmp  (return) 

movema 

move.w  regh(regs) ,d0 

;  77  Mov  M,A 

addl 

move.b  regl(regs) ,d0 

I  85 

Add  L 

move.b  rega,0(targbase,d0.1) 

move.b  d0 , regop 1 ( regs ) 

jmp  (return) 

move.b  rega,regop2(regs) 
move.b  regcon0e,regop3(regs) 

moveab 

move.b  regb(regs) ,rega 

;  78  Mov  A.B 

add.b  d0,rega 

jmp  (return) 

move  sr,d0 
and.w  regcon0f,d0 

moveac 

move.b  regc(regs) ,rega 

i  79  Mov  A.C 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

jmp  (return) 

movead 

move.b  regd(regs) ,rega 

;  7A  Mov  A,D 

addm 

move.w  regh(regs) ,d0 

;  86 

Add  M 

jmp  (return) 

;  7B  Mov  A,E 

move.b  0( targbase ,d0.1) ,d0 
move.b  d0,regop1 (regs) 

moveae 

move.b  rege(regs) ,rega 

move.b  rega,regop2(regs) 

jmp  (return) 

move.b  regcon0e,regop3(regs) 
add.b  d0,rega 

moveah 

move.b  regh(regs) ,rega 

;  7C  Mov  A,H 

move  sr,d0 

jmp  (return) 

and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 

moveal 

move . b  regl (regs ) , rega 
jmp  (return) 

;  7D  Mov  A.L 

jmp  (return) 

move.w  regh(regs) ,d0 

addaa 

move.b  rega, regop 1 (regs) 

;  87 

Add  A 

moveam 

;  7E  Mov  A.M 

move.b  rega,regop2(regs) 

move.b  0(targbase,d0.1) ,rega 

move.b  regcon0e,regop3(regs) 

jmp  (return) 

add.b  rega, rega 
move  sr,d0 

moveaa 

jmp  (return) 

;  7F  Mov  A, A 

and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 

addb 

move.b  regb ( regs ) ,d0 
move . b  d0 , regop 1 (regs ) 

;  80  Add  B 

jmp  (return) 

move.b  rega,regop2(regs) 

adcb 

move.b  regf ,regop3(regs) 

;  88 

Adc  B 

move.b  regcon0e,regop3(regs) 

asr.b  /I ,regf 

add.b  d0,rega 

move.b  regb ( regs ) ,d0 

move  sr,d0 

move.b  d0,regop1 (regs) 

and.w  regcon0f,d0 

move.b  rega,regop2(regs) 

move.b  0(flagptr,d0.w) ,regf 

moveq  /0,d1 

jmp  (return) 

addx.b  d0,rega 
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move  sr,d0 

move.b  0(flagptr,d0.w) ,regf 

and.w  regcon0f,d0 

jmp  (return) 

move.b  0(flagptr,d0.u) ,regf 

Jmp  (return) 

adch 

move.b  regf ,regop5(regs) 

;  8C  Adc  H 

asr.b  /I ,regf 

adcc 

move.b  regf ,regop3(regs) 

;  89  Adc  C 

move.b  regh(regs) ,d0 

asr.b  /I ,regf 

move.b  d0,regop1 (regs) 

move.b  regc(regs) ,d0 

move.b  rega,regop2(regs) 

move.b  d0,regop1 (regs) 

moveq  /0,d1 

move.b  rega,regop2(regs) 

addx.b  d0,rega 

moveq  /0,d1 

move  sr,d0 

addx.b  d0,rega 

and.w  regcon0f,d0 

move  sr,d0 

move.b  0(flagptr,d0.w),regf 

and.w  regcon0f,d0 

jmp  (return) 

move.b  0(flagptr,d0.u) ,regf 

jmp  (return) 

add 

move.b  regf ,regop3(regs) 

;  8D  Adc  L 

asr.b  /I ,regf 

adcd 

move.b  regf ,regop3(regs) 

;  8A  Adc  D 

move.b  regl(regs) ,d0 

asr.b  /I ,regf 

move.b  d0,regop1 (regs) 

move.b  regd(regs) ,d0 

move.b  rega,regop2(regs) 

move.b  d0,regop1 (regs) 

moveq  /0,d1 

move.b  rega,regop2(regs) 

addx.b  d0,rega 

moveq  /0,d1 

move  sr,d0 

addx.b  d0,rega 

and.w  regcon0f,d0 

move  sr,d0 

move.b  0(flagptr,d0.w) ,regf 

and.w  regcon0f,d0 

jmp  (return) 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

adcm 

move.b  regf ,regop3(regs) 

;  8E  Adc  M 

move.w  regh(regs) ,d0 

adce 

move.b  regf ,regop3 (regs) 

;  8B  Adc  E 

move.l  d0,a0 

asr.b  /I ,regf 

adda.l  targbase,a0 

move.b  rege(regs) ,d0 

asr.b  /l , regf 

move.b  d0,regop1 (regs) 

move.b  (a0),d0 

move.b  rega,regop2(regs) 

move.b  d0,regop1 (regs) 

moveq  /0,d1 

move.b  rega,regop2(regs) 

addx.b  d0,rega 

moveq  /0,d1 

move  sr,d0 

addx.b  d0,rega 

and.w  regcon0f,d0 

move  sr,d0 

( Continued 
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and.v  regcon0f,d0 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

adca  move.b  regf ,regop3(regs)  ;  8F  Adc  A 

asr.b  /I ,regf 
move.b  rega,d0 
move.b  d0,regop1 (regs) 
move.b  rega,regop2(regs) 
moveq  /0,d1 
addx.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

subb  move.b  regb(regs) ,d0  ;  90  Sub  B 

sub.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

subc  move.b  regc(regs) ,d0  ;  91  Sub  C 

sub.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.u) ,regf 
jmp  (return) 

subd  move.b  regd(regs) ,d0  ;  92  Sub  D 

sub.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

sube  move.b  rege(regs) ,d0  ;  93  Sub  E 

sub.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

subh  move.b  regh(regs) ,d0  ;  94  Sub  H 

sub.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

subl  move.b  regl(regs) ,d0  ;  95  Sub  L 

sub.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

subm  move.u  regh(regs) ,d0  ;  96  Sub  M 

move.b  0(targbase,d0.1) ,d0 
sub.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.u) ,regf 
jmp  (return) 

subaa  move.b  rega,d0  ;  97  Sub  A 

sub.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.u) ,regf 
jmp  (return) 

sbbb  asr.b  /I , regf  ;  98  Sbb  B 

move.b  regb(regs) ,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 


and.w  regcon0f,d0 

move.b  0(flagptr,d0.u) ,regf 

jmp  (return) 

sbbc  asr.b  /I, regf  ;  99  Sbb  C 

move.b  regc(regs) ,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

sbbd  asr.b  /I , regf  ;  9A  Sbb  D 

move.b  regd(regs) ,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.u) ,regf 
jmp  (return) 

sbbe  asr.b  /I, regf  ;  9B  Sbb  E 

move.b  rege(regs) ,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

sbbh  asr.b  /I, regf  ;  9C  Sbb  H 

move.b  regh(regs) ,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.u) ,regf 
jmp  (return) 

sbbl  asr.b  /I , regf  ;  9D  Sbb  L 

move.b  regl(regs) ,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

sbbm  move.u  regh(regs)  ,d0  ;  9E  Sbb  M 

move.l  d0,a0 
adda.l  targbase,a0 
asr.b  /I ,regf 
move.b  (a0),d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

sbba  asr.b  /I, regf  ;  9F  Sbb  A 

move.b  rega,d0 
moveq  /0,d1 
subx.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

andb  move.b  regb(regs) ,d0  ;  A0  Ana  B 

and.b  rega,d0 
move.b  d0,rega 
and.u  regconff,d0 
move.b  16(flagptr,d0.u) ,regf 
jmp  (return) 

andc  move.b  regc(regs)  ,d0  ;  A1  Ana  C 
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and.b  rega,d0 

and.b  rega,d0 

move.b  d0,rega 

move.b  d0,rega 

and.w  regconff,d0 

and.w  regconff,d0 

move.b  16(flagptr,d0.w) ,regf 

move.b  16(flagptr,d0.w) ,regf 

jmp  (return) 

jmp  (return) 

andd 

move.b  regd(regs) ,d0 

;  A2  Ana  D 

anda 

move.b  rega,d0 

;  A7  Ana  A 

and.b  rega,d0 

and.w  regconff,d0 

move.b  d0,rega 

move.b  16(flagptr,d0.w) ,regf 

and.w  regconff,d0 

jmp  (return) 

move.b  16(flagptr,d0.w) ,regf 

jmp  (return) 

xrab 

move.b  regb(regs) ,d0 

;  A8  Xra  B 

eor.b  d0,rega 

ande 

move.b  rege(regs) ,d0 

;  A3  Ana  E 

move.b  rega,d0 

and.b  rega,d0 

and.w  regconff,d0 

move.b  d0,rega 

move.b  16(flagptr,d0.w) ,regf 

and.w  regconff,d0 

jmp  (return) 

move.b  16(flagptr,d0.w) ,regf 

jmp  (return) 

xrac 

move.b  regc(regs) ,d0 

;  AA  Xra  C 

eor.b  d0,rega 

andh 

move.b  regh(regs) ,d0 

;  A4  Ana  H 

move.b  rega,d0 

and.b  rega,d0 

and.w  regconff,d0 

move.b  d0,rega 

move.b  16(flagptr,d0.w) ,regf 

and.w  regconff,d0 

jmp  (return) 

move.b  16(flagptr,d0.w),regf 

jmp  (return) 

xrad 

move.b  regd(regs) ,d0 

;  AA  Xra  D 

eor.b  d0,rega 

andl 

move.b  regl(regs) ,d0 

;  A5  Ana  L 

move.b  rega,d0 

and.b  rega,d0 

and.w  regconff,d0 

move.b  dfj.rega 

move.b  16(flagptr,d0.w) ,regf 

and.w  regconff,d0 

jmp  (return) 

move.b  16(flagptr,d0.w) ,regf 

jmp  (return) 

xrae 

move.b  rege(regs) ,d0 

;  AB  Xra  E 

eor.b  d0,rega 

andm 

move.w  regh(regs) ,d0 

;  A6  Ana  M 

move.b  rega,d0 

move.b  0(targbase,d0.1) ,d0 

and.w  regconff,d0 

(Continued  on  next  page) 
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move.b  I6(flagptr,d0.w) ,regf 
jmp  (return) 

xrah  move.b  regh(regs) ,d0 
eor.b  d0,rega 
move.b  rega,d0 
and.w  regconff,d0 
move.b  I6(flagptr,d0.w) ,regf 
jmp  (return) 

xral  move.b  regl(regs) ,d0 
eor.b  d0,rega 
move.b  rega,d0 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
jmp  (return) 

xrara  move.w  regh(regs) ,d0 

move.b  0(targbase,d0.1) ,d0 

eor.b  d0,rega 

move.b  rega,d0 

and.w  regconff,d0 

move.b  I6(flagptr,d0.w) ,regf 

Jmp  (return) 

xraa  moveq  /0,rega 

move.b  16(flagptr) ,regf 
Jmp  (return) 

orab  move.b  regb(regs) ,d0 

or.b  rega,d0 
move.b  d0,rega 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
jmp  (return) 


;  AC  Xra  H 


;  AD  Xra  L 


i  AE  Xra  M 


;  AF  Xra  A 


;  B0  Ora  B 


orac  move.b  regc(regs) ,d0 
or.b  rega,d0 
move.b  d0,rega 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
Jmp  (return) 

orad  move.b  regd(regs) ,d0 

or.b  rega,d0 
move.b  d0,rega 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
jmp  (return) 

orae  move.b  rege(regs) ,d0 

or.b  rega,d0 
move.b  d0,rega 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
jmp  (return) 

orah  move.b  regh(regs) ,d0 
or.b  rega,d0 
move.b  d0,rega 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
jmp  (return) 

oral  move.b  regl(regs) ,d0 
or.b  rega,d0 
move.b  d0,rega 
and.w  regconff,d0 
move.b  16(flagptr,d0.w) ,regf 
Jmp  (return) 

oram  move.w  regh(regs) ,d0 

move.b  0(targbase,d0.1) ,d0 

or.b  rega,d0 

move.b  d0,rega 

and.w  regconff,d0 

move.b  16(flagptr,d0.u) ,regf 

jmp  (return) 


oraa  move.b  rega,d0 

and.w  regconff,d0 

move.b  16(flagptr,d0.w) ,regf 

jmp  (return) 


j  B1  Ora  C 


;  B2  Ora  D 


;  B?  Ora  E 


;  B4  Ora  H 


;  B5  Ora  L 


;  B6  Ora  M 


;  B7  Ora  A 


cmpb  cmp.b  regb(regs) ,rega  ;  B8  Cmp  B 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

cmpc  cmp.b  regc(regs) ,rega  ;  BB  Cmp  C 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

cmpd  cmp.b  regd(regs) ,rega  ;  BA  Cmp  D 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w),regf 
jmp  (return) 

cmpe  cmp.b  rege(regs) ,rega  ;  BB  Cmp  E 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

cmph  cmp.b  regh(regs) ,rega  ;  BC  Cmp  H 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 
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cmpl  cmp.b  regl (regs) ,rega  ;  BD  Cmp  L 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf . 
jmp  (return) 

cmpam  move.w  regh(regs) ,d0  ;  BE  Cmp  M 

move.l  d0,a0 
adda.l  targbase,a0 
cmp.b  (a0),rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

cmpaa  cmp.b  rega.rega  ;  BF  Cmp  A 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

rnz  btst  /6,regf 

bne  mloop 

ret  move.b  1 (pseudosp) ,d0 

rol.w  /8,d0 
move.b  (pseudosp) ,d0 
addq.l  /2, pseudosp 
lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 


popb  move.b  (pseudosp)+,regc(regs)  ;  Cl  Pop  B 

move.b  (pseudosp)+,regb(regs) 
jmp  (return) 

jnz  move.b  1 (pseudopc) ,d0  ;  C2  Jnz  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /6,regf 


bne  mloop 

lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

jmpa  move.b  1 (pseudopc) ,d0  ;  C3  Jmp  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
lea.l  0(targbase,d0. 1) .pseudopc 
jmp  (return) 

cnz  move.b  1 (pseudopc) ,d0  ;  C4  Cnz  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /6,regf 
bne  mloop 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 

move.b  di ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  0(targbase,d0.1), pseudopc 
jmp  (return) 

pushb  move.b  regb (regs) .-(pseudosp)  ;  C5  Push  B 

move.b  regc(regs) .-(pseudosp) 
jmp  (return) 

adi  move.b  (pseudopc)+,d0  ;  C6  Adi  nn 

move.b  d0,regop1 (regs) 
move.b  rega,regop2(regs) 
move.b  regcon0e,regop3(regs) 
add.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 
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rst0  move.l  pseudopc, dl  ;  C7  Rst  0 

sub.l  targbase.dl 
move . b  dl , -2 ( pseudosp ) 
rol.w  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
move.l  targbase, pseudopc 
jmp  (return) 

rz  btst  /6,regf  ;  C8  Rz 

beq  mloop 

move.b  1 (pseudosp) ,d0 

rol.w  /8,d0 

move.b  (pseudosp) ,d0 

addq.l  /2, pseudosp 

lea.l  0(targbase,d0.1) .pseudopc 

jmp  (return) 

jz  move.b  1 (pseudopc) ,d0  ;  CA  Jz  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /6,regf 
beq  mloop 

lea.l  0 (tar gbase,d0.1) .pseudopc 
jmp  (return) 

nopCB  bra  illegl  ;  CB  Illegal 

for  8080 

cz  move.b  1  (pseudopc) ,d0  ;  CC  Cz  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 


btst  /6,regf 
beq  mloop 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  0( targbase, d0.1) .pseudopc 
jmp  (return) 

call  move.b  1 (pseudopc) ,d0  ;  CD  Call  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

aci  move.b  regf ,regop3(regs)  ;  CE  Aci  nn 

asr.b  /I ,regf 
move.b  (pseudopc)+,d0 
move.b  d0,regop1 (regs) 
move.b  rega,regop2(regs) 
moveq  /0,d1 
addx.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
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move.b  0(flagptr,d0.w) ,regf 
jmp  (return) 

rst8  move.l  pseudopc.dl  ;  CF  Rst  8 

sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  $8(targbase) .pseudopc 
jmp  (return) 

rnc  btst  /0,regf  ;  D0  Rnc 

bne  mloop 

move.b  1 (pseudosp) ,d0 

rol.w  /8,d0 

move . b  (pseudosp ) , d0 

addq.l  /2, pseudosp 

lea.l  0(targbase,d0. 1) .pseudopc 

jmp  (return) 

popd  move.b  (pseudosp)+,rege(regs)  ;  Dl  Pop  D 

move.b  (pseudosp)+,regd(regs) 
jmp  (return) 

jnc  move.b  1 (pseudopc) ,d0  ;  D2  Jnc  addr 

rol.w  /8,d0 
move . b  (pseudopc ) , d0 
addq.l  /I, pseudopc 
btst  /0,regf 
bne  mloop 

lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

out  moveq  /0,d0  ;  D3  Out  nn 

move.b  (pseudopc)+.d0 

ifne  disklo 
cmp.b  /$54,d0 


beq  outspec 
cmp.b  /$55,d0 
beq  outspec 
endc 

move.l  Z$ff0000,a0 
move.b  rega,0(a0,d0.1) 
jmp  (return) 

cnc  move.b  1 (pseudopc) ,d0  ;  D4  Cnc  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /0,regf 
bne  mloop 
move.l  pseudopc.dl 
sub.l  targbase.dl 
move . b  dl , -2 ( pseudosp ) 
rol.w  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

pushd  move.b  regd(regs) .-(pseudosp)  ;  D5  Push  D 

move.b  rege(regs) .-(pseudosp) 
jmp  (return) 

sui  move.b  (pseudopc)+,d0  ;  D6  Sui  nn 

sub.b  d0,rega 
move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w) ,regf 
Jmp  (return) 

rst 10  move.l  pseudopc.dl  ;  D7  Rst  10 

sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 
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move.b  dl ,-1 (pseudosp) 

addq.l  /2, pseudopc 

subq.l  /2, pseudosp 

btst  /0,regf 

lea.l  $10(targbase) .pseudopc 

beq  mloop 

jmp  (return) 

move.l  pseudopc.dl 
sub.l  targbase.dl 

rc 

btst  /0,regf 

;  D8  Rc 

move.b  dl  ,-2(pseudosp) 

beq  mloop 

rol.w  /8,d1 

move.b  1 (pseudosp) ,d0 

move.b  dl ,-1 (pseudosp) 

rol.w  /8,d0 

subq.l  /2, pseudosp 

move.b  (pseudosp) ,d0 

lea.l  0(targbase,d0.1) .pseudopc 

addq.l  /2, pseudosp 

jmp  (return) 

lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

nopDD 

bra  Illegl 

;  DD  Illegal 

for  8080 

nopD9 

bra  illegl 

;  D9  Illegal 

for  8080 

sbi 

asr.b  /I ,regf 
move.b  (pseudopc)+,d0 

;  DE  Sbi  nn 

jc 

move.b  1 (pseudopc) ,d0 

;  DA  Jc  addr 

moveq  /0,d1 

rol.w  /8,d0 

subx.b  d0,rega 

move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /0,regf 
beq  mloop 

lea.l  0(targbase,d0.1) .pseudopc 

move  sr,d0 

and.w  regcon0f,d0 

move.b  0(flagptr,d0.w) ,regf 

jmp  (return) 

jmp  (return) 

rst18 

move.l  pseudopc.dl 

;  DF  Rst  18 

in 

moveq  /0,d0 

;  DB  In  nn 

sub.l  targbase.dl 

move.b  (pseudopc)+,d0 

move . b  dl , -2 (pseudosp ) 

move.l  /$ff0000,a0 

rol.w  /8,d1 

move.l  0(a0,d0. 1) ,rega 
jmp  (return) 

move.b  dl ,-1 (pseudosp) 

subq.l  /2, pseudosp 

lea.l  $18(targbase) .pseudopc 

cc 

move.b  1 (pseudopc) ,d0 

;  DC  Cc  addr 

Jmp  (return) 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 

rpo 

btst  /2,regf 

;  E0  Rpo 
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bne  mloop 

rol.w  /8,d1 

move.b  1 (pseudosp) ,d0 

move.b  dl  ,-1 (pseudosp) 

rol.w  /8,d0 

subq.l  /2, pseudosp 

move.b  (pseudosp) ,d0 

lea.l  0(targbase,d0.1) .pseudopc 

addq.l  if  2, pseudosp 

jmp  (return) 

lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

pushh 

move.b  regh(regs) .-(pseudosp) 

;  E5  Push  H 

poph 

move.b  (pseudosp)+,regl(regs) 
move.b  (pseudosp)+,regh(regs) 
jmp  (return) 

;  El  Pop  H 

move.b  regl(regs) .-(pseudosp) 
jmp  (return) 

anl 

and.b  (pseudopc)+,rega 

;  E6  Ani  nn 

JP° 

move.b  1 (pseudopc) ,d0 

;  E2  Jpo  addr 

move.b  rega,d0 

rol.u  /8,d0 

and.w  regconff,d0 

move.b  (pseudopc) ,d0 

move.b  16(flagptr,d0.w) ,regf 

addq.l  /2, pseudopc 
btst  /2,regf 

jmp  (return) 

bne  mloop 

lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

rst20 

move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 

;  E7  Rst  20 

xthl 

move.b  regl(regs) ,d0 

;  E3  Xthl 

move.b  dl ,-1 (pseudosp) 

move.b  (pseudosp) .regl(regs) 

subq.l  /2, pseudosp 

move.b  d0, (pseudosp) 

lea.l  $20(targbase) .pseudopc 

move.b  regh(regs) ,d0 
move.b  1 (pseudosp) .regh(regs) 

Jmp  (return) 

;  E8  Rpe 

move.b  d0,1 (pseudosp) 

Jmp  (return) 

rpe 

btst  /2,regf 
beq  mloop 

move.b  1  (pseudosp) ,d0 

cpo 

move.b  1 (pseudopc ) ,d0 

;  E4  Cpo  addr 

rol.w  /8,d0 

rol.w  /8,d0 

move.b  (pseudosp) ,d0 

move.b  (pseudopc) ,d0 

addq.l  /2, pseudosp 

addq.l  /2, pseudopc 

lea.l  0(targbase,d0.1) .pseudopc 

btst  /2,regf 
bne  mloop 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 

jmp  (return) 

(To  be  continued  in  March ) 
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LISTING  ONE  (Text  begins  on  page  114) 


P LOT DOT . OBJ  Library  module  for  Microsoft  C  (small  model  programs) 

by  Dan  Rollins 

Mid-resolution  graphics  pixel-plot  function. 

Uses  look-up  tables  for  fastest  operation. 

Permission  is  granted  to  use  this  for  any  purpose  whatsoever, 
synopsis: 

plotdot (x, y , color ) 

int  x;  horizontal  (0-319)  not  value-checked 

int  y;  vertical  (0-199)  not  value-checked 

int  color;  color  for  dot  (0  to  3) 


- -  preamble  for  placing  data  into  Microsoft  C  'S  model'  static  data  area 

dgroup  group  data 

data  segment  word  public  1  data  1 


lookup  table  for  start  of  each  graphics  line 

index  is:  (Y  *  2) 

label  word 

addr  -  0 

rept  100 

dw  addr, addr+2000H  ; Y-0,1;  2,3;  4,5;  etc 
addr  -  addr+80 
endm 


- -  lookup  table  for  mid-res  pixel  positions  in  relevent  byte 

. - index  is:  (X  mod  4) 

mask_tbl  db  00111111b,  11001111b,  11110011b,  11111100b 

; -  lookup  table  for  color,  according  to  position  in  byte 

. - index  is  (COLOR  *  4)  +  (X  mod  4) 

color_tbl  db  00000000b,  00000000b,  00000000b,  00000000b  ;color  0 

db  01000000b,  00010000b,  00000100b,  00000001b  ;color  1 

db  10000000b,  00100000b,  00001000b,  00000010b  ;color  2 

db  11000000b,  00110000b,  00001100b,  00000011b  ;color  3 

data  ends 


preamble  for  placing  code  into  Microsoft  C  'S  model'  program  area 
group  prog 

segment  byte  public  'prog' 
assume  cs:pgroup,  ds: dgroup 


public  plotdot 
plotdot  proc 


proc  near  .-SMALL  MODEL  ONLY 

pop  si  ; fetch  return  addr  /this  technique  is  faster 

pop  bx  ; fetch  X  ordinate  /than  stack-relative  access 

pop  di  ; fetch  Y  ordinate 

pop  cx  ; fetch  color 

mov  dx,  es  .-save  current  ES 

mov  ax, 0b800H 

mov  es,ax  ;get  set  to  write  to  video  buffer 

shl  di,l  ; index  into  row  address  lookup  table 

mov  di, row_tbl [di]  ;DI  points  to  start  of  selected  row 

mov  ax,bx  .-copy  the  X  ordinate 

shr  ax,  1 

shr  ax,l  .-divided  by  4  is  byte  offset  from  start  of  row 

add  di,ax  ;DI  points  to  byte  to  modify 

mov  al,e8:[di]  ; fetch  current  screen  byte 

and  bx, 3  .-get  pixel-offset  in  byte  (0,1,2,  or  3) 

and  al,mask_tbl[bx]  .-mask  a  "hole"  into  the  current  byte 

index  into  the  color  table 

and  cx, 3  .-make  sure  it's  a  valid  color 

shl  cx,  1  ;  COLOR  *  2 

shl  cx, 1  ;  COLOR  *  4 

add  bx, cx  ;  index  is  (COLOR  *  4)  +  (X  mod  4) 

or  al, color  tbl[bx]  .-fill  the  "hole"  with  selected  color 


mov 

jmp 

plotdot  endp 
prog  ends 


es : [di] , al 
es,  dx 
si 


; place  modified  byte  back  into  screen 
.-restore  caller's  ES 

; artificial  (quick)  NEAR  return  to  caller 


End  Listing  One 


LISTING  TWO 


LINE . C 

by  Dan  Rollins 

Uses  incremental  algorithm  and  fast  ASM  plotdot 

Permission  is  granted  to  use  this  for  any  purpose  whatsoever. 

**************l*****1»********IH*************t********1****l************* 

_main (arglin)  /*  this  just  skips  the  'main'  function  altogether  */ 
char  *arglin;  /*  points  to  the  DOS  command  line  */ 

{ 

int  x, y; 

dmode(l);  /*  enter  text  mode  first  (so  screen  will  clear)  */ 
dmode(4);  l*  mid-res  color  graphics  mode  */ 
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/*  test  the  line  algorithm  by  drawing  in  all  directions,  colors  */ 

for  (x-0;  x<320;  x+-4)  plotline (160, 100,  x,  0,  3); 

for  (y-0;  y<200;  y+-4)  plotline  (160, 100, 319,  y,  2); 

for  (x-319;  x>-0;  x — 4)  plotline (160, 100,  x, 199,  1); 

for  (y-199;  y>-0;  y— 4)  plotline  (160, 100,  0,  y,  2); 


getch();  /*  pause  till  key  is  pressed  */ 
dmode(2);  /*  re-enter  text  mode  */ 


/ *  ****************************************************************** 


PLOTLINE (xl,yl,x2,y2,  color) 

draws  a  line  from  (xl,yl)  to  (x2,y2)  in  specified  color  (0  to  3) 
calls  1 plotdot'  (a  fast,  mid-resolution  pixel-plotting  routine) 

A******************************************************************  * / 


plotline (xl,yl, x2,y2,  color) 
int  xl,yl;  /*  starting  point  */ 
int  x2,y2;  /*  ending  point  */ 

int  color; 

( 

/*  use  static  variables  for  fastest  'access 
static  int  lg_delta,  sh_delta;  /*  distance  of  long,  short  axis  */ 
static  int  lg_step,  sh_step;  /*  0,  1  or  -1  */ 
static  int  cycle;  /*  decision  variable  */ 

static  int  temp;  /*  swapping  variable  */ 


V 


lg_delta  -  x2-xl; 
if  (lg_delta  >-  0) 
lg_step  -  1; 
else  { 

lg_delta  -  -lg_delta; 
lg_step  -  -1; 


/*  get  travel  along  X  axis  */ 


/*  get  absolute  value  */ 
/*  reverse  direction  */ 


sh_delta  -  y2-yl; 
if  (sh_delta  >-  0) 
sh_step  -  1; 
else  ( 

sh_delta  -  -sh_delta; 
sh_step  -  -1; 


/*  get  travel  along  Y  axis  */ 


/*  get  absolute  value  */ 
/*  reverse  direction  */ 


if  (sh_delta  >  lg_delta)  {  /*  if  Y  axis  is  longer,  swap  axes  */ 

cycle  -  sh_delta  >>  1; 

temp  -  lg_delta;  lg_delta  -  sh_delta;  sh_delta  -  temp; 
temp  -  lg_step;  lg_step  -  sh_step;  sh_step  -  temp; 


while  (yl  !-  y2)  ( 
plotpix (xl,yl, color) ; 
yl  +-  lg_step; 
cycle  +-  sh_delta; 
if  (cycle  >-  lg_delta) 
cycle  —  lg_delta; 
xl  +-  sh_step; 

) 

) 

) 

else  ( 

cycle  -  lg_delta  >>  1; 
while  (xl  !-  x2)  { 
plotpix (xl,yl, color) ; 
xl  +-  lg_step; 
cycle  +-  sh_delta; 
if  (cycle  >-  lg_delta) 
cycle  —  lg_delta; 
yl  +-  sh_step; 

) 

)  /*  end  of  while  */ 

)  /*  end  of  else  (for  axis 
)  I*  end  of  plotline  */ 


/*  loop  for  "vertical"  line  */ 

/*  always  bump  line  pointer  */ 

/*  bump  decision  variable  */ 

(  /*  past  decision  threshold?  */ 

/*  reset  for  next  decison  cycle  */ 
/*  bump  column  pointer  */ 


/*  X  axis  is  longer,  so  don't  swap 
/*  loop  for  "horizontal"  line  */ 


( 


swap)  */ 


*/ 


/ *  ****************************************************************** 

DMODE (mode) 

sets  the  display  mode 

mode  is:  0  -  bw  40x25  text  4  -  color  320x200  graphics 

1  -  color  40x25  text  5  -  bw  320x200  graphics 

2  -  bw  80x25  text  6  -  bw  640x200  graphics 

3  -  color  80x25  text 

dmode  (m) 
int  m; 

{ 

struct  XREGS {  int  ax,bx,cx, dx;  )  regbuf; 
regbuf.ax  -  m;  /*  AH  -  0,  AL  -  mode  */ 
int 86 ( 0x10, sregbuf , &regbuf ) ; 

} 

End  Listings 
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16-BIT  SOFTWARE  TOOLBOX 


Recommended  Software 

I  have  been  reading  about  the  Small¬ 
talk  language  with  interest  for  years, 
but  I  couldn't  quite  see  my  way  clear 
to  applying  for  a  job  at  Xerox’s  Palo 
Alto  Research  Center  (PARC)  just  so  I 
could  play  with  it.  METHODS  from  Di- 
gitalk  is  a  true  implementation  of 
Smalltalk  for  the  IBM  PC  (it  can  t  be 
marketed  with  the  name  Smalltalk 
because  of  trademark  consider¬ 
ations)  at  a  reasonable  price. 

Smalltalk  proper  is  an  object-ori¬ 
ented  programming  language,  but 
Smalltalk  as  people  usually  talk 
about  it  transcends  "mere”  coding  to 
become  both  an  environment  and  a 
philosophy  for  programming.  The 
Smalltalk  research  and  related  work 
at  Xerox's  PARC  have  become  the  ba¬ 
sis  for  the  much  ballyhooed  Macin¬ 
tosh  user  interface  and  the  other 
windowed,  "user-friendly”  operat¬ 
ing  system  interfaces  that  are  begin¬ 
ning  to  show  up  on  microcomputers. 
Many  of  its  concepts  were  also  inco- 
porated  into  the  language  Neon, 
which  was  developed  for  the  Macin¬ 
tosh  by  Kriya  Software  in  Chicago. 

METHODS  comes  with  an  excellent 
550-page  manual  that  leads  you  gent¬ 
ly  into  this  brave  but  strange  new 
world  of  object-oriented  program¬ 
ming.  METHODS'  screen  performance 
is  snappy  although  the  implemen¬ 
tors  had  to  give  up  support  for  bit¬ 
mapped  graphics  to  attain  it;  disk  per¬ 
formance  is  OK,  but  I  highly 
recommend  a  (large)  hard  disk.  The 
arrow  keys  and  special-function  keys 
are  used  in  a  comfortable  way  to  con¬ 
trol  the  windows,  and  you  can  get 
along  without  a  mouse  quite  nicely — 
although  a  mouse  may  be  used  when 
available. 

Readers  interested  in  learning 


by  Ray  Duncan 


more  about  Smalltalk  should  see  the 
August  1981  special  issue  of  Byte  and 
the  following  books: 


Goldberg,  Adele.  Smalltalk-80,  the  In¬ 
teractive  Programming  Environment. 
Addison-Wesley,  1984. 

Smalltalk-80,  Bits  of  History,  Words  of 
Advice.  Glenn  Krasner  ed.  Addison- 
Wesley,  1983. 

Goldberg,  Adele,  and  Robson,  David. 
Smalltalk-80,  the  Language  and  its  Im¬ 
plementation.  Addison-Wesley,  1983. 

METHODS  can  be  purchased  for 
$250  from  Digitalk  Inc.,  5200  West 
Century  Blvd.,  Los  Angeles,  CA  90045; 
(213)  645-1082. 

Additional  Recommended 
Software 

Two  days  after  I  received  a  copy  of 
Microsoft  C,  Version  3.0,  I  had  aban¬ 
doned  my  Lattice  C  compiler  forev¬ 
er.  The  new  Microsoft  compiler  gen¬ 
erates  .EXE  files  that  are  half  the  size 
of  the  files  generated  by  Lattice  C — 
and  faster  besides.  Microsoft  C  fea¬ 
tures  extremely  good  integration 
with  the  functions  of  MS  DOS  (as  you 
would  expect,  or  at  least  hope  for), 
including  easy  access  to  the  environ¬ 
ment  block  and  memory  manage¬ 
ment,  full  path  support,  and  several 
variations  on  the  exec  function.  I  par¬ 
ticularly  like  the  compiler’s  use  of 
SET  strings  in  the  environment  to 
find  its  libraries  and  include  files. 

The  Microsoft  C  floating  point  li¬ 
braries  use  the  8087  or  80287  numer¬ 
ic  coprocessor  automatically  when  it 
is  available,  or  in-line  8087  code  can 
be  generated.  Unlike  Lattice  C,  a  true 
assembly-language  source  file  can  be 
selected  as  the  output  from  the  C 
compiler,  which  may  be  hand-opti¬ 
mized  and  then  fed  to  the  Microsoft 


Macro  Assembler.  The  documenta¬ 
tion  for  the  compiler,  in  two  vol¬ 
umes,  is  far  and  away  the  best  I’ve 
seen.  I  guess  you  all  know  where  to 
find  Microsoft,  so  I  won’t  print  its  ad¬ 
dress  and  phone  number  here. 

Pro-CED  by  Chris  Dunford  (contrib¬ 
utor  of  many  great  programs  to  the 
public  domain,  including  the  BURN¬ 
OUT  utility)  is  a  command-line  editor 
for  PC-DOS  with  many  powerful  fea¬ 
tures  including  a  command  stack 
that  allows  you  to  recall  and  edit  pre¬ 
viously  entered  commands  for  reen¬ 
try  command  synonyms  that  allow 
you  to  abbreviate  often-used  com¬ 
mands  to  a  few  letters  or  symbols, 
the  ability  to  chain  frequently  used 
commands  together  without  batch 
files,  and  on-line  help.  Pro-CED  comes 
with  an  excellent  manual  and  is 
available  for  $35  from  Chris  Dunford 
at  P.O.  Box  1072,  Columbia,  MD  21044; 
(301)  992-9371. 

Expanding  the 
Environment 

The  default  environment  block  pro¬ 
vided  by  COMMAND.COM  is  not  very 
big,  and  when  you  start  to  use  pro¬ 
grams  that  require  several  SET  strings 
(such  as  the  Microsoft  C  compiler), 
you  may  find  that  you  exhaust  the 
available  environment  space  before 
you  ever  get  out  of  the  AUTOEXEC.BAT 
file  while  you  are  booting. 

Bob  Smith,  author  of  the  Tall 
Screen  program,  has  discovered  that 
the  DOS  3.1  COMMAND.COM  has  an  un¬ 
documented  switch  to  set  the  size  of 
the  environment. 

/E:nn  sets  the  size  of  the  environ¬ 
ment  area  to  ”nn"  para¬ 
graphs.  Range  is  10  to  62. 
Numbers  outside  that  range 
are  ignored. 

The  default  value  of  the  switch  ap¬ 
pears  to  be  /E:10. 

This  feature  is  most  useful  when 
used  in  conjunction  with  the  SHELL 
option  in  CONFIG.SYS.  For  example: 
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SH  ELI, = C:\BIN\COM  MAND.COM 
C:\BIN  /P  /K:20 

Trojan  Horse  Programs 

Don  Watkins,  system  operator  of  the 
CompuServe  IBM  PC  Novice  SIG,  re¬ 
cently  passed  me  a  copy  of  a  Trojan 
horse  program  that  was  uploaded  to 
his  bulletin  board.  This  program  is 
named  DROGAN.COM  and  is  7,040 
bytes  in  length.  When  you  run  it,  it 
says  "Please  wait  .  .  there  is  some 
disk  activity,  and  then  it  displays 
"BYF.  F_HEADf  and  exits — after  for¬ 
matting  your  disk. 

Inspection  of  DROGAN.COM  reveals 
that  it  is  a  "hacked"  version  of  the 
IBM  PC  DOS  FORMAT.COM  program. 
When  you  download  a  program 
from  a  BBS  without  the  source  code, 
you  need  to  be  really  careful — there 
are  some  twisted  minds  out  there! 

Tom  Neff  has  compiled  the  follow¬ 
ing  list  of  other  reported  Trojan 
horse  programs: 

DOSKNOWS.EXE — FAT  killer  mislead¬ 
ingly  named  the  same  as  the 
harmless  DOSKNOWS  system-status 
utility.  The  real  DOSKNOWS  is  5,376 
bytes  long. 

FGABTR — Billed  as  "improve  your 
EGA  display/'  but  when  run  it  de¬ 
letes  everything  in  sight  and 
prints  "Arf!  Arf!  Got  you!" 
FILER.EXE — labeled  "Great  new  filing 
system,"  reportedly  wiped  out  20- 
meg  hard  disk. 

SFCRET.BAS — Formats  disks. 
STRIPES.EXE — Draws  an  American 
flag  but  copies  the  remote  BBS  con¬ 
figuration  file  to  another  file  (STRI¬ 
PES.  BQS)  so  the  uploader  can  call 
back  and  download  all  the  pass¬ 
words.  Clever! 

VDIR.COM — This  is  the  disk  killer  Jer¬ 
ry  Pournelle  wrote  about  in  Byte 
magazine. 

More  on  Concurrent  DOS 

My  musings  about  Digital  Research, 
GEM,  and  Concurrent  PC  DOS  in  re¬ 
cent  issues  of  DDJ  provoked  several 
heated  responses  from  readers.  Evi¬ 
dently  many  people  still  harbor 
warm  fuzzy  feelings  in  their  heart 
for  Digital  Research,  dating  back  to 
the  CP/M  1.4  days,  and  they  suspect 
that  DRt  was  somehow  swindled  out 
of  its  rightful  place  as  the  emperor  of 
microcomputer  operating  systems. 
They  react  violently  to  the  sugges¬ 


tion  that  DRI  might  have  blown  the 
whole  ball  game  by  itself  with  such 
brilliant  marketing  moves  as  letting 
CP/M  2.2  stagnate  for  years,  dawdling 
forever  in  getting  a  usable  version  of 
CP/M-86  into  the  field,  and  wasting 
valuable  time  and  energy  on  hot 
ideas  such  as  Dr  Logo. 

Well,  the  statements  I’ve  made 
about  GEM  and  Concurrent  PC  DOS 
over  the  last  year  in  this  column  are 
only  my  own  opinions  and,  of 
course,  do  not  reflect  the  opinions  of 
the  management  of  DDJ.  I  have  been 
programming  on  micros  since  the 
CP/M  1.4  days  myself,  and  I  certainly 
appreciate  all  the  contributions  Gary 
Kildall  and  DRI  made  with  stable,  rel¬ 
atively  bugfree  operating  systems 
and  compilers  at  the  beginning  of  the 
microcomputer  revolution. 

The  events  of  the  last  two  or  three 
years,  however,  seem  to  point  to  an 
organization  that  is  flailing  around  in 
the  marketplace  without  much  sense 
of  reality  or  direction.  Just  recently 
we  have  been  treated  to  the  sight  of 
DRI  starting  up  massive  Unix  projects 
and  then  abandoning  them;  an¬ 
nouncing  Protected  Mode  Concur¬ 
rent  DOS-286  and  then  fizzling  out; 
caving  in  to  Apple  without  a  battle 
on  the  GEM  visual  interface;  drop¬ 
ping  support  for  CP/M-Plus  even 
though  the  8080/Z80  operating  sys¬ 
tems  are  probably  DRl's  sole  profit¬ 
able  product  by  now;  and  spending 
millions  of  dollars  on  advertising  to 
sell  only  about  50,000  copies  of  GEM 
at  a  price  that  could  have  barely  cov¬ 
ered  the  costs  of  materials,  packag¬ 
ing,  shipping,  and  handling. 

The  Concurrent  PC  DOS  project 
seems  to  me  to  be  the  height  of  fool¬ 
ishness  and  a  particularly  glaring  ex¬ 
ample  of  DRl’s  ability  to  delude  itself 
into  believing  that  the  old  days  can 
come  again.  Given  the  close  working 
relationship  between  Microsoft  and 
IBM  and  the  frequency  with  which 
new  IBM  hardware  products  and  Mi¬ 
crosoft  MS  DOS  versions  are  released, 
DRI  will  always  be  playing  a  catch-up 
game.  Even  if  Concurrent  DOS  per¬ 
formed  as  well  as  MS  DOS  (which  it 
doesn’t),  DRI  could  never  hope  to  be 
less  than  six  months  to  a  year  behind 
in  emulating  the  functionality  of  the 
latest  revision  of  MS  DOS — which  just 
isn't  going  to  be  good  enough  for  to¬ 
day's  software  market.  DRI  would 
have  been  much  wiser  to  invest  the 


money  and  programming  talent  it 
put  into  Concurrent  DOS  into  some¬ 
thing  that  the  market  really  needed 
instead  of  into  something  that  DRI 
wished  the  market  needed. 

IBM  PC  Graphics 

Dan  Rollins,  the  prolific  author  of 
magazine  articles  on  8086  assembly 
language  and  the  book  IBM  PC,  8088 
Macro  Assembler  Programming 
(Macmillan,  1985),  was  kind  enough 
to  send  us  the  following  letter  and 
listings: 

"My  interest  was  piqued  by  Tom 
Hogan’s  article  'Using  Decision  Vari¬ 
ables,'  published  in  the  May  1985  is¬ 
sue  of  DDJ.  I  was  disappointed  in 
how  slow  the  ellipsis  generator  exe¬ 
cuted — far  slower  than  the  BASIC  CIR¬ 
CLE  command.  The  code  that  gener¬ 
ates  the  coordinates  is  very  fast.  The 
bottleneck  is  in  the  pixel-plotting 
subroutine.  I  thought  your  readers 
might  appreciate  a  fast  IBM  dot  plot¬ 
ter  to  add  to  their  toolboxes. 

"The  PLOTDOT.ASM  program  (List¬ 
ing  One,  page  112)  is  different  from 
similar  routines  in  that  I  have  made  a 
concerted  effort  to  cut  down  on 
clock  cycles.  The  first  thing  I  did  was 
to  remove  any  ’general  code'  used  to 
determine  the  current  screen  mode, 
and  so  on.  This  version  will  work 
only  for  midresolution  graphics. 

"But  the  breakthrough  came  when 
I  realized  that  lookup  tables  could  be 
used  to  convert  the  x,y  coordinate 
pair  into  a  screen  buffer  location  and 
pixel  position.  This  technique  eats  up 
some  extra  RAM  (just  over  400  bytes), 
but  silicon  is  cheap.  The  routine  sac¬ 
rifices  storage  for  speed,  and  the 
trade-off  is  a  pretty  good  deal.  It 
avoids  a  very  time-consuming  multi- 
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plication,  and  the  code  is  straight-line 
(there  isn't  a  single  conditional  jump 
anywhere  in  the  routine). 

"A  couple  of  points  of  interest  in 
PLOTDOT.ASM.  I  have  written  it  to  in¬ 
terface  with  Microsoft  C  Small  Model 
programs,  and  the  start  of  the  code 
shows  the  coding  overhead  required 
to  do  so.  Second,  I  have  shaved  off 
some  precious  clock  cycles  by  ignor¬ 
ing  the  standard  interfacing  tech¬ 
niques.  Instead  of  the  stack  relative 
addressing  that  is  normally  used  to 
access  parameters,  I  have  simply 
popped  them  off  the  stack  into  the 
available  registers. 

"Another  interesting  point  is  in 
how  the  main  lookup  table  is  gener¬ 
ated.  This  is  perhaps  the  only  mean¬ 
ingful  use  of  the  Macro  Assembler’s 
REPT  pseudo-op. 

"Finally  I  am  enclosing  a  Microsoft 
C  line-drawing  function  (Listing  Two, 
page  112)  that  illustrates  the  speed  of 
the  dot  plotter.  The  ‘plotline’  function 
uses  a  decision  variable,  somewhat 
similar  to  that  of  Hogan’s  ellipsis  gen¬ 
erator.  You  could  recode  it  in  assem¬ 
bly  language,  but  it  might  not  be 
worth  your  effort.  A  disassembly 
shows  that  the  Microsoft  compiler 
generates  quite  efficient  code,  which 
is  improved  further  by  using  static 
variables  whenever  convenient.” 

More  Light  Reading 

As  I  mentioned  in  last  month's  col¬ 
umn,  if  you  don't  have  a  subscription 
to  Datamation,  you  are  missing  half 
the  fun  in  life.  An  example  is  the  es¬ 
say  "Real  Programmmers  Don’t  Use 
Pascal,”  which  appeared  in  the  July 
1983  issue  on  page  263.  It  introduces 
itself  with: 

"The  easiest  way  to  tell  who  the 
Real  Programmers  are  is  by  the  pro¬ 
gramming  language  they  use.  Real 
Programmers  use  FORTRAN.  Quiche 
Eaters  use  Pascal.  Niklaus  Wirth,  the 
designer  of  Pascal,  was  once  asked, 

’  How  do  you  pronounce  your  name?' 
‘You  can  either  call  me  by  name,  pro¬ 
nouncing  it  Veert,  or  call  me  by  val¬ 
ue,  Worth,'  he  replied.  One  can  tell 
immediately  from  this  comment  that 
Niklaus  Wirth  is  a  Quiche  Eater.  The 
only  parameter  passing  mechanism 
endorsed  by  Real  Programmers  is 
call-by-value-return,  as  implement¬ 
ed  in  the  IBM/370  FORTRAN  G  and  H 
compilers.  Real  Programmers  don’t 
need  abstract  concepts  to  get  their 
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jobs  done,  they  are  perfectly  happy 
with  a  keypunch,  FORTRAN  IV  com¬ 
piler,  and  a  beer.  Real  Programmers 
do  list  processing,  string  manipula¬ 
tion,  accounting  (if  they  do  it  at  all), 
and  artificial  intelligence  programs 
in  FORTRAN.  If  you  can’t  do  it  in  FOR¬ 
TRAN,  do  it  in  assembly  language.  If  it 
can’t  be  done  in  assembly  language, 
it  isn't  worth  doing.  .  .  .” 

The  article  goes  on  in  this  vein  for 
four  pages,  incidentally  giving  a 
proof  (in  FORTRAN,  not  ALGOL)  that 
Seymour  Cray,  at  least,  is  a  Real 
Programmer. 

Blatant  Plug  and  a 
Disclaimer 

As  many  of  you  know,  I  have  been 
working  for  a  year  now  on  what  I 
hope  will  be  the  definitive  book  on 
MS  DOS  programming.  It  starts  where 
the  other  books  leave  off.  It  is  target¬ 
ed  at  the  experienced  assembly-lan¬ 
guage  programmer,  and  it  has  many 
detailed  examples  and  working  pro¬ 
grams  (it  contains  some  C  examples, 
too).  Although  my  own  company 
published  this  book  briefly  under  the 
title  MS  DOS  Internals,  it  has  now 
been  sold  to  Microsoft  Press  and  will 
appear  in  your  favorite  bookstore 
under  the  title  Advanced  MS  DOS  in 
the  spring  of  1986. 

This  is  not  only  a  plug  but  also  a 
disclaimer.  Although  it  is  a  pleasure 
to  be  associated  with  the  fine  people 
at  Microsoft  Press,  let  me  assure  you 
that  it  will  not  influence  the  way  I 
report  on  Microsoft  Corp.  software 
in  this  column.  When  the  company 
deserves  praise  (as  with  the  C  compil¬ 
er),  it  will  get  it;  and  when  it  deserve 
brickbats,  it'll  get  those  too. 


DDJ 

(Listings  begin  on  page  112) 
Reader  Ballot 

Vote  for  your  favorite  feature/article. 
Circle  Reader  Service  No.  7. 
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PROFESSIONAL  PROGRAMMER 


Software 

Warranties 


"You  have  the  non-exclu¬ 
sive  right  to  use  the  en¬ 
closed  program.  You  may 
not  use,  copy,  modify  or 
transfer  the  program  or 
documentation,  or  any 
copy,  except  as  expressly 
provided  in  this  agree¬ 
ment.  Unauthorized  repro¬ 
duction,  transfer,  or  use 
may  be  a  criminal  offense 
under  federal  and/or  state 
law. 

"The  program  is  provid¬ 
ed  'as  is'  without  warranty 
of  any  kind.  Should  the 
program  prove  defective, 
you  (and  not  [the  compa¬ 
ny]  or  its  dealers)  assume 
the  entire  cost  of  all  neces¬ 
sary  servicing,  repair,  or 
correction.  [The  company] 
does  not  warrant,  guaran¬ 
tee,  or  make  any  represen¬ 
tations  regarding  the  use 
of,  or  the  results  of  the  use 
of,  the  program  in  correct¬ 
ness,  accuracy,  reliability, 
currentness,  or  otherwise; 
and  you  rely  on  the  pro¬ 
gram  and  results  solely  at 
your  own  risk. 

"[The  company]  does 
warrant  the  disk. 

"The  above  is  the  only 
warranty  of  any  kind,  ei¬ 
ther  expressed  or  implied, 
including  but  not  limited  to 
the  implied  warranties  of 
merchantability  and  fit¬ 
ness  for  a  particular  pur¬ 
pose  that  is  made  by  [the 
company].” 

The  above  familiar  prose 
is  reproduced  here  with¬ 
out  credit  to  (or  permission 
of)  the  companies  that  use 
it.  Although  the  whole  is  a 
composite,  every  sentence 
was  taken  directly  from 
some  company's  shrink¬ 
wrap  agreement.  There’s 
no  point  in  singling  out  one 
or  two  companies  when  so 


many  use  essentially  the 
same  disclaimer.  It  is  rou¬ 
tine  in  software  publishing 
today  to  sell  diskettes  for 
$400  or  $500  and  inform 
the  purchaser  that  there 
may  be  a  piece  of  software 
on  the  diskette;  that  if 
there  is,  it  may  or  may  not 
do  what  the  company’s  ad¬ 
vertising  says  it  will  do; 
that  it  may  or  may  not  do  it 
accurately,  correctly,  or 
reliably;  and  that  it  may  or 
may  not  be  of  any  use  to 
anyone;  but  that  in  any 
case  it  is  not  the  property 
of  the  customer,  who  may 
be  tried  as  a  criminal  for 
any  improper  use  of  the 
product,  proper  use  being 
defined  by  the  manufac¬ 
turer. 

It’s  a  routine  that  may 
soon  be  shaken — but  one 
organization  of  software 
developers  is  concerned 
about  whose  hand  will  do 
the  shaking. 

The  Software  Services 
Association  (SSA)  is  a  Cali¬ 
fornia  organization  whose 
members  are  individuals 
and  companies  involved  in 
software  development  and 
related  fields.  It’s  an  explic¬ 
itly  political  group  that  en¬ 
gages  in  lobbying  for  the 
interests  of  software  devel¬ 
opers.  It  was  formed  in 
1982  to  fight  California’s  at¬ 
tempt  to  levy  a  retroactive 
sales  tax  on  the  work  of 
small  software  companies 
that  would  extend  back  as 
far  as  1974.  The  SSA  has  re¬ 
cently  taken  on  the  issue  of 
software  warranties,  again 
in  connection  with  pro¬ 
posed  legislation. 

The  California  legisla¬ 
ture  held  hearings  last 
summer  on  a  bill  (AB  1507) 
that  would  have  required 
warranties  on  all  software 
products.  The  bill  was  de¬ 
feated,  but  the  SSA  does  not 
view  the  issue  as  closed. 


Michael  Odawa  of  the  SSA 
was  one  witness  who  testi¬ 
fied  at  the  hearings. 
Odawa  and  the  SSA  viewed 
the  bill  as  hostile  to  the 
software  industry,  but 
Odawa  has  nevertheless 
argued  in  favor  of  volun¬ 
tary  adoption  of  warran¬ 
ties  and  against  the  prac¬ 
tice  of  using  the  kind  of 
disclaimers  quoted  above, 
contending  that  compa¬ 
nies  that  use  them  "appar¬ 
ently  feel  no  need  to  stand 
behind  their  workman¬ 
ship.” 

Odawa  argues  that  con¬ 
sumers  will  not  continue 
to  put  up  with  useless  war¬ 
ranties  much  longer,  and 
he  cites  the  legislative  bat¬ 
tle  as  evidence.  He  urges 
SSA  members  to  offer  good 
warranties  and  to  use 
them  as  a  marketing  tactic. 
"Put  a  good  warranty  on 
your  product,”  he  says, 
"and  tell  the  world  about 
it.  Ask  your  customers 
whether  the  competition 
stands  behind  its  pro¬ 
ducts.” 

The  SSA  publishes  a 
newsletter  that  details  its 
activities.  You  can  get  in¬ 
formation  about  the  orga¬ 
nization  by  writing  to  Soft¬ 
ware  Services  Association, 
P.O.  Box  6413,  San  Jose,  CA 
95150. 

Software 

Pricing 

Another  Silicon  Valley  or¬ 
ganization  that  offers  use¬ 
ful  services  and  informa¬ 
tion  for  programmers  is 
the  Software  Entrepre¬ 
neurs’  Forum,  which 
meets  monthly  in  Palo 
Alto.  November's  meeting 
centered  on  software  pric¬ 
ing  strategies. 

Gregg  Marshal],  presi¬ 
dent  of  Rocky  Mountain 


Systems,  tongue  only  occa¬ 
sionally  in  cheek,  cited  sev¬ 
en  pricing  strategies,  each 
of  which  prevails  over  oth¬ 
ers  in  some  market. 

Several  of  the  techniques 
were  textbook  or  com- 
monsense  techniques, 
such  as  retail  price  equals 
n  times  cost  of  goods  sold. 
Marshall  set  n  at  some¬ 
where  between  6  and  10; 
in  other  industries  it  is  of¬ 
ten  more  like  5.  Other  com¬ 
mon  techniques  included 
copying  the  competition, 
pricing  according  to  the 
value  of  the  data  your  soft¬ 
ware  juggles,  and  selling  to 
the  perceived  value.  The 
last  idea  can  be  particular¬ 
ly  appealing  to  those  in  a 
company  who  see  their  job 
as  manipulating  the  pub¬ 
lic's  perception  of  the 
product.  Other  strategies 
included  what  Marshall 
called  the  Borland  strategy 
of  picking  a  magic  number. 

Other  speakers  pointed 
out  that  some  price  ranges 
create  misleading  impres¬ 
sions  for  consumers  and 
that  customers  are  willing 
to  pay  for  upgrades,  will¬ 
ing  enough  that  there  are 
profits  to  be  made  from 
upgrades.  Gary  Carlston, 
cofounder  of  Broderbund, 
emphasized  the  impor¬ 
tance  of  involving  dealers 
in  the  pricing  process. 

The  Software  Entrepre¬ 
neurs’  Forum  has  several 
splinter  groups,  such  as 
SlGs  covering  technical  is¬ 
sues  for  Macintosh  and  IBM 
developers,  as  well  as  mar¬ 
keting  and  engineering 
SIGs.  The  Forum  also  pub¬ 
lishes  a  newsletter.  You 
can  find  out  about  it  by 
writing  to  Software  Entre¬ 
preneurs’  Forum,  P.O.  Box 
61031,  Palo  Alto,  CA  94306. 

DDJ 
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Trading  Places 

A  flurry  of  post-Comdex 
visits  to  and  from  repre¬ 
sentatives  of  companies 
not  generally  thought  of  as 
software  developers  has 
left  us  with  a  curious  im¬ 
pression:  programmers 
and  semiconductor  pro¬ 
ducers  are  trading  places. 

All  right,  we’re  exagger¬ 
ating.  But  we  do  so  to  em¬ 
phasize  a  growing  trend, 
one  implication  of  which  is 
that  programmers  should 
keep  a  close  eye  on  semi¬ 
conductor  firms — and  not 
just  to  see  what  new  pro¬ 
cessors  are  coming.  The 
design  of  chips  is  becoming 
more  and  more  a  software 
task,  and  the  manufactur¬ 
ers  of  chips  are  beginning 
to  realize  that  they  need  to 
be  in  the  software 
business. 

Take  Intel.  We  flew  up 
to  Oregon  to  visit  some  In¬ 
tel  people  and  learned 
about  some  changes  un¬ 
derway  there. 

For  years,  Intel  has  sold 
development  systems  to  its 
customers,  development 
systems  that  were,  in  fact, 
personal  computers.  Intel 
was  not,  however,  in  the 
commercial  personal  com¬ 
puter  marketplace  be¬ 
cause  its  machines  were 
built  in  low  volumes  for 
specific  purposes.  Intel 
was  not  building  machines 
that  could  compete  in  the 
commercial  market,  nor 
did  the  company  want  to 
be  in  that  market.  Intel  had 
decided  as  far  back  as  the 
mid-70s  that  it  was  not  a 
computer  company  and  it 
was  not  in  its  best  interest 
to  develop  a  commercial 
computer  and  compete 
with  its  customers. 

But  the  development 
systems  Intel  built,  the  sys¬ 


tems  it  sold  to  its  customers 
who  were  building  ma¬ 
chines  around  Intel's 
chips,  were  not  just  boxes. 
Intel  also  supplied  the  de¬ 
velopment  software.  The 
history  of  Intel's  involve¬ 
ment  in  microcomputer 
software  development  is 
rich  in  intriguing  might- 
have-beens.  One  of  the  first 
Intel  development  systems 
sat  in  the  back  of  Gary  Kil- 
dall's  classroom  at  the  Na¬ 
val  Postgraduate  Research 
Institute  in  Monterey  Cali¬ 
fornia,  where  graduate 
student  Gordon  Eubanks 
wrote  CBASIC  as  a  class  pro¬ 
ject.  Kildall  wrote  some  of 
Intel's  development  soft¬ 
ware,  and  Intel  could  have 
had  CP/M  if  it  had  wanted 
it.  But  Intel  didn't  want  a 
commercial  product;  it 
wasn’t  in  the  software 
business  any  more  than  it 
was  in  the  computer 
business. 

Intel  passed  up  CP/M,  but 
it  did  put  together  for  each 
of  its  products  a  support 
package  of  the  hardware 
and  software  necessary  to 
use  the  product.  The  soft¬ 
ware,  like  the  hardware, 
was  designed  for  the  devel¬ 
opment  phase.  In  soft¬ 
ware,  as  in  computers,  In¬ 
tel  was  just  selling  support 
tools  for  its  products,  not 
competing  in  the  commer¬ 
cial  market. 

Now  that’s  changing.  In¬ 
tel  is  coming  to  believe  that 
it  belongs  in  the  commer¬ 
cial  system-software  mar¬ 
ket  and  that  it  must  devel¬ 
op  competitive  products. 
Company  employees 
make  no  mystery  about 
the  reason  for  the  shift  in 
strategy:  it’s  the  IBM  PC/AT. 

As  long  as  you  had  to 
buy  Intel’s  box  to  use  In¬ 
tel's  chips  and  Intel’s  soft¬ 
ware  was  written  to  run 
on  Intel’s  box,  the  firm  had 


a  captive  market  for  its  de¬ 
velopment  hardware  and 
software.  The  AT  has  cut  a 
link  out  of  the  chain:  it  pro¬ 
vides  the  speed,  memory 
and  power  needed  for  sys¬ 
tem  development,  and  it 
makes  the  Intel  boxes  un¬ 
necessary.  Which  leaves 
the  software  with  its  chain 
dangling.  Intel  develop¬ 
ment  software  must  now 
compete  with  commercial 
software.  That  has  caused 
some  concern  at  Intel  as 
well  as  some  scrambling  to 
get  the  products  and  the 
marketing  of  the  products 
in  line  with  commercial 
standards  and  practices. 
One  Intel  representative 
breathed  a  sigh  of  relief 
that  DDJ  had  not  reviewed 
the  Intel  C  compiler  in  its 
August  1985  review  but  ex¬ 
pressed  interest  in  having 
the  next  version  included 
in  the  next  review. 

The  other  side  of  this 
coin  is  that  the  design  of 
chips  (and  of  computers)  is  | 
becoming  more  and  more 
a  software  task.  Two  ex¬ 
amples  of  this  are  silicon 
compilers  and  the  soft¬ 
ware  simulation  of  semi¬ 
conductor  devices. 

We  went  to  hear  David 
Johannsen  speak  during 
Comdex.  Johannsen  is  gen¬ 
erally  credited  with  in¬ 
venting  the  concept  of  sili¬ 
con  compilation  as  a 
graduate  student  at  Cal 
Tech.  He  subsequently  ce¬ 
mented  his  right  to  use  the 
term  by  starting  a  compa¬ 
ny  called  Silicon  Compil¬ 
ers,  which  develops  silicon 
compilers  (as  one  might  na¬ 
ively  guess)  and,  more  re¬ 
cently,  silicon  compiler 
compilers.  Johannsen's  ap¬ 
proach  to  computer-aided 
design  most  blatantly  un¬ 
derscores  the  parallels  be¬ 
tween  semiconductor  de¬ 
sign  and  software  design. 


Silicon  compilation 
helps  in  the  design  and  de¬ 
sign  testing  of  a  chip  just  as 
a  software  compiler  helps 
in  the  design  of  a  program. 
The  user  works  with  low- 
level  primitives  such  as 
ALUs,  RAMs,  and  PLAs, 
building  these  into  blocks 
and  modules  and  perhaps 
into  chips  that  serve  as 
board-level  primitives  for 
a  higher  level  of  design. 
The  notion  of  multiple  lev¬ 
els  is  central  to  the  silicon 
compiler;  the  user  can  de¬ 
sign  at  different  levels, 
with  the  system  simulating 
devices  down  only  to  the 
level  at  which  design  is 
taking  place. 

Silicon  compilation  of¬ 
fers  some  capabilities  that 
software  compilers  don’t 
and  perhaps  should.  Users 
of  a  silicon  compiler  can 
specify  designs  in  language 
format,  just  as  when  writ¬ 
ing  code  (or  constructing 
truth  tables,  logic  equa¬ 
tions,  microcode;  Johann¬ 
sen  classifies  all  these  ap¬ 
proaches  as  language 
formats).  But  they  can  also 
work  at  a  graphic,  more  in¬ 
tuitive  level,  specifying  via 
schematics.  And  for  con¬ 
ventional  components,  the 
user  has  the  option  of  sim¬ 
ply  filling  in  a  displayed 
form  with  on  line  help — 
programming  by  menus. 

Silicon  Compilers'  silicon 
compilers  provide  some 
other  softwarelike  capabil¬ 
ities,  including  a  rough 
equivalent  of  syntax 
checking  in  a  logical  design 
rule  checker  (LDRC).  The 
LDRC  checks  for  timing  in¬ 
consistencies  and  type  in¬ 
consistencies  (clock  expect¬ 
ed,  ground  wired)  and 
flags  certain  “questionable 
practices”  (mostly  nonpor¬ 
table  stuff). 
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PROGRAMMER'S  SERVICES 

OF  INTEREST 


This  issue  focuses  on  Pas¬ 
cal,  Ada,  and  Modula-2  as 
structured  languages. 
There  has  for  some  time 
been  a  language  available 
in  the  6502  world  that  em¬ 
bodies  such  structured  fea¬ 
tures  as  syntactically 
meaningful  indentation: 
Promal. 

Systems  Management 
Associates  announced  that 
its  Promal  2.0  integrated 
programming  system  will 
support  the  IBM  PC  and 
compatibles  by  March 
1986.  Significant  perfor¬ 
mance  and  capacity  en¬ 
hancements  are  expected. 
The  product  consists  of  a 
high-performance,  com¬ 
piled  structured  language; 
full-screen  editor;  operat¬ 
ing  system  executive  (ex¬ 
cept  IBM  version);  and  li¬ 
brary  subroutines.  It 
currently  supports  the  Ap¬ 
ple  lie  or  lie  (with  128K  and 
80-column  card)  and  the 
Commodore  64/128. 

The  Commodore  and 
Apple  versions  are  priced 
between  $50  and  $100.  The 
IBM  PC  line  version  costs 
$99.95  plus  $5  for  shipping 
and  handling. 

Control-C  Software  has 
announced  a  software 
product  that  permits  spe¬ 
cific  IBM  PC  applications 
such  as  Lotus  1-2-3,  Multi¬ 
mate,  WordStar,  and  Side- 
Kick  to  work  on  personal 
computers  that  are  not  IBM- 
compatible.  Known  as  Soft- 
clone,  this  software  re¬ 
quires  no  changes  to  the 
original  release  disk,  so  any 
copy  protection  used  re¬ 
mains  in  force. 


At  the  heart  of  Softclone 
is  a  smart  loader  program 
that  loads  the  IBM  PC  appli¬ 
cation  and  surrounds  it 
with  a  fake  IBM  PC  soft¬ 
ware/hardware  environ¬ 
ment.  Whenever  an  appli¬ 
cation  accesses  IBM-specific 
memory  or  hardware, 
Softclone  intervenes,  ac¬ 
cessing  the  nonclone  host 
memory,  hardware,  and 
operating  system  instead. 
Under  a  licensing  agree¬ 
ment,  the  per-CPU  royalty 
is  $10. 

Advanced  Trace86  from 
Morgan  Computing  pro¬ 
vides  assembly-language 
programmers  with  a  de¬ 
bugging  environment  for 
the  IBM  PC  or  IBM  PC/AT.  In 
Trace  mode,  it  displays  a 
full  screen  (16—22  lines)  of 
disassembled  code.  An  in¬ 
verse  video  bar  marks  the 
instruction  that  is  current¬ 
ly  executing.  Windows 
show  a  constant  display  of 
registers  and  flags,  the  cur¬ 
rent  stack,  and  up  to  six 
lines  of  memory  (which 
you  can  set  to  track  pro¬ 
gram  references).  An  op¬ 
tional  window  displays  the 
contents  of  8087  registers. 
It  is  possible  to  single  step, 
trace  at  normal  trace  speed 
(about  30  instructions  per 
second)  or  quick  trace 
speed  (about  1/3000  of  na¬ 
tive),  use  a  keyboard  inter¬ 
rupt  to  start  tracing  a  run¬ 
ning  program,  or  set  a 
breakpoint  in  the  code.  Ad¬ 
vanced  Trace86  can  also 
step  backward  up  to  20  in¬ 
structions  to  get  a  replay  of 
the  action. 

Real-Time  Computer  Sci¬ 
ence  Corporation  has  an¬ 
nounced  several  new 
products.  The  PL/M  Con¬ 
nection  is  an  interface  li¬ 
brary  of  more  than  150 
functions  and  utilities  that 
provides  a  direct  connec¬ 
tion  between  an  IBM  PC 


and  Intel’s  PL/M  86  compil¬ 
er.  PL/M  Connection  comes 
on  a  360K  IBM  PC  DOS  for¬ 
matted  disk,  complete 
with  source  code  in  PL/M 
and  assembly  demonstra¬ 
tion  programs  (also  with 
source  code),  and  a  200- 
page  manual.  The  license 
fee  is  $295  per  user  system. 

Version  3.0  of  iSIM85 
software  allows  develop¬ 
ers  to  run  Intel  8-bit  com¬ 
pilers,  assemblers,  and  util¬ 
ities  on  IBM  PC/XT/ ATs  or 
any  MS  DOS-based  comput¬ 
er.  It  supports  Intel  devel¬ 
opment  software  for  the 
8085,  8080,  8089,  and  8048/ 
8051  processor  lines. 

Intel  and  Advanced 
Computer  Techniques 
have  agreed  to  develop  an 
80286-based  Ada  compiler. 
Aimed  at  military  software 
design  applications,  the 
Ada-286  compiler  will  sup¬ 
port  two  target  environ¬ 
ments:  the  80286  micropro¬ 
cessor  chip  and  the 
iRMX286  operating  system. 
Both  environments  will 
support  the  M80287  nu¬ 
meric  data  processor. 

The  Advanced  Logic  Re¬ 
search  System  286  is  based 
on  the  advanced  80286-8 
16-bit  microprocessor  with 
a  system  clock  rate  of  8 
MHz.  It  is  designed  to  be 
IBM  PC/AT  bus  compatible 
with  full  attention  to  the 
BIOS  ROMs.  The  system  sup¬ 
ports  IBM  PC  DOS  3.0  and  3.1 
and  Xenix  operating 
systems. 

A  5-inch  board  that  fits 
into  one  IBM  "short”  slot, 
the  PC/Short  Memory 
from  Emulex  expands  the 
IBM  PC  or  compatibles  to  a 
full  memory  capacity  of 
640K.  It  offers  starting  ad¬ 
dresses  of  128K,  256K, 
384K,  and  512K  so  the 
board  can  work  on  a  vari¬ 
ety  of  personal  computers 
with  different  RAM  capaci¬ 


ties  on  their  motherboards. 
The  PC/Short  Memory  also 
supports  byte  parity  to 
protect  data  in  the  event  of 
a  failure. 

Micro  Computer  Tech¬ 
nologies  has  introduced 
what  it  calls  the  next  gen¬ 
eration  of  expansion 
boards  for  the  IBM  PC/XT. 
The  Modular  Expansion 
Series  includes  an  exter¬ 
nally  mounted  visual/au- 
dible  indicator  for  key¬ 
board,  keylock  positions, 
fast/slow  speed,  program¬ 
mable  key  function,  and 
an  added  four  feet  of  key¬ 
board  extension  cable.  No 
IBM  expansion  slot  is 
required. 

The  power  to  develop 
transportable  applications 
on  a  range  of  hardware,  in¬ 
cluding  the  IBM  PC  AT,  IBM 
PC  XT,  and  Unix  machines, 
is  available  through  Pro¬ 
gress  from  Data  Language. 
Progress  is  an  application 
development  system  com¬ 
bining  a  fourth-generation 
application  language  with 
a  database  management 
system.  Advanced  facilities 
provide  a  single  produc¬ 
tive  environment  for 
building  transaction-ori¬ 
ented  applications  without 
conventional  program¬ 
ming.  Its  multiuser,  envi¬ 
ronment  supports  simulta¬ 
neous  database  access  and 
update  while  maintaining 
database  integrity  through 
systems  failures. 

The  Cauzin  Softstrip  Sys¬ 
tem  is  for  entering,  storing, 
and  distributing  data.  It  is 
an  alternative  to  diskettes 
and  telecommunications. 
The  Softstrip  data  strips 
are  decoded  and  entered 
into  a  personal  computer 
via  an  optoelectronic  scan¬ 
ning  device  that  plugs  into 
IBM,  Apple  II  series,  and 
Macintosh  personal  com¬ 
puters.  Each  data  strip  can 
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hold  up  to  5,500  bytes  and 
can  be  linked  for  lengthy 
programs,  financial  infor¬ 
mation,  or  databases. 

Advanced  Digital  Corpo¬ 
ration’s  PC-Slave  II  is  a 
high-speed  (8  MHz),  16-bit 
single-board  processor  that 
contains  two  Intel  80188 
CPUs,  two  512K  memory 
chips,  2K  of  dual  port 
networking,  and  a  priority 
interrupt  controller.  It 
achieves  both  hardware 
and  software  compatibility 
with  the  IBM  PC  and  com¬ 
patibles  by  providing  func¬ 
tional  identity  I/O  address¬ 
es,  video  display  keyboard 
interface,  and  operating 
system  software.  Single- 
user  systems  can  be  ex¬ 
panded  to  multiuser  sys¬ 
tems  of  2  —  32  individual 
workstations. 

Sumitronics  has  released 
the  General  Purpose  Cross 
Assembler,  XASS-V.  In  addi¬ 
tion  to  supporting  pro¬ 
gramming  for  all  common 
microprocessors,  the  XASS- 
V  also  supports  custom 
CPUs.  Definition  files  are 
generated  by  the  option 
program  of  the  Definition 
Processor  (XGEN-V).  It  is  exe¬ 
cutable  in  the  32-bit  native 
mode  of  VAX-II  series  and 
micro  VAX-I/II. 

Version  1.5  of  Koch  Soft¬ 
ware’s  PC  Sweep  disk/file 
management  program  fea¬ 
tures  an  unerase  capability 
that  supports  fixed  and  re¬ 
movable  hard  disks.  PC 
Sweep  is  an  enhanced  MS 
DOS  version  of  the  Sweep 
CP/M  software  program, 
and  runs  on  the  IBM  PC/XT/ 
AT.  The  product  allows  us¬ 
ers  to  search  for  files  and 
determine  memory  usage 
of  each  file,  view  or  page 
through  document  files, 
and  access  the  main  menu 
of  help  screens  via  one-key 
commands. 

WATFOR-77,  the  latest 
member  of  the  WATFOR 
family  of  FORTRAN  compil¬ 
ers,  has  been  released  by 
WATCOM  Products  for  the 


IBM  PC  DOS  operating  sys¬ 
tem.  By  eliminating  the 
need  to  produce  object 
files  and  the  linking  pro¬ 
cess,  WATFOR-77  can  be 
used  to  develop  and  debug 
programs.  The  PC  version 
is  available  for  a  one-time 
license  fee  of  $295.  A  site 
can  be  licensed  for  $1,200 
(up  to  20  computers)  or  for 
$3,000  (more  than  20  com¬ 
puters)  annually. 

Micro  Data  Base  Systems 
has  introduced  Guru,  an 
artificial-intelligence  soft¬ 
ware  package  developed 
for  businesses  operating  in 
an  IBM  PC  environment. 
Guru  integrates  expert  sys¬ 
tems  capabilities  and  a  nat¬ 
ural-language  interface 
with  business  tools  such  as 
spreadsheets,  database 
managers,  telecommuni¬ 
cations,  and  text  proces¬ 
sors. 

Multiple  ports  on  the  Mi- 
crofazer  II  from  Quadram 
provide  parallel/parallel, 
parallel/serial,  serial/seri¬ 
al,  and  serial/parallel 
modes  in  a  single  unit.  It 
has  an  8K  memory  that  can 
be  expanded  in  incre¬ 
ments  of  up  to  2  mega¬ 
bytes.  Microfazer  II  bulfers 
print  data  without  using 
up  any  of  the  computer’s 
memory.  It  then  takes  over 
the  printing  task,  freeing 
the  computer. 

The  CLASIX  MultiDrive 
Director  from  Reference 
Technology  is  designed  to 
increase  the  number  of  CD- 
ROM  drives  attached  to  a 
personal  computer.  The 
Director  connects  up  to 
eight  DataDrive  Series  500 
optical  disk  drives  to  a  sin¬ 
gle  IBM  PC/XT/AT  or 
compatible. 

MicroMotion  Master- 
FORTH  1.2  for  the  IBM  PC 
line  now  supports  the 
8087/80287  math  coproces¬ 
sors.  The  8087  extension  in¬ 
cludes  a  macro  assembler 
with  local  labels  support¬ 
ing  all  precisions,  opcodes, 
and  synchronization.  The 


floating-point  package  in¬ 
cludes  transcendental  and 
high-level  functions  as 
well  as  formatted  input 
and  output  routines.  Mas- 
terFORTH  1.2  includes  a  full 
file  interface  to  MS  DOS 
2.1— 3.1.  It  is  also  available 
for  the  Macintosh,  the  Ap¬ 
ple  II  line,  the  Commodore 
64,  and  CP/M  machines. 

Protecting  Data 

What  happens  to  all  that 
information  in  the  event  of 
a  power  failure?  Elgar  has 
released  Failsafe,  a  micro¬ 
computer  power-protec¬ 
tion  device.  When  utility 
power  fails,  Failsafe  is  acti¬ 
vated.  After  power  is  re¬ 
stored,  it  returns  the  pro¬ 
gram  to  where  it  left  off 
and  completes  unfinished 
tasks. 

Fastback  (Version  5.0)  is  a 
hard  disk  backup  software 
utility  from  Fifth  Genera¬ 
tion  Systems  that  backs  up 
a  10-megabyte  hard  disk 
on  standard  5V4-inch  flop¬ 
pies  or  on  the  IBM  PC/AT.  It 
works  with  PC  DOS  or  MS 
DOS,  Versions  2.0  or  later. 

Emerald  Systems'  Archi¬ 
val  Storage  Protector  sup¬ 
ports  Novell  local  area  net¬ 
works,  including  Netware 
special  files.  The  utility  is 
available  with  Emerald  14- 
inch  tape  backup  subsys¬ 
tems  for  both  stand-alone 
and  networked  IBM-com¬ 
patible  microcomputers. 
Volumes  range  from  30  to 
236  megabytes  of  format¬ 
ted  capacity. 

Everex  has  added  two 
memory  expansion  boards 
for  the  IBM  PC/AT  and  com¬ 
patibles.  The  RAM  2500AT 
holds  2V2  megabytes  of 
memory  (using  64K  RAM 
chips),  and  the  RAM  3000 
AT  holds  3  megabytes  and 
can  use  64K  or  256K  chips. 

Kustom  Electronics  has 
introduced  the  Sunflower 
MS  10  IR,  an  internal  10- 
megabyte  removable  hard 
disk  kit  designed  for  the 
IBM  PC/XT/ AT  and  AT&T 


6300.  It  is  suitable  for  com¬ 
panies  and  government 
agencies  handling  sensi¬ 
tive  or  classified  data. 

Communications 

Network  Revelation  from 
Cosmos  is  a  transaction-ori¬ 
ented  applications  envi¬ 
ronment  for  microcom¬ 
puter  networks.  It  uses 
two  filing  systems:  ROS  and 
Link.  ROS  is  designed  for 
single-user  and  unshared 
network  files.  Link  ar¬ 
ranges  data  into  IK  frames 
and  allows  network  lock¬ 
ing  routines  to  be  used. 

The  1200PA,  a  212A-com- 
patible  modem  from  Ra- 
cal-Vadic  is  designed  to 
solve  application  problems 
encountered  in  dial-up 
modems.  A  full  dialing 
keyboard  permits  control, 
option  setting,  dialing,  and 
running  diagnostics  from 
the  front  panel,  eliminat¬ 
ing  pencil  switches  or  de¬ 
pendence  upon  terminal 
protocols. 

Torus’  icon-based 
networking  software  sys¬ 
tem,  Tapestry,  runs  un¬ 
modified  on  IBM’s  Token 
Ring  networking  hard¬ 
ware.  The  product  inte¬ 
grates  the  functions  of  file 
and  record  management, 
electronic  mail,  an  inde¬ 
pendent  library  of  single- 
user  and  multiuser  appli¬ 
cations  software, 

telephone  management, 
shared  printers  and  mo¬ 
dems,  and  other  tools. 

The  Zoom  Telephonies 
Zoom/Modem  PC  1200  for 
the  IBM  PC/XT/ AT  and  com¬ 
patibles  features  call-pro¬ 
gress  tone  detection,  real¬ 
time  clock/calendar, 
auto-answer  touch-tone 
password  security,  audio 
input  port,  RAM  buffer  for 
background  electronic 
messaging,  support  of  four 
COM  ports,  and  a  high¬ 
speed  16450  UART  for  com¬ 
patibility  with  the  IBM  PC/ 
AT  and  AT  clones. 

The  Software  Link's 
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MultiLink  Advanced  and 
LANLink  provide  a  soft- 
ware-driven  solution  to 
multiuser  and  shared-re¬ 
source  systems  for  IBM  PCs 
and  compatibles.  Multi- 
Link  Advanced  allows  you 
to  use  up  to  eight  dumb  ter¬ 
minals  with  one  micro¬ 
computer  using  a  floppy 
and  the  standard  RS-232 
port.  It  can  be  combined 
with  LANLink  to  create  a 
companywide  system 
with  as  many  as  72  work¬ 
stations  operating  concur¬ 
rently. 

Reference  Map 

Systems  Management, 
3325  Executive  Dr.,  Ra¬ 
leigh,  NC  27609;  (919)  878- 
3600,  (800)  762-7874.  Reader 
Service  Number  16. 
Control-C  Software,  6441 
S.W.  Canyon  Ct.,  Portland, 
OR  97221;  (503)  292-8842. 
Reader  Service  Number  17. 
Morgan  Computing,  P.O. 
Box  112730,  Carrollton,  TX 
75011;  (214)  245-4763.  Read¬ 
er  Service  Number  18. 
Real-Time  Computer  Sci¬ 


ence  Corp.,  1390  Flynn  Rd., 
Camarillo,  CA  93010;  (805) 
987-9781.  Reader  Service 
Number  19. 

Intel,  5000  W.  Williams 
Field  Rd.,  Chandler,  AZ 
85224;  (602)  961-8420.  Read¬ 
er  Service  Number  20. 
Advanced  Logic  Research, 
2991  E.  White  Star  Ave., 
Anaheim,  CA  92806;  (714) 
666-2951.  Reader  Service 
Number  21. 

Emulex,  3545  Harbor  Blvd., 
P.O.  Box  6725,  Costa  Mesa, 
CA  92626;  (800)  854-7112, 
(714)  662-5600  in  Calif. 
Reader  Service  Number  22. 
Micro  Computer  Technolo¬ 
gies,  1745  21st  St.,  Santa 
Monica,  CA  90404;  (213)  829- 
3641.  Reader  Service  Num¬ 
ber  23. 

Data  Language,  47  Man¬ 
ning  Rd,  Billerica,  MA 
01821;  (617)  663-5000.  Read¬ 
er  Service  Number  24. 
Cauzin  Systems,  835  South 
Main  St.,  Waterbury,  CT 
96706;  (203)  573-0150.  Read¬ 
er  Service  Number  25. 
Advanced  Digital  Corp., 
5432  Production  Dr.,  Hun¬ 
tington  Beach,  CA  92649; 
(714)  891-4004,  (800)  251- 
1801.  Reader  Service  Num¬ 
ber  26. 


Sumitronics,  580  N.  Pas- 
toria  Ave.,  Sunnyvale,  CA 
94086;  (408)  737-7683.  Read¬ 
er  Service  Number  27. 

Koch  Software,  11  W.  Col¬ 
lege  Dr.,  Bldg.  G,  Arlington 
Heights,  IL  60004;  (312)  398- 
5440.  Reader  Service  Num¬ 
ber  28. 

WATCOM  Products,  415 
Phillip  St.,  Waterloo,  ONT 
N2L  3X2;  (519)  886-3700. 
Reader  Service  Number  29. 
Micro  Data  Base  Systems, 
P.O.  Box  248,  Lafayette,  IN 
47902;  (317)  447-1122.  Read¬ 
er  Service  Number  30. 
Quadram  Corp.,  One  Quad 
Way  Norcross,  GA  30093- 
2918;  (404)  923-6666.  Reader 
Service  Number  31. 
Reference  Technology, 
1832  N.  55th  St.,  Boulder, 
CO  80301;  (303)  449-4157. 
Reader  Service  Number  32. 
MicroMotion,  8726  Sepul¬ 
veda  Blvd.,  #A171,  Los  An¬ 
geles,  CA  90045;  (213)  821- 
4340.  Reader  Service 
Number  33. 

Elgar,  9250  Brown  Deer 
Rd.,  San  Diego,  CA  92121; 
(619)  450-0085.  Reader  Ser¬ 
vice  Number  34. 

Fifth  Generation  Systems, 
909  Electric  Ave.,  Ste  202, 
Seal  Beach,  CA  90740;  (800) 


225-2775,  (213)  439-2191. 
Reader  Service  Number  35. 
Emerald  Systems,  4757  Mo- 
rena  Blvd.,  San  Diego,  CA 
92117;  (619)  270-1994.  Read¬ 
er  Service  Number  36. 
Everex,  47777  Warm 
Springs  Blvd.,  Fremont,  CA 
94539;  (415)  498-1111.  Read¬ 
er  Service  Number  37. 
Kustom  Electronics,  8320 
Nieman  Rd.,  Lenexa,  KS 
66214;  (800)  255-6311.  Read¬ 
er  Service  Number  38. 
Cosmos,  19530  Pacific  High¬ 
way  South,  Seattle,  WA 
98188;  (206)  824-9942.  Read¬ 
er  Service  Number  39. 
Racal-Vadic,  1525  McCar¬ 
thy  Blvd.,  Milpitas,  CA 
95035;  (408)  946-2227.  Read¬ 
er  Service  Number  40. 
Torus,  411  Seaport  Ct.,  Ste. 
105,  Redwood  City,  CA 
94063;  (415)  363-2418.  Read¬ 
er  Service  Number  41. 
Zoom  Telephonies,  207 
South  St.,  Boston,  MA 
02111;  (617)  423-1072.  Read¬ 
er  Service  Number  42. 

The  Software  Link,  8601 
Dunwoody  PI.  NE,  Ste.  632, 
Atlanta,  GA  30338;  (404)  998- 
0700.  Reader  Service  Num¬ 
ber  43. 

— Wendelin  Colby 
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ATTENTION  TURBO  PASCAL  PROGRAMMERS 


Excellent  product . . .  best 
screen  manager  I’ve  ever 
seen  in  any  language. 


Don  A.  Williams 
Finance  &  Administration 
Honeywell 


The  word  professional 
most  certainly  describes 
the  capabilities  this  sub¬ 
routine  library  provides 
for  implementing  inter¬ 
rupt  service  and  pop-up 
routines. 


Computer  Language  Magazine  (206)  367-0650 


TURBO  PROFESSIONAL’S  easy  to  use  routines  let  you . . . 
write  safe,  “sidekickable”  routines  that  can  use  DOS 

•  execute  DOS  commands  from  T\irbo  •  create  super-fast 
windowed  displays  •  service  interrupts  without  assembler 

•  make  your  own  keyboard  enhancers  •  allocate  memory 
from  DOS  •  print  concurrently  with  DOS  3.x. 

Complete  with  109  +  routines,  manual,  source  code  to 
Super  Macs  keyboard  enhancer,  and  many  example 
programs. 

Only  $49-95  +  $5  00  shipping  &  handling 
Visa,  MasterCard  ok. 

Order  now!  f  %  Sunny  Hill  Software 

13732  Midvale  North  Suite  206 
Seattle,  Washington  98133 


<3 


Get  the  tools  that  have  no  competition. 


Requires  Turbo  for  compatibles.  Turbo  Pascal  &  Sidekick  Trademark  Borland  Inti. 
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About  the  Cover 

Parallel  processing.  Like  a  jug¬ 
gler  whose  right  hand  is  better 
off  not  knowing  what  the  left  is 
doing,  one  starts  the  various  pro¬ 
cesses  going  and  trusts  the 
rhythm  of  the  task  to  stave  off  di¬ 
saster  The  cover  illustration  was 
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sign  and  Illustration. 
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The  advent  of  parallel  process¬ 
ing  could  force  us  to  rethink  the 
way  we  solve  problems.  Mathe¬ 
matical  algorithms  in  general  are 
routinely,  almost  by  implicit  def¬ 
inition,  sequential.  Now,  things 
are  changing.  Is  some  new 
Knuth  writing  the  book  on  paral¬ 
lel  algorithms?  Herein,  some  per¬ 
spective  on  parallel  processing 
today  and  an  example  of  concur¬ 
rency  in  Pascal.  Also  please  note 
the  new  column  on  assembly 
language  and  Joe  Marasco’s 
monumental  minimizer 
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Our  annual  look  at  the  tech¬ 
niques  of  artificial  intelligence 
will  present  code  in  Prolog,  LISP, 
and  Expert-2,  led  off  by  Bob 
Brown's  BRIE  (Boca  Raton  Infer¬ 
ence  Engine). 
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Dr,  Dot*1?  journal  o! 


Admirers  of 
the  late,  la¬ 
mented  Sof- 
talk  PC  will  experi- 
I  ence  a  twinge  of  deja 
i  vu  on  reading  our  ta¬ 
ble  of  contents  this 
month:  The  Right  to 
Assemble  was  a  regu¬ 
lar  feature  of  that 
magazine,  written  bv 
our  own  Ray  Dun¬ 
can.  The  writer  in  us  regretted  such 
an  apt  title  going  to  dust,  and  the  pro- 
|  grainmer  in  us  wanted  to  see  a  regu- 
[  lar  column  on  assembly  language  in 
our  pages,  so  the  editor  in  us  made 
some  phone  calls.  Craig  Stinson  of 
Softalk  and  Ray  graciously  granted 
us  use  of  the  title.  The  column's  con¬ 
tents  will  come  from  several  authors 
j  and  address  several  architectures;  it 
will  always  include  assembly-lan¬ 
guage  code. 

It’s  hard  to  let  a  good  column  title 
or  idea  atrophy.  We  got  a  call  from 
Fred  Davis  at  A  +  magazine  asking  of 
us  what  we  had  asked  of  Craig  and 
Ray.  As  a  result,  Computer  Calisthen- 
|  ics,  the  puzzle  column  launched 
here  in  DDJ  by  Michael  Wiesenberg, 
is  now  running  in  A+.  Many  of  you 
will  recall  that  the  original  complete 
title  of  DDJ  was  Dr.  Dobb's  Journal  of 
!  Computer  Calisthenics  and  Orth¬ 
odontia:  Running  Light  Without 
Overbyte.  Now  we  just  need  to  li¬ 
cense  the  Orthodontia. 

The  real  old-timers  will  be  grum¬ 
bling  about  our  error  in  the  last  para¬ 
graph;  the  original  title  spoke  of  Tiny 
BASIC,  not  Computers,  they  will 
|  point  out.  True  enough,  and  that  's  oe- 
i  casion  for  another  note  of  avuncular 
!  pride;  Gordon  Brandly's  February 
j  1985  piece  entitled  "Tiny  BASIC  for 
i  the  68000''  was  just  reprinted  in  I/O, 
j  a  leading  Japanese  computer  maga- 
;  zine.  I/O  has  also  reprinted  Jim  Hen- 
|  drix's  articles  on  Smali-C  We're  hap- 
|  py  that  DDJ  can  be  involved  in 
|  software  development  worldwide. 

!  In  fact,  since  we  believe  that  the 
community  of  serious  programmers 


is  fundamentally  one 
international  com¬ 
munity,  we  are  be¬ 
ginning  to  make  a 
greater  effort  to  dis¬ 
tribute  the  magazine 
internationally  and 
to  draw  on  authors 
from  around  the 
world. 

This  issue  was  too 
stuffed  to  fit  in  Chip- 
Watch,  Professional  Programmer,  or 
DDJ  On  Line,  but  here  at  least  is  the 
on-line  report: 

After  a  fitful  start  in  January,  the 
DDJ FORUM  is  humming  along  nicely 
on  CompuServe.  We  apologize  to  all 
who  logged  on  January  1  only  to  find 
things  in  an  unfinished  state.  We  be¬ 
came  fully  operational  on  January  16 
and  since  then  have  gradually  added 
to  our  Data  Libraries  (DLs).  You  can 
now  download  all  the  code  from  is¬ 
sues  111,  112,  and  113  (with  the  ex¬ 
ception  of  Allen  Holub's  MS  DOS  shell 
and  utilities)  along  with  various  se¬ 
lections  from  back  issues. 

We  want  the  DLs  to  contain  listings 
that  our  readers  have  asked  for.  If 
there  is  something  front  a  back  issue 
that  is  particularly  useful  to  you,  let 
us  know.  If  demand  is  great  enough, 
we  will  make  it  available. 

Our  message  boards  have  also  seen 
considerable  activity.  Columnists 
Rav  Duncan  and  Allen  Holub  are  sy¬ 
sops  and  log  on  regularly  to  answer 
queries  and  chat.  As  of  the  date  this 
was  written,  no  special  conferences 
have  been  planned,  but  we  suggest 
that  you  sign  on  and  read  the  Confer¬ 
ence  Bulletin  to  find  a  more  recent 
update. 

Hope  you  will  drop  by  soon. 


A  r — 

Michael  Swaine 
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FORUM 


LETTERS 


Columns 

Dear  DDJ, 

I  noticed  an  apparent  error 
in  the  listing  of  fgrep.c  in 
DDJ,  September  1985.  The 
fifth  line  on  page  63  should 
read  stoupper(str);  not  - 
stoupperf  buffer);.  This 
would  keep  the  — y  flag 
from  working  unless  a 
string  file  was  used. 

Michael  J.  Eager 

481  Century  Dr. 

Campbell,  CA  95008 

Dear  DDJ, 

I  got  a  red  Dr.  Dobb's  T- 
shirt  at  the  Journal's  CP/M 
82  (or  was  it  81?)  booth. 
Now,  alas,  I  need  another 
piece  of  apparel  to  go  with 
it:  a  black  armband  with 
the  words  “Bring  Back 
Cortesi.” 

The  old  guard  keeps 
changing  at  Dr.  Dobb's. 
Nostalgia  for  the  chip- 
smoking-hackers'  glorious 
Portola  Valley  tabloid  can’t 
mask  the  fact  that  times 
are  a  changing  out  here  for 
your  readers  too.  No  one 
cares  anymore  whether 
we  can  redirect  PUN:  to  a 
solder-on  UART.  They  care 
whether  the  shirt  is  white. 
Thank  Peter  Norton  they 
don’t  care  whether  the  col¬ 
lar  is  buttoned! 

Losing  Cortesi  is  anoth¬ 
er  matter.  He  was  current. 
He  was  relevant.  He  was 
beautifully  articulate.  And 
though  I'd  rather  give  up 
night  skiing  than  Turbo 
Pascal,  he  was  most  often 
right. 

Good  luck,  Dave,  pursu¬ 


ing  whatever  "interest 
having  nothing  to  do  with 
software”  you’re  into. 
Charles  Landis 
1803  39th  Ave.  East 
Seattle,  WA  98112 

ProDOS 

Dear  DDJ, 

I  have  been  receiving  DDJ 
in  exchange  for  another 
publication,  which  has 
gone  down  the  tubes.  For 
the  past  six  months  I  have 
glanced  at  your  magazine. 
Undoubtedly  I  would  not 
have  renewed  my  sub¬ 
scription.  With  the  Decem¬ 
ber  1985  issue,  however, 
you  have  captured  my  at¬ 
tention.  Imagine  finding 
two  articles  pertaining  to 
the  Apple  II  world  and, 
more  particularly  to  Pro- 
DOS,  my  favorite  subject.  If 
such  events  continue,  I 
might  become  a  disciple  or 
even  a  contributor.  What 
are  DDJ’ s  plans  for  addicts 
like  me?  How  about  an  is¬ 


sue  devoted  to  the  6502? 

It  would  be  out  of  char¬ 
acter  for  me  not  to  com¬ 
ment  on  Shawn  Day's  arti¬ 
cle,  "Adding  a  Copy 
Command  to  ProDOS."  I 
have  several  nits  to  pick 
and  one  severe  deficiency 
to  point  out. 

In  first  stage  processing,  a 
pointer  is  used  for  reading 
the  text  of  the  user's  input 
from  the  primary  text  buff¬ 
er.  This  could  have  been  ac¬ 
complished  more  directly 
by  examining  the  input 
buffer.  In  keeping  with 
ProDOS  BASIC  convention, 
spaces  should  have  been  ig¬ 
nored  during  command 
parsing.  Finally,  it  is  not 
necessary  to  implement 
prefix  fetching  and  file  cre¬ 
ating  in  PBITS.  If  you  doubt 
this  assertation,  assign  val¬ 
ues  of  3  and  0  to  PBITS  and 
PBITS +1,  respectively  and 
observe  that  program  func¬ 
tion  does  not  change. 

In  second  stage  process¬ 


ing,  every  direct  call  to  the 
machine-language  inter¬ 
face  could  be  replaced  by  a 
call  to  GOSYSTEM,  making 
program  size  smaller  and 
program  logic  more  consis¬ 
tent.  This  fault  is  minor, 
however,  in  comparison  to 
the  inability  of  the  code 
(e.g.,  lines  361  —  378)  to  copy 
sparse  files  accurately.  Be¬ 
fore  describing  a  solution 
to  the  problem,  I  shall 
briefly  explain  this  generic 
file  entity. 

A  sparse  file  contains  dis¬ 
continuous  data  (i.e.,  holes 
exist  in  the  file).  The  num¬ 
ber  of  data  bytes  that  po¬ 
tentially  can  be  read  from 
the  file  exceeds  the  num¬ 
ber  of  data  bytes  actually 
stored  within  the  file.  A 
random  access  text  file 
(RATF)  is  the  prototypical 
sparse  file.  Not  all  RATFs  are 
sparse,  but  the  potential  ex¬ 
ists.  For  example,  consider 
a  RATF  with  a  record  length 
of  512  bytes.  One  physical 
ProDOS  block  holds  one  file 
record.  When  you  first 
open  (i.e.,  create)  the  file,  it 
has  a  length  of  0  and  is  con¬ 
tained  on  one  block.  If  next 
you  write  10  bytes  of  data 
to  Record  200,  the  file 
length  becomes  102,410 
bytes  (i.e.,  10  +  [512  X  200]) 
but  the  file  occupies  only 
three  blocks.  If  all  of  the 
prior  records  held  data,  the 
file  would  require  202 
blocks.  Thus,  the  file  is 
sparse.  This  economy  of 
space  is  made  possible  by 
index  blocks  which  keep 
track  of  but  do  not  allocate 
space  for  dataless  records. 
Under  ProDOS  the  most  ex¬ 
treme  example  of  this  phe¬ 
nomenon  is  a  file  whose 
length  is  16  megabytes  and 
whose  physical  size  is  only 
5  blocks.  That's  sparse! 

When  Shawn  Day’s  code 
reproduces  a  sparse  file,  it 
assigns  physical  blocks  to 
actual  and  potential  data 
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blocks  alike.  Using  my  first 
example,  his  copy  com¬ 
mand  would  produce  a  file 
with  202  blocks  instead  of  3 
blocks.  That  is  not  accept¬ 
able,  especially  since  RATFs 
almost  cry  out  to  be  copied 
to  a  RAM  disk.  What  to  do? 

The  principles  involved 
in  correcting  the  flaw  are 
not  difficult.  When  a  file  is 
opened,  the  buffer  re¬ 
served  for  that  file  is  1024 
bytes  long.  The  lower  half 
holds  an  image  of  the  most 
recent  data  block  being 
read  or  written.  The  upper 
half  contains  an  image  of 
the  index  block  for  the  cur¬ 
rent  128K  of  file  content. 
By  reading  the  source  file 
in  one-block  increments, 
checking  whether  data  ex¬ 
ists  by  testing  the  corre¬ 
sponding  index  bytes  (e.g., 
zero  means  no  data;  non¬ 
zero  indicates  data),  and 
writing  to  the  target  file 
only  if  data  is  found,  the 
sparse  file  can  be  faithfully 
duplicated.  File  position 
must  be  monitored  during 
the  process  so  that  data  is 
written  to  the  correct  loca¬ 
tion  within  the  target  file. 
The  SET_MARK  and  GET 
_MARK  commands  are  ide¬ 
al  for  this  purpose.  Admit¬ 
tedly  block-by-block  trans¬ 
fer  of  file  contents  is  slow¬ 
er  than  bulk  movement, 
but  the  difference  in  speed 
is  surprisingly  small  for 
files  of  64K  or  less,  and  ac¬ 
curacy  is  the  sine  qua  non 
for  a  file  copy  program. 

If  any  reader  would  like 
an  annotated  listing  of  this 
process,  I  shall  be  happy  to 
provide  one  for  the  price 
of  a  SASE. 

Let’s  hear  it  for  the  6502! 

Sandy  Mossberg 

50  Talcott  Rd. 

Rye  Brook,  NY  10573 

Bose-Nelson  Sort 

Dear  DDJ, 

Mr.  Celko’s  article  on  the 


Bose-Nelson  sort  (DDJ,  Sep¬ 
tember  1985)  was  very  in¬ 
teresting  and  thought-pro¬ 
voking,  particularly  his 
comments  on  stable  versus 
nonstable  sorts.  As  an  ad¬ 
dendum  to  his  article,  I 
wish  to  offer  the  following 
remarks: 

1. 1  was  unable  to  get  the 
recursive  program  (Listing 
One)  to  work.  There  ap¬ 
pear  to  be  at  least  two 
problems.  First,  in  the  pro¬ 
cedure  bosesort,  the  test 
if\n>l)  is  incorrect  since  n 
has  not  been  declared.  I 
suspect  that  this  test  should 
be  if  (j>l).  Second,  the  ex¬ 
pression  for  m  simplifies  to 
m=j/2.  This  cannot  be  cor¬ 
rect  since  the  result  is  an 
endless  sequence  of  recur¬ 
sive  calls  bosesortf  2,  2  ). 
Since  the  notation  used  in 
Listing  One  is  different 
from  the  notation  used  in 
the  algorithm  statement 
(an  unfortunate  choice!)  I 


cannot  deduce  how  m 
should  be  calculated. 

2.  As  printed,  Listing 
Two  is  also  incorrect.  In 
case  2  of  procedure  bose¬ 
sort,  the  first  call  to  push3 
should  instead  be  a  call  to 
push5.  Also,  in  case  3,  y  is 
defined  twice.  The  second 
definition  should  be  y  = 
stack[top-4];. 

3.  To  compare  the  recur¬ 
sive  and  nonrecursive 
methods,  I  wrote  the  pro¬ 
gram  shown  in  my  Listing 
One,  page  54,  (borrowing 
heavily  from  Mr.  Celko's 
Listing  Two!).  Note  that  my 
method  of  retrieving  com¬ 
mand  line  arguments  is  ap¬ 
plicable  to  Small-C. 

4.  For  some  reason,  the 
sequence  of  swaps  gener¬ 
ated  by  the  recursive  pro¬ 
gram  is  the  reverse  of  the 
sequence  produced  by  the 
nonrecursive  version. 

5.  A  brief  comparison  of 
the  recursive  version  (my 
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118 

211 

160 

13 

33 

50 

49 

33 

123 

243 

167 

14 

37 

55 

54 

34 

128 

260 

173 

15 

41 

61 

59 

35 

133 

278 

180 

16 

45 

65 

64 

36 

139 

288 

187 

17 

49 

81 

70 

37 

144 

308 

193 

18 

53 

90 

76 

38 

149 

319 

200 

19 

57 

100 

81 

39 

154 

331 

207 

20 

62 

106 

87 

40 

160 

338 

213 

Table  1:  Comparison  of  Bose-Nelson  Sort  with  Theoreti¬ 
cal  Minimum 


Recursive 

Non-Recursive 

.EXE  file  size 

8633 

14166 

Execution  Time  (1 00  items) 

1.3 

2.6 

Execution  Time  (1 000  items) 

54.6 

110.9 

Table  2 


Listing  One)  with  the  non¬ 
recursive  version  (his  List¬ 
ing  Two)  is  shown  in  Table 
2,  below.  Execution  times 
have  been  corrected  for 
loading  time.  Also,  the 
timed  programs  did  not 
print  out  the  swap  pairs. 

6.  The  B-N  algorithm 
generates  32,708  pairs  for  a 
list  of  664  items.  Therefore, 
if  you  must  sort  more  than 
this  many  items,  you  must 
either  use  an  unsigned  in¬ 
teger  for  the  variable 
count,  or  you  must  use  a 
longer  integer. 

7.  Table  1,  below,  com¬ 
pares  the  B-N  sort  with  the 
theoretical  minimum  and 
with  n!og2(n)  for  values  of 
n  up  to  40.  A  few  points 
should  be  noted.  First,  the 
B-N  sort  efficiency  drops 
off  fairly  steadily  as  n  in¬ 
creases.  For  n  =  100,  the  B-N 
algorithm  generates  al¬ 
most  three  times  the  mini¬ 
mum  number  of  swap 
pairs.  However,  the  rela¬ 
tionship  is  not  smooth.  For 
example,  increasing  from 
95  to  96  items  requires  7  ad¬ 
ditional  swaps.  Increasing 
to  97  items  requires  64  ad¬ 
ditional  swaps,  and  in¬ 
creasing  to  98  items  re¬ 
quires  32  additional  swaps. 

8.  I  have  not  had  a 
chance  to  test  the  B-N  strat¬ 
egy  against  the  more  popu¬ 
lar  sorting  algorithms.  Ob¬ 
viously,  a  B-N  sort  will  take 
less  time  to  sort  a  sorted  or 
nearly  sorted  list  (fewer 
swaps  are  required)  than  a 
random  list.  However,  if 
we  compare  the  number 
of  swap  pairs  generated  by 
the  B-N  algorithm  with 
n*log2(n),  as  shown  in  Ta¬ 
ble  1,  it  appears  that  for 
large  values  of  n  (say,  15  or 
higher)  a  Bose-Nelson  sort 
may  not  be  able  to  com¬ 
pete  with  a  properly  se¬ 
lected  conventional  sort. 

Richard  J.  Wissbaum 

15553  E.  Wyoming  Dr.  -  H 

Aurora,  CO  80012 
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VIEWPOINT 


Shrink- 
wrapped 
Big  Macs? 


I  read  with  great  interest 
the  editorial  in  the  Decem¬ 
ber  1985  DDJ  concerning 
the  recent  spate  of  litiga¬ 
tion  in  the  software  indus¬ 
try.  I  share  the  concern  ex¬ 
pressed  regarding  current 
trends  in  software  protec¬ 
tion  and  in  particular  with 
how  many  software  pub¬ 
lishers  are  claiming  both 
copyright  and  trade  secret 
protection  for  software 
packages  that  are  widely 
distributed. 

As  an  attorney  specializ¬ 
ing  in  patent,  trademark, 
copyright,  and  other  intel¬ 
lectual  property  law,  I 
have  always  believed  that 
patents  should  protect  un¬ 
derlying  ideas,  and  copy¬ 
rights  should  protect  the 
expression  of  ideas.  The 
United  States  Supreme 
Court  has  clearly  shown 
that  a  patentable  invention 
exists  even  when  the  actu¬ 
al  improvement  exists  sole¬ 
ly  in  software.  Conse¬ 
quently,  if  a  programmer 
develops  a  software  pack¬ 
age  that  performs  new  and 
useful  functions  then  the 
idea  underlying  the  soft¬ 
ware  may  be  patentable. 

On  the  other  hand, 
Copyright  Statute  17  USC, 
(Section  101,  et  seq)  specifi¬ 
cally  provides  that  copy¬ 
right  protection  for  an 
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original  work  of  author¬ 
ship  does  not  protect  "any 
idea,  procedure,  process, 
system,  method  of  opera¬ 
tion,  concept,  principle,  or 
discovery,  regardless  of 
the  form  in  which  it  is  de¬ 
scribed,  explained,  illus¬ 
trated,  or  embodied  in 
such  work." 

The  National  Commis¬ 
sion  on  New  Technological 
Uses  of  Copyrighted  Works 
(CONTU),  empowered  by 
Congress  to  review  copy¬ 
right  legislation,  concluded 
that  copyright  protection 
should  be  afforded  to  com¬ 
puter  programs  and  data¬ 
bases.  It  proposed  changes 
in  the  copyright  statute,  in¬ 
cluding  a  provision  stating 
that  it  would  not  be  an  in¬ 
fringement  for  a  rightful 
possessor  of  a  copy  of  a 
computer  program  either 
to  use  the  program  in  con¬ 
junction  with  a  machine  or 
to  make  archival  copies. 

It  is  interesting  that  this 
section  (Section  117)  as  en¬ 
acted  does  not  use  the  lan¬ 
guage  "rightful  possessor” 
but  rather  uses  "owner  of 
a  copy.”  Although  I  have 
not  been  able  to  find  any 
legislative  history  concern¬ 
ing  the  change,  it  is  clear  to 
me  that  the  party  or  par¬ 
ties  who  caused  this 
change  were  mindful  that 
the  owner  of  a  copyright¬ 
ed  work  may  license  the 
use  of  a  copy  of  the  copy¬ 
righted  work  as  distin¬ 
guished  from  selling  a 
copy  of  the  work.  There¬ 
fore,  if  one  could  argue 
that  what  would  normally 
be  considered  a  sale  of  a 
copy  was  instead  a  license 
to  use  a  copy  then  all  bets 
would  be  off  with  respect 
to  the  aforementioned  sec¬ 
tion  and  to  Section  109(a)  of 
the  copyright  law.  Section 
109(a)  states  that  the  owner 
of  a  particular  copy  is  enti¬ 
tled,  without  the  authority 


of  the  copyright  owner,  to 
sell  or  otherwise  dispose  of 
the  possession  of  that  copy. 

Although  a  license  can 
certainly  be  entered  into 
between  two  parties,  it  re¬ 
quires  more  than  the  open¬ 
ing  of  a  package  to  show  ac¬ 
ceptance  of  terms  of  the 
license;  it  is  also  outside  the 
intention  of  CONTU  that 
trade  secrets  be  preserved 
by  licensing  copies  where¬ 
in  hundreds  or  thousands 
of  licenses  are  made  in 
such  a  manner.  The  soft¬ 
ware  subcommittee  report 
from  CONTU  states  that  it  is 
self-evident  that  trade  se¬ 
crecy  cannot  be  relied 
upon  if  a  program  is  wide¬ 
ly  marketed  or  otherwise 
broadly  distributed. 

Some  software  publish¬ 
ers  have  been  trying  to 
have  their  cake  and  eat  it 
too.  They  claim  to  have 
copyright  protection  and 
are  only  granting  licenses 
to  use  copies  of  the  copy¬ 
righted  work,  such  licenses 
being  accepted  by  the  user 
opening  a  package.  By  their 
reasoning,  virtually  any 
item,  not  just  software, 
could  be  packaged  in  a 
shrink-wrap  form  contain¬ 
ing  a  "license”  limiting  all 
warranties,  liabilities,  and 
even  ownership  of  the 
item!  Certainly  that  was  not 
the  intention  of  CONTU  and 
was  an  oversight  by  Con¬ 
gress  when  the  phrase 
"rightful  possessor”  was 
changed  to  "owner  of  a 
copy." 

I  am  in  the  process  of  in¬ 
vestigating  this  matter  fur¬ 
ther  and  may  recommend 
that  legislation  be  intro¬ 
duced  to  amend  Section 
117  of  the  Copyright  Stat¬ 
ute.  A  change  in  the  statute 
is  the  proper  avenue  to 
clarify  the  right  of  the  pur¬ 
chaser  of  a  computer  pro¬ 
gram  to  make  archival 
copies  and  to  analyze  the 


program.  If  the  publisher 
wishes  to  protect  underly¬ 
ing  inventive  ideas  it 
should  seek  such  protec¬ 
tion  by  way  of  the  patent 
statutes,  which  provide 
protection  for  a  17-year 
term  in  exchange  for  full 
disclosure  of  the  invention. 
I  would  appreciate  com¬ 
ments  and  thoughts  be¬ 
cause  any  change  should 
be  supported  by  all  inter¬ 
ested  parties  seeking  to 
have  fair  protection  af¬ 
forded  the  authors  of  com¬ 
puter  programs. 
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_ C  CHEST _ 

The  Last  of  the  Shell  Support  Routines 


The  code  this  month  is  the  last  of 
the  shell  support  routines.  A 
few  subroutines  are  useful  enough  as 
stand-alone  library  routines  to  men¬ 
tion  here,  but  for  the  most  part  I’ll  let 
the  code  speak  for  itself. 

Ssortf  )  (Listing  Ten,  page  70)  is  an¬ 
other  general-purpose  sort  routine 
modeled  after  the  Unix  qsortf )  rou¬ 
tine  (See  C  Chest,  April  1985).  The 
April  column  implemented  the  rou¬ 
tine  as  a  Quicksort,  whereas  this  ver¬ 
sion  uses  an  adaptation  of  the  Shell 
Sort  in  K  &  R.  For  many  applications 
(especially  those  with  only  a  small 
amount  of  data  to  sort  or  those 
where  the  data  has  already  been 
sorted)  a  Shell  Sort  is  a  better  way  to 
go  than  a  Quicksort.  It  uses  much  less 
code,  and  for  small  N,  it's  about  as  ef¬ 
ficient  as  Quicksort.  Like  qsort(  ), 
ssortf  )  is  passed  four  arguments — 
the  base  address  of  the  array  to  be 
sorted  (base),  the  number  of  elements 
in  the  array  (net),  the  width  of  one 
element  in  bytes  (width),  and  a  point¬ 
er  to  a  comparison  function  that  is 
passed  pointers  to  two  elements  in 
the  array  and  should  otherwise 
work  like  strcmpf )  does.  You  can 
find  more  details  on  how  to  use  this 
routine  and  on  how  a  shell  sort 
works  in  the  April  C  Chest. 

Reargvf )  (Listing  Nine,  page  68)  is 
not  so  much  part  of  the  shell  itself  as 
a  routine  for  other  programs  that  are 
being  run  under  the  shell.  It's  passed 
pointers  to  argv  and  argc,  and  it  re¬ 
places  these  with  another  version 
created  from  the  CMDLINE  environ¬ 
ment  variable  generated  by  the  shell 
when  a  command  is  executed.  The 
shell's  complete  (up  to  2,048-byte) 
command  line  is  passed  to  a  program 
using  this  mechanism,  because  you 


by  Allen  Holub 


can  pass  only  127  characters  via  DOS. 
Reargvf  )  should  be  called  before 
argv  or  argc  are  used  in  maint ).  Note 


that  the  program  name  is  available  as 
argv[0j  if  you  use  reargvf ).  This  is 
not  the  case  in  DOS  Versions  1  or  2. 

If  possible,  you  should  incorporate 
the  code  from  reargvf )  directly  into 
your  root  module  (where  it  belongs). 
It's  provided  here  as  a  separate  func¬ 
tion  because  the  Microsoft  compiler 
doesn't  give  you  the  root  module 
sources,  so  you  have  no  choice  but  to 
call  an  independent  subroutine. 

Dirf  )  (Listings  Seven  and  Eight, 
pages  56  and  57)  is  a  modified  version 
of  the  directory  routines  that  were 
part  of  the  Is  directory  utility  given 
in  the  July  C  Chest.  Dir  is  passed  a 
pointer  to  an  initialized  structure 
(called  a  DIRECTORY)  containing  vari¬ 
ous  commands.  It  gets  a  directory 
and  puts  it  into  an  argv-like  array  of 
pointers  to  strings,  part  of  this  struc¬ 
ture.  Mk—dir(  )  creates  a  DIRECTORY 
structure.  You  set  various  flags  in  the 
structure  to  tell  dirf )  what  to  do  and 
then  call  it  with  a  file  specification 
and  a  pointer  to  the  initialized  DIREC¬ 
TORY  as  its  arguments.  When  the  sub¬ 
routine  returns,  various  fields  of  the 
DIRECTORY  will  have  been  updated  to 
hold  the  proper  file  or  subdirectory 
names  as  well  as  other  information 
such  as  file  sizes  and  a  volume  label. 
The  returned  directory  is  sorted  for 
you  (using  ssortf ) ).  The  routine  del 
_ dirf )  deletes  a  DIRECTORY  structure. 
Dir.h  (Listing  Seven)  has  details  about 
how  to  initialize  the  DIRECTORY  and 
how  dirf )  modifies  it.  If  you  want  to 
see  an  example  of  how  dirf  )  is  used, 
look  in  the  shell  on  lines  478—566  of 
Listing  One  (January  1986).  Refer  to 
the  July  C  Chest  for  details  about  get¬ 
ting  directories  from  DOS  in  general. 

Dir  works  in  slightly  different 


ways  from  the  Is  described  in  July. 
The  major  difference  is  the  total  file 
size.  If  you  specify  a  long  format  list¬ 
ing,  the  file  size  in  bytes  is  still  listed 
as  part  of  the  dirv  entry.  This  size  is 
the  number  of  actual  characters  in 
the  file.  The  total  byte  count,  howev¬ 
er,  reflects  the  number  of  bytes  actu¬ 
ally  occupied  by  the  file  on  the  disk. 
In  DOS  the  minimum  number  of 
bytes  allocated  to  a  file  is  a  "cluster/’ 
which  is  a  contiguous  group  of  disk 
sectors.  On  the  PC/AT  hard  disk,  a 
cluster  requires  2K  (four  512-byte  sec¬ 
tors);  2K  are  required  to  store  a  file, 
even  if  that  file  contains  only  one 
character.  The  totals  returned  by 
dirf )  will  reflect  the  file  sizes,  round¬ 
ed  up  to  the  cluster  size  for  your  par¬ 
ticular  disk.  (It  varies  from  disk  type 
to  disk  type — IK  clusters  are  used  on 
a  354K  double-sided  floppy.) 

Lvalues 

A  few  months  back  I  mentioned  a 
problem  I  was  having  with  the  Lat¬ 
tice  C  compiler.  In  particular,  I  want¬ 
ed  to  be  able  to  say: 

long  x; 
int  *p; 

x  =  *(  (long  *)p  )++  ; 

in  order  to  be  able  to  fetch  a  long-size 
object  pointed  to  by  p  and  then  incre¬ 
ment  p  as  if  it  were  a  pointer  to  long. 
Lattice  kicks  this  code  out  with  an 
"lvalue  required”  error  message. 
The  code: 

long  x; 
char  *p; 

x  =  *(  long  *)p  ; 
p  +  =  sizeoft  long  ); 

is  accepted  by  Lattice.  I  think  the  first 
expression  ought  to  compile,  and  in 
support  of  my  contention,  several 
compilers  do  indeed  accept  the  state¬ 
ment  and  generate  the  correct  code: 
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Microsoft  C  (Version  3.0),  Aztec  C 
(Version  3.20d),  and  Whitesmith's  C 
for  the  68000  are  three  of  these.  Jim 
Howell  writes  that  the  Introl  C  com¬ 
piler  for  the  6809  also  generates  cor¬ 
rect  code.  Jim  also  mentions  that  the 
C-systems  C  compiler  outputs  gar¬ 
bage  but  doesn't  report  an  error. 

Several  people  have  written  about 
this  problem,  most  of  them  advanc¬ 
ing  the  argument  that  the  Lattice  C 
compiler  is  behaving  rationally.  In 
order  to  understand  the  problem  bet¬ 
ter,  we  should  start  by  defining  lva¬ 
lue.  K  &  R  say:  “An  object  is  a  manip- 
ulatable  region  of  storage;  an  lvalue  is 
an  expression  referring  to  an  object. 
An  obvious  example  of  an  lvalue  is 
an  identifier.  There  are  operators 
that  yield  lvalues:  for  example  if  E  is 
an  expression  of  pointer  type,  then 
*E  is  an  lvalue  expression  referring  to 
the  object  to  which  E  points.  The 
name  'lvalue'  comes  from  the  assign¬ 
ment  expression  E1=E2  in  which 
the  left  operand  El  must  be  an  lvalue 
expression.”1 

So,  an  lvalue  is  the  place  where  the 
results  of  an  expression  evaluation  are 
stored.  As  J.  S.  Williams  writes,  howev¬ 
er,  an  "lvalue  is  not  just  an  expression 
on  the  left-hand  side  of  an 
assignment  statement.  A  better  inter¬ 
pretation  is  that  the  lvalue  of  an  ex¬ 
pression  is  the  symbolic  location  of  the 
value  of  the  expression."  That  is,  it’s  an 
address  into  which  the  result  of  the  ex¬ 
pression  evaluation  will  be  put.  An 
lvalue  has  to  be  a  real  place — a  vari¬ 
able  that's  been  declared  somewhere 
or  the  place  pointed  to  by  a  pointer. 

Several  people  mention  a  comple¬ 
mentary  concept  to  an  lvalue — an 
rvalue.  An  rvalue  represents  the  val¬ 
ue  of  an  lvalue.  That  is,  if  an  lvalue  is 
the  address  into  which  we'll  put  the 
result  of  an  expression,  an  rvalue  is 
the  result  itself — the  number  that 
will  be  put  into  the  lvalue.  Consulting 
the  grammar  in  Appendix  A  of  K  &  R 
(pages  214—219),  there's  no  nonter¬ 
minal  symbol  called  an  rvalue.  That 
is,  the  concept  of  rvalue  can  be  used 
to  describe  several  nonterminal  sym¬ 
bols  in  the  grammar,  whereas  an  lva¬ 
lue  is  actually  a  nonterminal.  Thus, 
talking  about  rvalues  might  help  us 
to  understand  the  problem  concep¬ 
tually  but  the  rvalue  is  not  bolted 


into  trie  language  as  is  the  lvalue. 

Nevertheless,  an  rvalue  is  a  useful 
concept.  The  creation  of  an  rvalue 
may  involve  memory  allocation  over 
which  you  have  no  control.  Compil¬ 
ers  sometimes  put  intermediate  re¬ 
sults  of  an  expression  evaluation  into 
scratch  variables  (or  registers)  that 
they  allocate  transparently  to  your 
program.  Thus,  an  rvalue  may  be  as¬ 
sociated  with  an  "anonymous  tem¬ 
porary”  variable  that  you  cannot  ac¬ 
cess  directly. 

Wayne  Throop  writes,  "A  cast  is 
defined  in  K&R  (page  42)  like  this: 
'In  the  construction  “(type-name)  ex¬ 
pression,”  the  expression  is  convert¬ 
ed  to  the  named  type  by  the  conver¬ 
sion  rules  above.  The  precise 
meaning  of  a  cast  is  in  fact  as  if  the 
expression  were  assigned  to  a  vari¬ 
able  of  the  specified  type,  which  is 
then  used  in  place  of  the  whole  con¬ 
struction.’  Now,  this  paragraph  can 
possibly  be  interpreted  to  mean  that 
a  cast  must  be  an  lvalue.  Most  compil¬ 
ers,  however,  do  not  so  implement  it. 
The  key  is  in  the  'converted  to  the 
named  type’  phrase.  A  cast  (poten¬ 
tially)  changes  the  bits  of  the  cast  ex¬ 
pression.  Anonymous  temporaries 
are  normally  not  treated  as  lvalues 
because  things  assigned  to  them  can 
never  be  retrieved  later.” 

In  other  words,  a  cast  generates  an 
rvalue,  and  as  a  result  of  evaluating 
the  cast,  the  number  might  be  copied 
into  a  scratch  variable  in  order  to 
ease  any  necessary  arithmetic  ma¬ 
nipulation  associated  with  the  type 
conversion  (such  as  sign  extension, 
truncation  of  high-order  bits,  and 
floating  point  to  integer  conversion). 
So,  in 

x  =  *(  (long  *)p  )  +  +  ; 

the  (long*)p  may  cause p  to  be  copied 
to  a  temporary  variable  as  part  of  the 
cast  operation,  and  the  +  +  would 
increment  the  temporary  variable, 
not  p  itself. 

The  point  about  temporary  vari¬ 
ables  is  well  taken.  Nevertheless,  just 
because  it’s  easiest  for  the  compiler  to 
always  put  a  cast  variable  into  an 
anonymous  temporary  this  behavior 
is  not  required  by  the  language.  More 
to  the  point,  just  because  a  variable 
might  be  copied  somewhere  else, 
there’s  no  reason  why  the  compiler 
can't  copy  it  back  when  it  has  fin- 
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ished  with  it.  In  any  event,  p  doesn’t 
have  to  be  copied  anywhere  in  the 
problem  we’re  discussing.  We  don’t 
need  to  modify  it;  long  pointers  and 
int  pointers  are  the  same  physically. 
The  difference  lies  in  how  the  object 
pointed  to  is  used,  not  in  any  dissimi¬ 
larities  between  the  pointers  them¬ 
selves.  By  the  same  token,  if  p  isn’t 
copied  to  a  temporary  variable, 
there’s  no  reason  why  you  can’t  in¬ 
crement  it,  and  several  compilers  will 
indeed  let  you  increment  a  cast 
pointer. 

To  my  mind,  the  human  being 
shouldn’t  have  to  do  something  (or 
not  do  something)  for  the  conve¬ 
nience  of  the  compiler;  rather,  the 
compiler  should  do  its  best  to  behave 
rationally,  provided  that  the  input  is 
rational.  A  compiler  that  makes  intel¬ 
ligent  decisions  about  when  to  copy 
and  when  not  to  copy  variables  is  a 
better  compiler — there's  no  point  in 
copying  objects  that  don't  need  to  be 
copied.  Unfortunately  many  compil¬ 
ers — and  Lattice  C  seems  to  be  one  of 
these — don’t  operate  intelligently. 

As  a  footnote,  a  more  technically 
correct  argument  against  increment¬ 
ing  a  cast  variable  is  that  there’s  no 
obvious  way  to  parse  such  an  expres¬ 
sion  using  the  formal  grammar  in 
the  back  of  K  &,  R.  Because  several 
compilers  accept  the  construct,  it's 
obviously  possible  to  write  a  gram¬ 
mar  in  which  incrementing  a  cast 
variable  is  acceptable.  More  to  the 
point,  the  grammar  in  K&R  isn’t 
used  “as  is”  in  any  C  compiler  that  I 
know  of.  Everybody  (including 
K  &.  R)  has  modified  it  a  little  to  make 
it  more  realistic  when  they  write  a 
real  compiler.  The  grammar  in  my 
copy  of  the  draft  proposed  ANSI  stan¬ 
dard  bears  little  relation  to  the  one  in 
K  &  R,  so  until  the  ANSI  standard  is 
formalized,  I  don’t  think  the  gram¬ 
matical  argument  is  valid  either. 

There  is  one  argument  that  I  do 
think  is  valid.  As  I’ve  learned  the  hard 
way  y  =  *((long*  )p)+  +  is  not  porta¬ 
ble,  at  least  it's  not  portable  to  Lattice. 
On  the  other  hand,  y  =  *(long* )p;  p 
+  =  sizeofllong)  is  acceptable  to  all 
compilers.  This  second  method  is 
therefore  preferable  for  portability 
reasons. 

Problems  with  The  Microsoft 
€  Compiler 

A  few  months  ago  Microsoft  sent  me 


a  review  copy  of  the  new  version 
(3.0)  of  its  C  compiler.  I’ve  been  using 
it  since  then  (to  develop  the  shell  I’ve 
been  talking  about  since  January, 
among  other  things). 

I  really  want  to  like  this  compiler.  It 
generates  compact  code,  and  its  im¬ 
plementation  of  the  language  is  one 
of  the  best  I’ve  found  (it  supports  enu¬ 
merated  types  and  strong  type  check¬ 
ing  a  la  the  proposed  ANSI  standard). 
Moreover,  its  library  documentation 
is  organized  quite  nicely  with  all  the 
functions  in  alphabetical  order  in¬ 
stead  of  grouped  by  function  (a  prac¬ 
tice  I  never  could  understand).  You 
can  find  the  documentation  for  any 
routine  in  the  library  quickly  just  by 
looking  it  up.  There’s  no  need  to  con¬ 
sult  a  cross-reference,  then  an  index  , 
and  then  look  it  up.  Microsoft  has 
tried  to  minimize  the  number  of 
functions  described  by  a  single  entry 
(very  little  of  the  one-page-for-15-simi- 
lar-functions  business),  and  every  en¬ 
try  has  a  See  Also  section  and  an  Ex¬ 
amples  section.  I  wish  every 
compiler's  library  documentation 
was  organized  as  nicely  as 
Microsoft's. 

The  library  is  one  of  the  more  com¬ 
plete  that  I’ve  seen,  too,  especially  in 
the  operating  system  support  area. 
For  example,  it  has  both  a  getenv  and 
a  putenv  routine  so  you  can  not  only 
retrieve  a  variable  from  the  current 
environment  but  you  can  add  a  vari¬ 
able  to  it  as  well.  Putenv  lets  you  pass 
variables  to  a  spawned  process  pret¬ 
ty  easily,  without  having  to  go 
through  a  temporary  file.  The  com¬ 
piler  also  comes  with  a  Unix-like  ver¬ 
sion  of  the  cc  driver  program.  (It  can 
compile  and  link  your  source  code  in 
one  step.) 

Unfortunately,  the  compiler  itself 
has  several  serious  problems.  Like 
most  compilers,  the  Microsoft  com¬ 
piler  is  actually  several  programs 
that  are  invoked  in  sequence  by  a 
controlling  driver  program.  The  var¬ 
ious  programs  communicate  with 
each  other  via  temporary  files  and 
the  command  line.  The  first  things  I 
tried  to  compile  were  the  hyphen¬ 
ation  routines  from  October’s  C  Chest 
column,  and  the  compiler  wouldn't 
do  it.  Pass  3  of  the  compiler  kicked 
out  an  incomprehensible  error  mes¬ 
sage  that  referred  to  a  line  number  in 
a  temporary  file  that  was  erased  by 
the  driver  program  (or  so  I  assume — 


the  file  was  not  to  be  found  on  the 
disk).  So,  I  thought  to  myself,  I’ll  just 
run  the  passes  by  hand  instead  of  let¬ 
ting  the  supplied  driver  program  do 
it  for  me.  No  good.  The  individual 
passes  of  the  compiler  are  not  docu¬ 
mented — anywhere.  You  can’t  run 
them  yourself.  More  to  the  point, 
were  I  a  naive  user  the  situation 
would  be  more  incomprehensible 
because  the  documentation  doesn’t 
explain  that  compilation  involves  the 
invocation  of  programs  that  you 
know  nothing  about.  Anyway,  I 
eventually  fixed  the  problem  by 
stripping  the  large  arrays  of  initial¬ 
ized  data  out  of  the  offending  file  and 
putting  them  into  a  second  file.  The 
compiler’s  problem  seems  to  have 
something  to  do  with  symbol  table 
space  overflow,  but  who  knows? 

Another  related  problem — the 
compiler  lets  you  use  several  environ¬ 
ment  variables  to  pass  it  information. 
The  INCLUDE  environment,  for  exam¬ 
ple,  can  hold  a  list  of  places  to  look  for 
//include d  files.  It  seems,  however, 
that  the  driver  program  knows  about 
these  environments,  but  the  other 
programs  that  make  up  the  compiler 
do  not.  In  particular,  the  driver  pro¬ 
gram  passes  the  contents  of  the  IN¬ 
CLUDE  environment  to  the  subpro¬ 
grams  using  the  DOS  command  line. 
The  DOS  command  line  is  limited  to 
127  bytes,  so  if  the  INCLUDE  environ¬ 
ment  has  too  many  characters  in  it, 
the  command  line  can  be  truncated 
and  the  invoked  subprogram  will  spit 
out  an  incomprehensible  error  mes¬ 
sage.  Again,  this  behavior  is  not  docu¬ 
mented.  You  are  not  told  to  limit  the 
length  of  the  INCLUDE  environment. 

The  above  problems  are  character¬ 
istic  of  a  general  nonchalance  to¬ 
ward  error  processing  on  the  part  of 
Microsoft.  The  compiler’s  normal  er¬ 
ror  processing,  even  when  it’s  work¬ 
ing  properly  is  among  the  worst  I've 
ever  seen.  Its  error  messages  are  for 
the  most  part  uninformative  and  er¬ 
ror  recovery  is  nonexistent.  For  ex¬ 
ample,  the  message 

“Syntax  error  ’{’  ” 

was  generated  by  a  missing  semico¬ 
lon  several  lines  above  the  one  that 
was  flagged  in  the  error  message. 
The  compiler  is  showing  you  the 
symbol  following  the  semicolon,  the 
one  that  confused  it.  Because  a  miss- 
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ing  semicolon  is  perhaps  the  most 
common  error  in  a  C  program,  you’d 
think  that  Microsoft  would  at  least 
handle  this  one  carefully — but  no. 
Semicolons  weren’t  mentioned  in 
any  of  the  hundred  spurious  error 
messages  that  followed.  (I’m  not  ex¬ 
aggerating  the  number  of  messages 
either,  there  really  were  a  hundred 
of  the  things.)  And  then,  to  add  insult 
to  injury,  the  compiler  aborted,  tell¬ 
ing  me  that  there  were  too  many  er¬ 
rors  to  continue  processing  even 
though  the  missing  semicolon  was 
the  only  real  error  in  the  file. 

This  sort  of  behavior  is  repeated 
j  with  disgusting  regularity.  A  missing 
semicolon,  colon,  parenthesis,  or 
j  curly  bracket  is  a  disaster.  Misspell  a 
j  keyword,  and  all  is  lost.  Spurious  er- 
I  ror  messages  are  a  serious  problem 
in  themselves,  and  they  can't  be 
eliminated  entirely,  but  a  well-de¬ 
signed  compiler  ought  to  be  able  to 
recover  from  an  error  within  a  few 
statements  and  then  go  on  process- 
j  ing.  At  the  very  least,  it  could  skip  to 
)  the  next  subroutine  declaration  and 
then  start  processing  from  there  (you 
can  do  that  with  a  regular  expres¬ 
sion).  As  far  as  I  can  tell,  though,  the 
Microsoft  compiler  makes  no  at¬ 
tempt  to  recover. 

These  goings-on  dramatically  slow 
a  program’s  development  time.  In¬ 
stead  of  compiling,  fixing  five  or  ten 
errors,  and  then  recompiling,  I  have 
to  compile,  fix  only  one  error,  com¬ 
pile  again,  fix  one  error,  and  so  forth. 
I  may  have  to  recompile  10  or  15 
times  to  get  all  the  errors  fixed,  a 
very  time-consuming  process  to  say 
the  least.  I  don’t  care  how  fast  a  com¬ 
piler  is,  if  I  have  to  recompile  15 
times  to  find  15  errors,  I’ll  never  fin¬ 
ish  my  program. 

Another  real  problem  here  is  the 
error  message  not  telling  me  what 
the  error  was.  If  I  were  not  already  a 
reasonably  proficient  C  program¬ 
mer,  I’d  never  have  found  some  of 
my  errors  (which  were  sometimes 
several  lines  above  the  one  flagged 
by  the  error  message).  If  you  don’t  al¬ 
ready  know  C  very  well,  the  Micro¬ 
soft  compiler  is  a  waste  of  money. 
You'll  get  so  disgusted  with  its  behav¬ 
ior,  you'll  never  learn  the  language 
well  enough  to  debug  any  but  the 
simplest  program. 

Another  problem  is  that  the  docu¬ 
mentation  doesn’t  mention  various 


I  important  differences  between  the 
way  a  Microsoft  library  routine 
j  works  and  the  way  that  the  equiva- 
;  lent  Unix  routine  works.  The  most 
serious  of  these  problems  that  I’ve 
found  so  far  is  in  the  spawn  function. 
It  turns  out  that  files  opened  by  a  par¬ 
ent  process  are  closed  when  the 
child  process  terminates!  (And  I  don’t 
use  the  /  lightly.)  It  seems  OK  for  a 
child  to  inherit  copies  of  the  parent's 
file  descriptors  (which  is  document¬ 
ed),  but  the  child  shouldn't  be  able  to 
modify  them,  much  less  close  them. 
Even  worse,  it  is  an  e?cit(  )  call  in  the 
child  that  does  the  closing,  not  an  ex¬ 
plicit  call  to  closet  ).  In  other  words, 
there  is  no  way  for  a  file  to  stay  open 
after  a  child  is  spawned.  Maybe  this 
isn’t  a  problem  with  the  spawn  func¬ 
tion  at  all,  maybe  it’s  a  bug  in  MS  DOS. 
In  any  event,  bug  or  not,  this  aber¬ 
rant  behavior  should  be  document¬ 
ed.  There  isn’t  a  word  about  it  in  the 
manual,  and  it  took  me  half  a  day  to 
i  track  it  down. 

There  are  a  few  other  inconsisten- 
!  cies  (such  as  strncpy  pads  out  the 
string  with  nulls  to  the  maximum 
i  count — why?),  but  I  won’t  go  into  all 
!  of  them  here.  The  compiler  also  has 
several,  more  minor  problems — for 
example,  it  ignores  the  last  line  of  a 
file  if  it  isn’t  terminated  with  a  new 
line.  An  #endif  without  a  CR  gives  an 
I  "unexpected  end  of  file”  message. 
The  library  function  fgetst  )  doesn't 
have  this  bug  in  it — why  does  the 
compiler? 

Though  the  library  documentation 
is  nicely  done,  the  User's  Guide  is  aw¬ 
ful.  It  has  very  little  discussion  of  un¬ 
familiar,  Microsoft-specific  parts  of 
|  the  language.  This  lack  of  detail  is 
made  more  intolerable  because  the 
User's  Guide  spends  thousands  of 
words  talking  about  topics  with 
which  most  readers  will  be  familiar. 
For  example,  on  page  25  it  says:  "It  is 
|  recommended  that  you  create  a  sep- 
I  arate  directory  for  each  type  of 
file.  .  .  .  (Refer  to  your  MS-DOS  docu¬ 
mentation  if  you  are  unfamiliar  with 
the  procedures  for  setting  up  and 
maintaining  directories).”  Does  Mi¬ 
crosoft  seriously  believe  that  a  C  pro¬ 
grammer  doesn't  know  how  to  set 
up  a  directory?  Another  example  is 
on  page  36  where  we  find  a  long 
treatise  on  how  to  create  a  batch  file: 
"You  can  create  an  MS-DOS  batch  file 
|  to  set  up  the  compiler  environment 


|  and  invoke  the  compiler.  Creating 
and  using  batch  files  is  discussed  in 
!  full  in  your  MS-DOS  manual.  This  sec- 
I  tion  is  intended  simply  to  demon¬ 
strate  possible  uses  of  the  MSC  com¬ 
mand  in  a  batch  file  ...”  and  on,  and 
on,  and  on.  The  manual  talks  about 
how  to  use  batch  files  for  the  rest  of 
the  page  and  most  of  the  next.  Most 
readers  don’t  need  to  be  told  what  a 
batch  file  is  ad  nauseam;  those  who 
don’t  know  can  find  the  material  in 
the  DOS  manual.  In  fact,  the  User's  j 
!  Guide  could  be  shortened  by  about  50  I 
1  percent  if  it  started  out  with  the  sen¬ 
tence:  "This  manual  assumes  that 
j  you  are  familiar  with  MS  DOS.  If  you 
are  not,  please  read  your  MS  DOS  doc¬ 
umentation  before  proceeding.  ” 
Why  make  readers  wade  through 
pages  of  useless  verbiage  to  find  the 
few  buried  pieces  of  real  informa¬ 
tion  and  then  not  provide  them  with 
adequate  information  when  a  new 
topic  is  introduced? 

Worse  than  this  garbage  is  the  lack 
i  of  real  information  on  many  obscure  ! 
i  or  hard-to-understand  parts  of  the 
}  Microsoft  C  implementation.  The  ! 
’  keyword  far,  for  example,  is  used  to  I 
j  create  a  32-bit  pointer  in  a  small  mod-  ! 
el  program;  but  the  user’s  manual  j 
gives  you  almost  no  information,  and  j 
|  no  examples  whatsoever,  on  how 
this  keyword  should  be  used.  I  tried 
for  about  half  an  hour  to  declare  a 
typedef  for  a  far  pointer  to  an  un¬ 
signed  object  before  I  hit  on  the  right 
:  combination  of  keywords.  The  man¬ 
ual  was  no  help  and  neither  were 
the  error  messages,  most  of  which  j 
said  "syntax  error”  and  little  else.  I 
don’t  mind  Microsoft’s  introducing  a 
|  new  keyword,  especially  one  as  use- 
i  ful  as  this  one,  but  it  should  be  docu-  ! 
|  mented  up  the  wazoo.  It  is  not. 

One  final  problem  and  then  I'll 
quit.  It’s  impossible  (or  rather,  so 
hard  that  I  don’t  want  to  bother)  to  j 
!  make  either  ROMable  code  or  .COM  i 
files  with  the  Microsoft  compiler.  In  j 
the  course  of  my  normal  consulting 
work,  I  have  to  write  a  lot  of  ROMable 
code.  To  do  this  with  most  compilers,  I 
you  need  a  copy  of  the  C  root  module  j 
so  that  you  can  modify  it  to  do  your 
system  initializations.  You  also  need  j 
a  special  root  module  if  you  want  to  j 
make  .COM  files.  Lattice  and  Aztec 
both  provide  the  root  module  source 
with  their  compilers.  Microsoft  does 
not.  When  I  called  Microsoft  to  ask 
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|  about  getting  a  copy  the  staff  were 
j  pretty  reluctant  even  to  talk  about  it. 

I  Finally  I  managed  to  talk  to  Sandra 
;  Jacobson,  the  VP  in  charge  of  C  prod-  j 
uct  marketing,  and  she  told  me  that  , 
the  root  source  was  available  but  that 
it  cost  $500  (that's  five  hundred — two 
zeros  after  the  five).  This  left  me 
speechless  for  a  moment — $500  is 
more  than  the  compiler  costs.  For  ! 
$500  Manx  gives  you  two  compilers  i 
(one  optimizing,  the  other  not);  the  j 
complete  source  code  for  the  entire 
I/O  library,  not  just  the  root  module;  | 
copies  of  several  Unix  utilities  ( grep ,  | 
Is,  make,  diff,  and  a  version  of  the  vi  j 
editor);  an  assembler;  a  linker;  and 
several  other  utilities.  Where  does 
Microsoft  get  off  asking  $500  for  100  , 
lines  of  code,  without  which  their  ; 
compiler  is  useless  to  anyone  who 
has  to  put  a  program  into  ROM?  The 
only  response  I  got  was  that  not  j 
many  of  its  customers  require  it.  j 
Well,  I  require  it.  The  company 
wasn’t  sympathetic.  Then  it  said  that 
,  another  reason  for  not  releasing  the  | 
root  module  is  that  it  didn’t  want  to 
|  provide  user  support  for  it — the  l 
module  was  "too  complex"  and  Mi-  I 
crosoft  "wasn’t  too  proud  of  the  way  j 
that  the  program  looked.”  To  j 
my  mind,  this  doesn’t  speak  well  for  j 
the  quality  of  Microsoft's  program- 
J  ming  or  of  its  support.  If  Microsoft 
can't  explain  the  internal  workings 
|  of  its  own  compiler,  who  can?  It 
seems  that  it'll  only  provide  support  I 
if  your  question  isn’t  too  hard.  To  all  j 
appearances  Microsoft  has  gone  the 
way  of  several  large  corporations: 
"We  don’t  care,  we  don't  have  to.” 

In  conclusion,  the  Microsoft  C  com¬ 
piler  is  a  good  implementation  of  the 
C  language,  with  a  very  complete  I/O 
J  library  and  laudable  library  docu¬ 
mentation.  It  generates  compact  code 
|  and  is  easy  to  use  (once  you  wade 
through  the  User's  Guide).  As  far  as  I 
;  can  tell,  the  code  it  produces  is  error- 
free.  Because  of  serious  flaws  in  the  \ 
j  error  recovery  mechanism,  however,  [ 
|  an  extremely  poorly  written  User’s  j 
{  Guide,  and  a  certain  reticence  on  Mi- 
|  crosoft's  part  to  really  support  its  own 
■  product,  the  compiler  is  useless  to 
anyone  who  is  not  already  a  very  ex- 
j  perienced  C  programmer  and  to  any¬ 
one  who  has  to  generate  ROMable 
code  or  do  serious  systems  program¬ 
ming.  Though  the  library  documenta¬ 
tion  is  well  organized,  it  is  opaque, 


not  telling  you  anything  about  the  in-  I 
ternal  workings  of  the  routines. 
There's  no  way  (short  of  disassem¬ 
bling  the  library)  to  make  ROMable  j 
code  or  .COM  files  with  the  Microsoft  j 
compiler.  Even  if  you’re  an  experi-  j 
enced  programmer,  I’m  not  sure 
you'd  be  willing  to  put  up  with  the  I 
awful  error  recovery  which  is  bound  j 
to  slow  up  your  development  time,  or  ; 
spend  inordinate  amounts  of  time  j 
trying  to  figure  out  how  a  library  rou-  j 
tine  works  and  what  undocumented  j 
bugs  it  contains. 

As  I  write  this,  a  copy  of  the  Manx  j 
Aztec  C  86  compiler  has  just  arrived  ' 
in  the  mail  and  a  copy  of  Lattice,  Ver¬ 
sion  3,  is  on  the  way.  I'll  report  back 
sometime  in  the  next  few  months,  af¬ 
ter  I’ve  had  a  chance  to  use  them  for  a 
while. 

Shell  Availability 

This  column  is  part  of  a  four-part  se¬ 
ries  describing  the  entire  shell.  A  re¬ 
print  of  all  four  parts  along  with  a 
disk  containing  the  listings  and  an  ex¬ 
ecutable  version  of  the  shell  are 
available  for  $29.95  from  Dr.  Dobbs 
Journal,  2464  Embarcadero  Way, 
Palo  Alto,  CA  94303.  Please  see  the  ad¬ 
vertisement  on  page  71. 

\ote 

1.  Kernighan  &,  Ritchie,  The  C  Pro¬ 
gramming  Language  (Englewood 
Cliffs,  N.J.:  Prentice-Hall,  1978),  183. 
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A  Variable 


Metric  M 


inimizer 


by  Joe  Marasco 


This  article  de¬ 
scribes  a  vari¬ 
able  metric 
minimizer,  a  program 
that  finds  the  set  of  pa¬ 
rameters  to  a  function 
that  will  produce  the 
smallest  output  value 
from  that  function. 

Minimization  is  a  com¬ 
mon  problem  in  many 
fields.  A  familiar  exam¬ 
ple  of  this  process  is  the  least  squares  fitting  of  a  set  of  data 
to  a  straight  line.  Here,  an  explicit  set  of  equations  is  used 
to  derive  the  optimal  value  for  the  slope  and  the  intercept 
of  a  straight  line  that  approximates  the  input  data.  (The 
minimized  function  is  the  sum  of  the  squares  of  the  devi¬ 
ations  of  the  data  points  from  the  straight  line.)  That  is, 
least  squares  fitting  finds  the  equation  of  the  line  that  goes 
as  closely  as  possible  through  the  middle  of  a  set  of  data 
points.  Of  course  these  points  have  to  be  linelike  to  begin 
with;  forcing  randomly  scattered  data  into  a  line  has  no 
meaning. 

The  least  squares  function,  because  it's  using  lines,  re¬ 
quires  you  to  find  two  parameters  (the  slope  and  the  in¬ 
tercept).  To  fit  a  parabola  rather  than  a  line  to  your  data, 
you'd  have  to  find  three  parameters  instead  of  two.  In 
general,  polynomial  fitting  for  a  degree  n  polynomial  re¬ 
quires  you  to  find  n  + 1  parameters. 

But  you  need  not  limit  yourself  to  polynomials.  Your 
data  might  fit  a  more  exotic  combination  of  powers,  such 
as  a  rational  fraction  or  a  continued  fraction.  It  might  also 
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contain  terms  with 
trig,  log,  or  other  tran¬ 
scendental  functions. 
In  general,  we’d  like  to 
be  able  to  find  the 
minimum  for  any 
function,  regardless  of 
the  complexity.  All 
data  can’t  be  meaning¬ 
fully  depicted  as  a 
straight  line. 

When  no  limits  are 
put  on  the  parameters  to  a  function,  we  have  an  "uncon¬ 
strained”  minimization  problem  in  n  dimensions  (where 
n  is  the  number  of  parameters  that  can  vary).  Imagine  an 
n-dimensional  surface;  our  problem  is  to  find  the  "low¬ 
est”  point  on  the  surface.  As  you  might  expect,  this  pro¬ 
cess  can  be  both  difficult  and  time  consuming.  The 
"search  space”  becomes  very  large  as  the  dimension  of 
the  problem  increases.  By  the  late  60s  and  early  70s,  the 
general  minimization  problem  was  brought  under  con¬ 
trol  on  large  mainframe  computers  for  functions  of 
about  10  —  20  parameters.  Today  methods  exist  for  han¬ 
dling  much  larger  problems,  but  these  are  not  really 
amenable  to  microcomputer  implementation. 

The  program  presented  here  uses  methods  now  ac¬ 
cepted  as  both  robust  and  efficient.  That  is,  these  meth¬ 
ods  can  handle  a  wide  variety  of  functions  and  data  with¬ 
out  failing,  and  they  can  find  a  minimum  in  a  shorter 
period  (fewer  iterations)  than  other  methods.  Some  meth¬ 
ods  seek  minima  by  a  sort  of  "curve  crawling.”  Like  the 
proverbial  drop  of  water,  they  tend  to  smell  "down”  and 
go  in  that  direction. 

The  steepest  descent  method,  for  example,  looks  at  the 
local  topology  (read:  derivative  information)  and  points 
itself  orthogonally  (at  right  angles)  to  the  level  curves  in 
an  effort  to  point  toward  the  minimum.  The  process  is 


The  program  does  unconstrained 
minimization  in  n  dimensions  by 
looking  at  the  global  topology  of 
the  problem  as  well  as  local  infor¬ 
mation  from  the  derivatives. 
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clarified  by  thinking  of  a  contour  map  of  a  volcanic  cra¬ 
ter.  Just  below  the  rim,  the  contour  map  will  show  a 
series  of  concentric  circles.  The  program  looks  at  this 
map,  points  itself  toward  the  center  by  finding  a  direc¬ 
tion  at  a  right  angle  to  a  contour  line,  and  off  it  goes. 
There  are  other  considerations  in  a  real  problem.  For  ex¬ 
ample,  how  big  a  step  do  you  take?  (You  don’t  want  to  go 
up  the  other  side.)  You  get  the  idea  though.  The  spacing 
of  the  contour  lines  will  help  you  with  step  size. 

Of  course  this  example  is  a  bit  contrived.  Many  geome¬ 
tries  aren’t  concentric  circles.  The  contour  lines  may  often 
look  like  wickedly  curved  and  contorted  bananas,  making 
the  program  waste  a  lot  of  time  going  toward  the  mini¬ 
mum.  Think  of  a  meandering  river:  It’s  always  going 
downhill.  At  each  point  it  is  locally  following  the  largest 
gradient.  Nevertheless,  when  viewed  from  above,  the  riv¬ 
er  doesn’t  follow  the  shortest  path  from  the  top  to  the 
bottom. 

The  methods  I  have  used  are  called  "quasi-Newton  pos¬ 
itive  definite  secant  update"  methods.  The  "variable  met¬ 
ric’’  part  comes  from  looking  at  the  global  topology  of  the 
problem  in  addition  to  the  local  information  given  by  the 
derivatives.  That  is,  we’re  looking  at  the  river  both  from 
above  and  from  the  perspective  of  the  river  itself.  These 
methods  try  to  take  bananalike  contours  and  transform 
coordinates  internally  so  that  they  appear  to  the  algo¬ 
rithm  as  concentric  circles.  Because  the  "metric”  for  do¬ 
ing  this  transformation  changes  as  we  move  about,  the 
methods  are  called  variable  metric  methods.  These  meth¬ 
ods  converge  more  rapidly  to  the  minimum  than  do 
other  approaches. 

Davidon  seems  to  have  been  the  first  person  to  hit  on 
these  methods.  The  Davidon-Fletcher-Powell  (DFP)  method 
is  still  one  of  the  best  algorithms  available.  A  similar  meth¬ 
od — the  Broyden-Fletcher-Goldfarb-Shanno  (BFGS)  meth¬ 
od — is  thought  to  be  somewhat  superior  for  some  prob¬ 
lems.  These  two  methods  have  survived  lots  of  empirical 
testing,  and  most  people  consider  them  to  be  the  best.  Both 
methods  are  used  in  the  accompanying  program  as  well 
as  a  "steepest  descent”  method  for  comparison's  sake. 

A  word  of  caution:  All  these  methods  have  some  limita¬ 
tions.  They  all  tend  to  find  a  local  minimum,  but  over  the 
hill  there  may  be  a  deeper  valley.  Your  local  minimum 
may  not  be  the  global  minimum.  Hence  these  methods  may 
depend  somewhat  on  where  you  start  them.  The  better 
your  original  estimate  of  where  the  minimum  might  be, 
the  better  chance  you  have  of  not  getting  stuck  in  the 
wrong  one  when  there  are  multiple  minima.  Unfortunate¬ 
ly  in  higher  dimensions  it’s  often  difficult  to  guess  how 
many  minima  there  might  be  or  where  they  might  be.  Sad¬ 
dle  points  can  be  troublesome  too,  fooling  the  program  into 
thinking  that  it  has  arrived  at  the  minimum.  This  difficulty 
is  compounded  as  you  use  higher  dimensions. 

Theory 

This  section  describes  briefly  how  the  minimizer  works 
so  that  you  can  follow  the  code.  The  description  is  pretty 
meaty;  you  may  want  to  skip  past  it  if  the  mathematics  of 
the  problem  don’t  interest  you.  On  the  other  hand,  if 
you’d  really  like  to  understand  the  inner  workings  of  the 
mathematics,  any  of  the  references  at  the  end  of  this  arti¬ 
cle  will  be  more  than  sufficient. 


The  program  loop  is  divided  into  four  main  parts:  The 
first  uses  the  current  approximation  to  the  inverse  Hessian 
matrix  (this  contains  what  I’ve  previously  called  the  global 
topology  information).  The  current  values  of  the  deriva¬ 
tives  of  your  function  with  respect  to  each  of  the  parame¬ 
ters  are  also  used  to  obtain  a  search  direction.  As  long  as 
the  matrix  remains  positive  definite,  the  theory  guaran¬ 
tees  that  we  will  always  point  downward.  So,  our  mini¬ 
mum  will  decrease  at  each  step  if  nothing  goes  awry. 

In  the  second  part,  the  step  size  is  optimized  with  a 
linear  search  along  the  direction  chosen  in  part  1.  A  rea¬ 
sonable  trial  step  size  is  attempted,  and  the  value  of  the 
function  and  its  derivatives  are  calculated  for  the  new 
location.  Once  again,  if  everything  works,  this  trial  step 
brackets  the  true  minimum.  A  cubic  interpolation  be¬ 
tween  the  previous  position  and  the  trial  position  will 
find  our  new  minimum.  Although  this  search  doesn't 
have  to  be  exact,  we  can  run  into  problems  here.  The 
system  will  quit  if  the  cubic  interpolation  fails  because  of 
strange  geometries;  if  the  minimum  was  not  bracketed,  a 
step  size  larger  than  the  trial  may  be  attempted.  In  any 
event,  the  result  of  this  step  is  a  new  proposed  minimum. 

In  the  third  part  we  decide  whether  or  not  we’ve  fin¬ 
ished.  If  the  new  minimum  isn’t  lower  than  the  old  one, 
we  stop  because  the  rounding  off  is  probably  killing  us — 
the  new  minimum  is  always  supposed  to  be  lower.  (Inci¬ 
dentally  this  means  you  cannot  go  out  of  a  valley  to  a 
lower  valley  unless  something  unusual  happens.)  We  ll 
also  quit  if  the  estimated  distance  to  the  minimum,  as 
computed  internally  by  the  program,  is  smaller  than  the 
first  stopping  criterion. 

We  stop  if  the  percent  change  in  the  minimum  (from 
the  previous  value)  is  less  than  the  second  stopping  crite¬ 
rion.  No  matter  what  happens,  we  stop  if  we’ve  used  up 
the  number  of  iterations  allowed  by  the  user.  If  we  de¬ 
cide  to  exit,  the  reason  for  stopping  is  returned  to  the 
main  program. 

Should  we  make  it  through  part  3,  we  prepare  for  an¬ 
other  iteration.  Here,  derivatives  of  the  function  at  the 
new  minimum  are  computed  (so  that  they'll  be  ready  for 
part  1  on  the  next  go-round).  The  inverse  Hessian  matrix 
is  updated  here  too,  using  either  the  Davidon-Fletcher- 
Powell  or  Broyden-Fletcher-Goldfarb-Shanno  updating 
method.  Both  of  these  methods  guarantee  that  the  in¬ 
verse  Hessian  will  remain  positive  definite,  so  the  new 
minimum  will  indeed  be  lower  than  the  old  one.  If  the 
steepest  descent  is  being  used,  the  update  is  skipped  be¬ 
cause  the  identity  matrix  is  always  used  in  this  case.  The 
update  completed,  we  return  to  part  1  above  for  another 
spin  through  the  loop. 

As  you've  probably  noticed,  derivatives  are  computed 
twice  per  iteration  in  this  scheme,  a  penalty  of  all  meth¬ 
ods  that  include  a  linear  search.  When  minimizing  using 
experimental  data  sets  with  many  points,  the  computa¬ 
tion  of  the  derivatives  is  by  far  the  most  time-consuming 
process.  Each  time  we  evaluate  the  derivative  vector,  we 
need  to  make  2n  function  calls,  where  n  is  the  number  of 
parameters  in  the  function.  The  number  of  function  calls 
per  iteration  is  approximated  as  4n+2.  Anything  you  can 
do  in  your  function  to  speed  things  up  will  have  a  great 
effect  on  total  computation  time.  The  other  computations 
take  much  less  time. 
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A  final  word  on  the  derivatives — there  are  2n  function 
evaluations  per  derivative  because  the  derivatives  are 
computed  by  a  simple  symmetric  finite  difference.  The 
function  is  computed  once  after  adding  an  epsilon  to  the 
value  of  the  parameter  in  question.  It's  computed  a  sec¬ 
ond  time  after  subtracting  an  epsilon.  Then  we  take  the 
difference,  dividing  by  twice  epsilon  and  holding  all 
other  parameter  values  constant. 

Note  that  if  the  epsilon  is  too  small,  the  derivative  will 
be  imprecise  (because  we  may  be  subtracting  two  num¬ 
bers  that  are  almost  equal  and  then  magnifying  the  dif¬ 
ference  by  dividing  by  a  small  number).  On  the  other 
hand,  if  the  epsilon  is  too  big  the  approximation  of  the 
derivative — the  secant  instead  of  the  tangent,  as  it  were — • 
will  be  too  gross.  This  problem  has  no  easy  solution.  The 
default  is  set  to  something  reasonable,  and  the  derivative 
calculation  can  be  examined  by  setting  "debug”  to  3 
(more  on  this  in  a  moment).  You  can  then  set  derivative 
step  sizes  individually  for  each  parameter  on  input.  After 
that  you  have  to  fend  for  yourself. 

The  Program 

The  program  I  have  just  described  solves  only  small-  to 
medium-size  problems;  it's  dimensioned  to  handle  up  to 
ten  parameters,  although  you  can  adjust  this  number.  To 
complete  the  program,  you  need  to  add  a  function  repre¬ 
senting  your  model,  compile  that  function,  and  link  it 
with  the  other  modules.  The  load  module  then  does  the 
minimization,  subject  to  various  input  commands  you 
give  it.  Actually  the  design  of  the  system  is  predicated  on 
building  a  library  of  models  so  that  various  optimizations 
can  be  performed  against  sets  of  data — more  on  building 
this  library  in  a  moment. 

My  version  of  the  system  was  built  on  an  Osborne  com¬ 
puter  (running  CP/M  2.2)  using  Software  Toolworks’s  C/80 
compiler  (Version  3.0)  with  floating-point  support.  Digital 
Research's  relocating  assembler,  library  manager,  and 
linker  were  also  used.  All  these  products  were  up  to  the 
task,  although  a  special  tip  of  the  hat  goes  to  Walt  Bi- 
lofsky’s  folks  at  Software  Toolworks  for  an  exceptional 
product. 

Most  of  the  C  code  should  port  easily  to  other  ma¬ 
chines.  The  file  global. h  that  is  included  in  all  source  files 
contains  conditional  compilation  directives  to  ease  the 
porting  task.  For  example,  the  Software  Toolworks  com¬ 
piler  doesn't  support  the  type  double,  so  I’ve  included  a 
* define  for  the  C/80  compiler  to  change  all  doubles  to 
floats. 

If  you're  using  the  C/80  compiler,  leave  the  * define  C80 
statement  in  global. h.  Otherwise,  remove  it  to  get  the 
standard  # includes  for  stdio.h  and  math.h.  I  used  some  of 
Software  Toolworks's  library  functions:  atoi,  atof,  fabs, 
strcmp,  strcpy,  strlen,  isspace,fopen,  and  fclose  are  Unix- 
like  and  should  pose  no  problems.  I’ve  assumed  that  is- 
spacei  J  is  a  subroutine  rather  than  a  macro,  however.  If 
isspacef  )  is  defined  by 

#  define  isspace(c)  ( (c)=  = ' '  1 1  (c)  =  =  ’  ’  \t'  1 1  (c)  =  =  '\n') 


the  invocation 
isspacel  *p+  +  ) 
is  expanded  to 

<*p-M-  =  =  ’  '!l*p+  +  =  =  "\t'll’p+  +  =  =  '\n’) 

where  p  is  incremented  three  times  if  it's  not  a  space,  tab, 
or  new  line. 

Two  other  portability  problems  are  resolved  by  the 
* define  C80  statement — the  use  of  getline  instead  of  fgets 
and  the  need  to  use  %//rather  than  %/in  scanf  calls  when 
using  doubles  instead  of floats. 

Lint  is  unhappy  with  one  part  of  VMM.C.  The  problem 
has  to  do  with  passing  around  pointers  to  functions. 
VMM.C  needs  to  read  a  string  containing  a  function  name, 
look  up  that  function  in  a  table,  and  then  pass  the  address 
of  the  function  back  to  the  calling  program.  So,  we  have 
to  declare  a  function  that  returns  a  pointer  to  a  second 
function  that,  in  turn,  returns  a  double.  The  correct  decla¬ 
ration  syntax  is: 

double  ( *obj(a,b) )( ) 
double  a,  b; 

{ 

} 

The  argument  list  has  to  be  in  the  innermost  set  of  paren¬ 
theses.  Unfortunately,  the  normally  stalwart  C/80 
doesn’t  accept  this  declaration.  There  is  a  convenient, 
though  very  nonportable,  way  to  work  around  it, 
though.  In  fact,  some  compilers  won’t  accept  the  code  as 
given  in  the  listings.  I  assumed  that  an  int  and  pointer  are 
the  same  size  (a  valid  assumption  in  an  8080)  and  then 
wrote  the  code  accordingly.  Listing  Nine  (next  month) 
shows  the  essentials  of  the  VMM  code  as  it  stands.  Listing 
Ten  (next  month)  is  a  short  sample  program  that  shows 
the  changes  you  have  to  make  for  the  program  to  be  cor¬ 
rect. 

It's  obviously  to  your  advantage  to  use  an  8087  if  you 
have  it;  the  calculations  in  the  program  are  floating-point 
intensive. 

As  I  mentioned  earlier,  you'll  have  to  provide  a  model 
of  your  function  as  a  C  subroutine.  I’ve  provided  several 
templates  that  you  can  look  at  to  see  what  this  model 
should  look  like.  You  must  respect  the  number  and  type 
of  all  arguments  to  the  function  call;  even  if  you  don’t  use 
all  of  them,  they  all  must  be  included  for  consistency. 
The  variable  user  (in  mainf  ) )  lets  you  communicate  with 
your  function  from  the  outside;  when  the  minimizer 
calls  your  function,  it  calls  it  with  user  set  to  0. 

You  must  update  the  function  library  routine  (funlibf ) 
in  VMM.C,  Listing  Two,  page  76)  every  time  you  add  a 
function  to  the  system.  You  can  find  detailed  instructions 
for  updating  funlibf  )  in  the  comments  in  the  code.  Brief¬ 
ly  a  few  tables  need  to  be  changed.  The  system  chooses  a 
function  interactively  at  run  time,  and  the  tables  serve  to 
automate  the  function  selection  process.  These  tables  tell 
the  program  what  the  function  is  called  when  input  is 
being  interpreted,  what  name  it  has  in  the  system,  how 
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many  parameters  it  has,  how  many  constants  it  has,  and 
what  names  you  have  chosen  for  the  parameters. 

Adding  a  function  is  easy.  By  grouping  the  main  pro¬ 
gram,  the  function  library  routine,  and  all  the  user  func¬ 
tions  in  VMM.C,  all  the  things  that  you're  likely  to  change 
are  isolated  in  one  module,  so  VMM.C  is  the  only  module 
that  ever  needs  to  be  recompiled.  To  rebuild  the  system, 
edit  VMM.C,  recompile  it  alone,  and  then  link  it  to  the 
remainder  of  the  system.  You  may  want  to  put  the  other 
modules  into  a  library  to  ease  the  linking  process. 

Before  modifying  the  system,  it’s  best  to  get  it  working 
and  play  with  it  for  a  while.  Compile  and  link  all  the 
modules  provided,  and  then  run  the  program  using  the 
sample  data  file  I've  provided  (al.dat,  Listing  Eight,  next 
month).  Unix-style  redirection  can  be  used  to  both  enter 
the  data  and  put  the  results  into  a  file: 

A>VMM  <A1.DAT  >A1.RES 

You  can  interactively  input  the  commands  found  in 
al.dat  too  and  see  the  results  directly  on  your  screen. 

The  Program’s  Output 

Some  of  the  program's  behavior  deserves  comment. 
There  are  several  levels  of  debug  printout,  so  you  can 
have  the  program  glide  through  to  the  result  quickly  and 
silently  or  you  can  see  it  work  in  three  levels  of  detail. 
Silent  operation  is  important  if  the  minimizer  is  embed¬ 
ded  into  another  application.  Sometimes,  however,  it  is 
important  to  see  what  the  program  is  doing.  Debug  level 
1  prints  out  some  summary  results  at  each  iteration.  Lev¬ 
el  2  displays  details  of  how  the  program  is  making  its 
internal  computations  and  decisions.  Level  3  goes  one 
step  further  and  provides  details  of  the  derivative  calcu¬ 
lations. 

You  can  set  the  debug  level  for  each  data  case  as  part 
of  the  data  input  process. 


bfgs 

select  BFGS  method 

constants 

set  constants  in  function 

debug 

set  debug  level 

derivsteps 

set  step  size  for  derivatives 

dfp 

select  dfp  method 

end 

exit  program 

epsilons 

set  stopping  criteria 

exmin 

set  expected  minimum 

funname 

select  function  (req’d  first) 

iterlim 

set  maximum  iteration 

itermin 

set  minimum  iteration 

limitflags 

set  limits  on  parameters 

lowerlimits 

set  lower  limits 

newdata 

read  a  data  file 

next 

do  this  data  set,  then  read  next 

pstart 

set  starting  values  for  parameters 

reset 

set  reset  value  on  update  matrix 

sd 

select  steepest  descent  method 

upperlimits 

set  upper  limits 

Table  1:  VMM  keywords 


Command  Input 

Another  area  of  interest  is  the  command  input  process. 
I've  tried  to  make  the  program  easy  to  use  without  rob¬ 
bing  it  of  its  flexibility  for  advanced  users.  Most  of  the 
important  parameters  can  be  adjusted  on  input,  although 
a  case  can  be  run  with  as  few  as  three  commands:  one  to 
name  the  function  to  use,  one  to  give  the  starting  values 
for  the  parameters,  and  one  to  invoke  the  calculation  for 
that  case.  Multiple  cases  can  be  stacked  in  one  run.  Each 
of  these  cases  is  referred  to  below  as  a  data  set. 

As  you  can  see  from  the  code  (and  from  the  sample  data 
in  Listing  Eight),  input  is  formatted  as  a  keyword  followed 
by  either  zero  or  more  numeric  values  or  strings.  If  the 
first  word  on  the  line  is  not  recognized  as  a  keyword,  the 
entire  line  is  taken  as  a  comment.  This  is  convenient  for 
embedding  comments  in  the  output  listing  as  all  input 
commands  are  echoed,  but  might  cause  trouble  if  you’re 
not  paying  attention  when  entering  data.  Recognized 
keywords  are  shown  in  Table  1,  below. 

The  first  command  in  any  data  set  must  be  funname. 
This  command  should  be  followed  by  the  name  of  the 
function  to  be  looked  up  in  the  library.  (The  table  that 
you  set  up  in  funlibi )  tells  the  program  how  many  pa¬ 
rameters  and  constants  this  function  requires.) 

The  only  other  mandatory  command  is  pstart,  which 
takes  as  arguments  n  floating-point  numbers  correspond¬ 
ing  to  the  starting  values  for  the  n  parameters  expected 
by  the  function  named  in  funname. 

The  minimization  algorithm  can  be  selected  with  one 
of  the  sd,  dfp,  or  bfgs  commands.  These  correspond  to 
steepest  descent,  Davidon-Fletcher-Powell,  or  Broyden- 
Fletcher-Goldfarb-Shanno  methods.  The  dfp  command  is 
used  by  default. 

The  minimum  and  maximum  number  of  iterations  are 
specified  with  the  keywords  itermin  and  iterlim,  each  fol¬ 
lowed  by  a  fixed-point  number.  If  these  commands 
aren’t  used,  defaults  of  n  and  2n  (where  n  is  the  number 
of  parameters)  are  assumed. 

The  reset  command  tells  the  program  to  reset  its  up¬ 
date  matrix  periodically  after  a  specified  number  of  iter¬ 
ations.  If  you  don’t  issue  a  reset  command,  a  default  of 
3n/2  is  used. 

Stopping  criteria  can  also  be  specified.  By  default,  if  the 
estimated  distance  to  the  minimum  becomes  less  than 
l.Oe  — 06  or  the  fractional  change  in  the  minimum  be¬ 
comes  less  than  l.Oe— 03,  the  program  will  stop  (provided 
that  the  minimum  number  of  iterations  has  been  execut¬ 
ed).  You  can  alter  these  limits  with  the  keyword  epsilons 
followed  by  the  limit  on  the  estimated  distance  to  the 
minimum  and  the  limit  on  the  fractional  change  (in  that 
order).  Both  numbers  must  be  entered,  even  if  you  want 
to  change  only  one  of  them. 

One  or  more  parameters  can  be  constrained  to  a  speci¬ 
fied  range  using  the  limitflags,  lowerlimits,  and  upper- 
limits  keywords.  The  three  must  always  be  used  togeth¬ 
er.  Limitflags  is  followed  by  n  integers  set  to  either  0  or  1, 
turning  limit  flags  off  or  on.  If  the  flag  is  set  to  off  (the 
default  if  a  command  is  not  used),  then  there  are  no  con¬ 
straints  on  that  parameter.  The  keywords  lowerlimits 
and  upperlimits  must  be  followed  by  n  floating-point  val¬ 
ues  for  the  lower  and  upper  limits  on  each  parameter; 
the  values  for  those  parameters  with  flags  set  to  0  are 
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ignored.  An  example  of  the  process  is  given  at  the  top  of 
Listing  Eight.  Constraints  on  parameters  are  very  useful 
when,  for  example,  you  know  that  a  certain  parameter 
must  be  positive  (it  might  be  a  physical  dimension).  In  this 
case  you  can  set  its  lower  limit  to  0.0  and  its  upper  limit  to 
some  large  number.  You  can  also  fix  a  parameter  by  set¬ 
ting  its  limit  flag  to  1  and  setting  its  lower  and  upper  limit 
to  its  starting  value  (this  particular  use  of  limits  is  rare  but 
may  prove  useful).  Constraining  parameters  slows  down 
the  system  significantly  as  there  are  several  places  where 
a  trigonometric  transformation  must  be  employed  to 
convert  from  a  bounded  interval  to  an  infinite  one  and 
back  again. 

The  derivsteps  keyword  lets  you  set  the  size  of  the  in¬ 
terval  used  for  computing  the  derivative.  The  default  in¬ 
terval  is  1  percent  on  either  side  of  the  current  value. 

The  keyword  epcmin  adjusts  the  expected  value  of  the 
minimum  (0.0  is  the  default). 

To  allow  you  to  find  best  sets  of  parameters  for  whole 
families  of  functions,  your  function  may  use  several  con¬ 
stants,  set  using  the  keyword  constants  followed  by  m 
floating-point  values  for  the  m  constants  that  your  func¬ 
tion  requires.  Constant  values  are  remembered  from  data 


8  bits  (Osborne  I) 
single  precision 
Z-80,  CP/M  2.2 
51/4-inch  floppy 

Scale  Method  Result  Minimum  Iterations 


Starting  values:  (— 1 .2, 1 .0, . . 

.  -1.2,  1.0) 

100 

sd  - 

-.67140, 

.45982 

14. 

4 

dfp 

-.860, 

.749 

17. 

7 

bfgs 

-.84, 

.71 

17. 

7 

10 

sd 

.889, 

.788 

6.1  E— 2 

20 

dfp 

■99, 

.99 

7.4  E-5 

20 

bfgs 

.98, 

.97 

1.5  E-3 

20 

1 

sd 

.96809, 

.92871 

5.5  E-3 

20 

dfp 

.99982, 

.99964 

1.6  E-7 

10 

bfgs 

.99996, 

.99994 

8.3  E-9 

10 

Starting  values:  (1 .2, 

0.8,  .  .  .  1 

•2,  0.8) 

100 

sd 

.95171, 

.90560 

1.2  E-2 

10 

dfp 

.9825, 

.9651 

1.6  E— 3 

9 

bfgs 

1.0036,1 

.0072 

6.8  E-5 

8 

10 

sd 

.96279, 

.92363 

7.5  E-3 

20 

dfp 

.9986, 

.9971 

1.0  E-5 

7 

bfgs 

.99842, 

.99678 

1.3E-5 

7 

1 

sd 

.99944, 

.99869 

1.7  E-6 

10 

dfp 

.99986, 

.99971 

1.0E-7 

6 

bfgs 

.99983, 

.99963 

1.6  E-7 

6 

Time  (total) 

670 

seconds 

Time  per  run 

37.2 

seconds 

Time  per  iteration 

3.2 

seconds 

Table  2:  8-bit  benchmark 


set  to  data  set  as  a  convenience.  Nevertheless,  if  you 
change  functions  you  must  include  a  new  constants  state¬ 
ment  to  avoid  using  the  old  constants. 

Debug  sets  the  debug  level;  follow  it  by  0, 1,  2,  or  3.  Note 
that  the  debug  diagnostics  start  being  printed  as  soon  as 
this  command  is  issued,  so  putting  it  in  at  the  start  of  a  data 
set  gives  you  debug  diagnostics  as  part  of  the  input  echo. 
Debug  level  0  (no  diagnostics  are  printed)  is  the  default. 

Use  the  newdata  command  to  read  a  file  with  experi¬ 
mental  data.  Follow  the  command  with  the  full  file  name 
for  the  data  (e.g.,  b:e?cp.dat).  The  data  file  is  assumed  to 
have  a  very  specific  format:  The  first  element  is  the  num¬ 
ber  of  lines  to  read  from  the  data  file  (extra  lines  are  ig¬ 
nored).  The  rest  of  the  file  is  data  (in  floating-point  for¬ 
mat).  The  x  value  must  be  entered  first,  then  the  y  value. 
The  data  is  put  into  an  array  of  structures  called  exp  (de¬ 
fined  near  the  top  of  Listing  Two).  If  you  need  something 
different  (such  as  three  numbers  instead  of  two),  you’ll 
have  to  change  the  definition  of  the  DATA  structure  (in 
global. h),  as  well  as  the  associated  input  routines,  and 
then  recompile.  Note  that  the  maximum  number  of  data 
points  is  defined  as  DM  AX  in  the  main  program  and  will 
probably  need  to  be  enlarged.  If  you  want  to  echo  the 
data  as  it's  read,  turn  on  the  debug  before  requesting  new¬ 
data.  The  program  aborts  if  it  can't  open  the  data  file. 

One  caveat  with  newdata :  Data  read  into  the  array  per¬ 
sists  from  one  data  set  to  the  next  (in  the  same  way  as  do 
constants).  It  didn't  make  sense  to  have  to  reread  the  data 
from  disk  for  each  new  case  if  the  same  data  was  being 
used.  Anyway  if  you  want  to  change  data  files  from  one 
case  to  another,  you  must  issue  a  call  to  newdata  with  a 
different  file  name.  Incidentally,  I  used  the  keyword 
newdata  instead  of  something  such  as  datafile  to  empha¬ 
size  that  you  are  in  fact  reading  in  new  data. 

The  neyt  command  starts  up  the  algorithm  (moves  you 
from  a  Data  Input  to  a  Run  mode)  for  the  current  data  set. 
With  the  exceptions  of  data  entered  with  newdata  and 
constants  read  in  with  constants,  each  set  starts  with  a 
clean  slate — there’s  no  carry-over  from  the  previous  data 
set.  If  debug  was  set  to  1  on  the  previous  data  set,  and  you 
still  want  it  to  be  1,  you  must  request  it  again. 

The  keyword  end  causes  the  program  to  terminate. 

If  an  error  is  detected  in  a  data  set,  the  set  is  skipped.  If 
the  reason  for  the  data  error  isn’t  obvious,  the  case  should 
be  run  a  second  time  with  debug  set  to  1  at  the  very  start 
of  the  case.  You  can  always  reset  it  to  0  just  before  issuing 
a  next  command,  thereby  getting  additional  debug  print¬ 
out  just  for  the  input  stage.  Sometimes  the  error  is  caused 
by  a  mistyped  keyword,  which  causes  the  whole  line  to 
be  treated  as  a  comment.  If  debug  is  set  to  0,  there's  no 
indication  that  this  has  occurred.  The  program  always 
tells  you  how  many  commands  and  how  many  comment 
lines  it’s  read,  however,  so  you  have  a  quick  way  of 
checking  for  this  problem  even  if  debug  is  off. 

Benchmarks 

I  ran  two  benchmarks  to  show  the  relative  performance 
of  the  various  algorithms  mentioned  earlier  (see  Tables  2, 
left,  and  3,  page  32).  The  Rosenbrock  function: 

F  =  K  *  (x2  -  x,2)2  +  (1  -  x,)2 
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was  used.  F  is  0  when 


The  correct  result  is  (1.0,  1.0,  .  .  .  1.0,  1.0),  which  would 
be  indicated  below  as  1.0,  1.0.  The  number  of  digits  in  the 
result  shows  how  much  the  answer  varies  from  pair  to 
pair  among  the  five  pairs  of  results.  The  minimum 
should  be  0.0. 


x2  =  X]2  and  x,  =  1 

So,  at  x,  =  1,  x2  =  1,  we  have  a  minimum  for  all  K  >  0. 

The  constant  K  allows  us  to  "scale”  the  two  terms;  for 
K  =  1,  the  two  terms  have  about  the  same  contribution  to 
F  in  the  neighborhood  of  the  minimum.  As  K  becomes 
large,  the  problem  becomes  progressively  more  difficult: 
The  first  term,  which  "drives”  x2  to  be  Xj2,  will  swamp 
the  second  term,  which  drives  Xj  to  1.  For  K  =  100,  we 
would  expect  to  see  x2  approach  Xj2  but 
not  see  x,  go  to  1. 1  have  included  tests  with  K  =  1, 10,  and 
100  on  an  extended  Rosenbrock  function  using  ten  in¬ 
stead  of  two  variables;  that  is,  the  function  is  made  up  of 
ten  terms  consisting  of  five  pairs  of  variables  related  in 
the  same  way.  The  tests  have  been  done  using  a  poor 
starting  point  (  —  1.2,  1.0)  and  a  fairly  good  starting  point 
(1.2,  0.8)  so  you  can  evaluate  the  importance  of  a  good 
starting  value. 

All  tests  were  performed  using  the  same  maximum 
number  of  iterations  (20).  The  inverse  Hessian  approxi¬ 
mation  was  reset  every  five  iterations  in  the  dfp  and  bfgs 
methods.  The  factor  K  is  called  scale  in  the  tables. 


16  bits  (Intel  86/30  System) 

double  precision 
8086/8087,  Xenix 
25  Meg  hard  disk 

Scale  Method 

Result 

Minimum 

Iterations 

Starting  values:  (- 

1.2, 1.0, . . .  -1.2, 1.0) 

100 

sd 

-.67131,  .45970 

14. 

4 

dfp 

-.64703,  .42826 

14. 

7 

bfgs 

-.63495,  .41267 

13. 

7 

10 

sd 

.89008,  .78805 

6.1  E— 2 

20 

dfp 

.9983,  .996 

1.3  E-5 

20 

bfgs 

.999,  .998 

8.1  E— 6 

20 

1 

sd 

.96809,  .92871 

5.5  E-3 

20 

dfp 

.99980,  .99961 

2.0  E-7 

10 

bfgs 

.99980,  .99960 

2.0  E-7 

10 

Starting  values:  (1 .2,  0.8, ...  1 .2,  0.8) 

100 

sd 

.95171,  .90559 

1.2E-2 

10 

dfp 

.981,  .9624 

1.8E-3 

10 

bfgs 

1.0031,1  .0062 

4.8  E-5 

10 

10 

sd 

.96279,  .92363 

7.5  E-3 

20 

dfp 

.99846,  .99668 

1.5  E-5 

5 

bfgs 

.99837,  .99650 

1.6  E  — 5 

5 

1 

sd 

.99943,  .99872 

1.7  E— 6 

10 

dfp 

.99986,  .99970 

9.7  E— 8 

5 

bfgs 

.99982  .99962 

1.6  E-7 

5 

Time  (total) 

81  seconds 

Time  per  run 

4.5  seconds 

Time  per  iteration 

0.4  seconds 

Table  3:  16-bit  benchmark 


The  Listings 

Several  listings  are  provided  with  this  article.  Global. h 
(Listing  One,  page  74)  is  the  global  include  file  mentioned 
earlier.  It  contains  conditional  compilation  switches  for 
the  C/80  compiler  versus  other  C  compilers. 

VMM.C  (Listing  Two)  is  the  main  program,  the  function 
library  module,  and  all  the  functions  in  the  library.  For 
the  time  being,  there  are  three  functions:  cohenl  )  is  the 
test  problem  in  Cohen’s  book  (see  the  reference  in  code), 
sinel  )  finds  coefficients  for  a  polynomial  approximation 
by  fitting  sine  data,  and  rosenf  )  is  used  as  a  benchmark. 
You'll  have  to  compile,  assemble,  and  then  link  this  file  to 
add  a  function  to  the  library.  All  the  other  files  may  be 
kept  in  object  format  and  just  linked  to  VMM.OBJ  (or  .O, 
REL,  or  whatever)  to  generate  a  new  load  module. 

MINIM. C  (Listing  Three,  page  82)  contains  the  main  min- 
imizer  routine. 

AUXL.C  (Listing  Four,  next  month)  contains  the  line 
search  procedure  and  the  decision  logic  for  stopping  the 
minimization. 

UP.C  (Listing  Five,  next  month)  holds  the  routines  re¬ 
quired  for  updating  the  "topology  matrix"  according  to 
the  DFP  or  BFGS  methods. 

UTIL.C  (Listing  Six,  next  month)  contains  a  variety  of 
utility  routines.  Among  these  are  routines  for  transform¬ 
ing  from  external  to  internal  coordinates  when  dealing 
with  constrained  variables,  routines  for  calculating  de¬ 
rivatives,  routines  for  initializing  everything  at  the  begin¬ 
ning  of  a  data  set  and  for  setting  proper  defaults,  vector 
and  matrix  output  routines,  and  routines  for  various  ma¬ 
trix  and  vector  manipulations. 

READ.C  (Listing  Seven,  next  month)  is  the  input  inter¬ 
preter.  There  are  a  few  conditional  compilation  direc¬ 
tives  in  this  module  so  that  scanf  will  handle  floats  and 
doubles  correctly. 

Al.dat  (Listing  Eight)  is  a  sample  input  for  a  test  run, 
including  the  Rosenbrock  benchmark  mentioned  above. 
Al.dat  reads  in  sine.dat  (Table  4,  below),  which  contains 
the  experimental  data  for  the  function  sine(  ). 

Availability 

This  program  is  put  in  the  public  domain  for  personal, 


20 

.050000 

.078459 

.550000 

.760406 

.100000 

.156434 

.600000 

.809017 

.150000 

.233445 

.650000 

.852640 

.200000 

.309017 

.700000 

.891006 

.250000 

.382683 

.750000 

.923879 

.300000 

.453990 

.800000 

.951056 

.350000 

.522499 

.850000 

.972370 

.400000 

.587785 

.900000 

.987688 

.450000 

.649448 

.950000 

.996917 

.500000 

.707107 

1 .000000  1 .000000 

Table  4:  sine.dat 
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nonprofit  use  only.  Permission  is  granted  to  reproduce  it, 
but  I  would  appreciate  your  commenting  any  changes 
you  make.  As  the  publicly  available  source  code  is  obvi¬ 
ously  beyond  my  control,  I  can  assume  no  liability  for 
subsequent  versions. 

This  source  code  is  available  on  several  CP/M  remote 
BBSs,  in  particular  on  the  Mountain  View  RCPM  (415)  965- 
4097  and  the  First  Osborne  Group  (FOG)  RBBS  #\  (415)  755- 
2030.  Both  of  these  systems  provide  free  downloads  to 
members  satisfying  nominal  entry  requirements. 

I  plan  to  keep  a  list  of  registered  users  in  order  to  sup¬ 
port  continuing  development  and  evolution  of  this  sys¬ 
tem.  Registered  users  participate  in  a  common  pool  of 
bugs  and  bug  fixes  as  well  as  potential  future  updates.  To 
become  a  registered  user,  send  a  check  for  $25  to:  Billy- 
bob  Software,  P.O.  Box  363,  Belmont,  CA  94002-0363. 

A  registered  user  can  obtain  the  source  code  on  a  5'4- 
inch  disk  by  sending  a  preformatted  disk  and  sufficient 
return  postage  to  the  above  address.  Be  sure  to  indicate 
what  format  your  disk  is  expecting.  The  most  recent  ver¬ 
sion  will  be  returned.  I  can  handle  many  CP/M  formats  as 
well  as  PC  DOS  and  MS  DOS  formats;  if  you  require  an  un¬ 
usual  format,  send  a  postcard  and  I'll  let  you  know  if  I  can 
accommodate  you. 
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Concurrency 
and  Turbo  Pascal 


After  much  trial  and  error,  I 
have  developed  a  method  to 
use  Turbo  Pascal  (CP/M-80)  to 
implement  several  concurrent  tasks. 
These  techniques  are  useful  for  writ¬ 
ing  software  that  must  respond  to 
several  real-time  events,  such  as  a 
modem  program.  In  this  article,  I 
will  explain  what  concurrency  is, 
what  it  is  useful  for,  and  how  to 
achieve  it.  Turbo  Pascal  provides  a 
convenient  way  to  become  acquaint¬ 
ed  with  multitasking  because  of  the 
ease  of  writing  and  trying  variations 
quickly  and  clearly. 

Subroutines  vs.  Coroutines 

A  subroutine  or  function  call  is  fre¬ 
quently  used  in  programming  to  car¬ 
ry  out  a  "subtask"  that  a  main  task 
needs  in  order  to  continue.  Economy 
of  coding  occurs  when  this  same  sub¬ 
task  is  needed  in  several  different 
places.  The  subtask  is  subservient  to 
the  main  task  in  that  its  existence  de¬ 
pends  upon  being  called  upon  by  the 
main  task. 

A  pair  of  coroutines  should  appear 
to  proceed  in  random  order,  namely 
the  starting  or  completion  of  either 
routine  is  not  in  complete  lockstep 
with  the  other  routine.  Doing  several 
things  at  the  same  time  is  often  called 
multitasking;  it  is  an  important  fea¬ 
ture  of  the  languages  Modula  and 
Ada. 

An  example  of  a  possible  use  of 
coroutines  is  the  implementation  of  a 
terminal  program  on  a  personal 
computer.  In  this  case,  one  task  has 
the  responsibility  of  monitoring  the 
keyboard.  Every  time  a  key  is 
pressed,  the  corresponding  charac¬ 
ter  is  sent  out  of  the  serial  port.  The 
other  task  monitors  the  serial  port 
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An  appropriate  use  of 
coroutines  is  in  mon¬ 
itoring  the  keyboard 
and  the  serial  port 
under  a  terminal 
program. 


for  incoming  characters,  and  when 
one  arrives,  it  is  sent  to  the  display. 
These  two  tasks  are  more  or  less  in¬ 
dependent  as  they  do  not  need  to 
share  any  function. 

An  important  characteristic  of  the 
operation  of  such  a  program  is  that 
you  do  not  assume  that  the  arrival  of 
characters  at  the  serial  port  is  closely 
related  to  tapping  the  keyboard.  Fail¬ 
ure  of  characters  to  arrive  from  ei¬ 
ther  source  should  not  interfere  with 
the  operation  of  the  other  task. 

A  skeleton  of  the  program  should 
be: 

taskl; 

begin 

repeat 

serout(keyin); 
until  false(forever); 
end; 
task2; 
begin 
repeat 

videout(serin); 
until  false{forever}; 
end; 

Each  of  the  tasks  resembles  the 
main  procedure  of  a  Pascal  program. 
As  is  good  form  in  structured  pro¬ 
gramming,  all  the  tough  work  gets 
put  off  to  be  written  in  the  subrou¬ 


tines  and  functions  (particularly  se¬ 
rin  and  keyin).  Before  I  discuss  the 
subroutines  in  detail,  note  that,  for 
the  tasks  to  run  independently  of 
each  other,  they  need  to  have  sepa¬ 
rate  stack  spaces.  The  stack  is  used  to 
save  return  addresses  (among  other 
things)  when  subroutines  and  func¬ 
tions  are  called.  If  both  tasks  shared  a 
common  stack,  there  would  be  an 
undesirable  tendency  for  return  ad¬ 
dresses  (and  possibly  data)  to  get  con¬ 
fused  between  the  two  tasks.  Thus, 
each  task  should  be  assigned  its  own 
stack. 

In  Listing  One,  page  88,  you  can  see 
that  taskl  and  task2  indeed  start  by 
assigning  their  own  stack  spaces.  Al¬ 
though  mystack  is  declared  as  a  vari¬ 
able  in  both  taskl  and  task2,  the  tasks 
are  assigned  separate  memory  loca¬ 
tions  by  the  Turbo  Pascal  compiler. 
The  compiler  assigns  different  loca¬ 
tions  for  every  variable  of  the  main 
program  and  for  every  parameter, 
return  value,  and  variable  of  every 
function  and  procedure. 

The  two  functions  keyin  and  serin 
are  characterized  by  taking  an  un- 
predictably  long  time  to  complete 
their  tasks — for  example,  keyin  could 
take  hours  if  the  keyboard  operator 
fell  asleep  (and  meanwhile  other 
things  might  be  happening).  These 
two  functions  consist  of  a  loop  where 
the  function  (tediously)  asks  whether 
a  character  is  available.  It  is  in  these 
loops  that  most  of  the  time  is  wasted; 
as  soon  as  a  character  becomes  avail¬ 
able,  the  function  can  return  its 
value. 

The  crux  of  accomplishing  concur¬ 
rency  is  to  share  the  processing 
power  between  tasks.  This  sharing  is 
accomplished  by  the  calls  to  defer 
done  by  keyin  and  serin.  Defer  is  treat¬ 
ed  as  a  procedure,  but  it  succeeds  in 
switching  the  processor  from  one 
task  to  another  (hence  the  choice  of 
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name).  It  should  be  invoked  wherev¬ 
er  a  procedure  might  not  proceed 
quickly.  Defer  should  also  be  invoked 
from  time  to  time  if  rapid  response  to 
external  events  (such  as  key  presses)  is 
needed  and  a  procedure  or  function 
is  doing  extensive  calculations. 

I  found  it  convenient  to  treat  the 
main  portion  of  the  program  as 
taskO;  it  is  special  in  that  it  is  given- 
initial  control  when  the  program 
starts.  It  must  initialize  variables  for 
defer  to  operate;  other  initializations 
can  be  done  here  as  well,  such  as 
sending  commands  to  hardware  to 
configure  baud  rates  and  so  on.  In  ad¬ 
dition,  the  way  the  program  should 
terminate  is  through  the  main  proce¬ 
dure;  the  Pascal  compiler  does  not 
empower  the  subroutines  to  termi¬ 
nate  the  program  in  a  normal  man¬ 
ner.  To  help  in  start-up  and  termina¬ 
tion,  two  procedures,  initall  and  ey/t, 
are  provided. 

The  coding  of  defer  was  arrived  at 
after  some  experimentation.  I  found, 
for  example,  that  assigning  an  array 
element  with  the  hardware  stack 
pointer  ( stackptr )  results  in  a  differ¬ 
ent  value  than  assigning  a  simple 
variable  with  stackptr.  The  reason  is 
that  the  compilation  generates  code 
that  pushes  an  address  pointer  for 
the  element  on  the  stack  and  so  af¬ 
fects  the  value  of  the  stack  pointer  at 
that  moment. 

When  defer  is  called,  the  return 
address  in  the  calling  task  is  on  the 
(current)  stack.  When  defer  switches 
stack  pointers  (thus  switching  to  the 
stack  of  another  task),  it  will  return  to 
the  point  in  the  new  task  where  de¬ 
fer  had  been  called. 

A  task  is  entered  at  two  places:  at 
the  start  and  reentry  (from  where  it 
had  been  deferred).  It  is  necessary 
for  defer  to  know  which  (re-)entry  to 
use.  This  is  accomplished  with  a  test 
of  the  saved  stack  pointer.  If  the 
saved  value  is  zero,  then  it  can  as¬ 
sume  the  task  has  never  been  en¬ 
tered  and  it  should  start  at  the  begin¬ 
ning.  When  a  task  is  started,  it  should 
immediately  initialize  the  stack 
pointer  to  its  own  stack  space. 

In  the  interests  of  clarity  and  easy 
modification,  the  scheduling  aspect 
of  defer  has  been  broken  off  into  a 
separate  procedure.  The  functioning 
of  schedule  here  is  almost  trivial;  it  is 
apparent  that  for  special  applica¬ 
tions  with  more  tasks,  you  might 


wish  to  try  other  scheduling  algo¬ 
rithms  than  round  robin. 

The  beauty  of  using  the  proce¬ 
dures  initall,  defer,  schedule,  ejcit,  and 
the  like  is  that  they  may  be  used  as 
black  boxes — the  details  of  how  they 
work  can  be  ignored  in  their  use. 
Once  I  had  written  them,  I  concen¬ 
trated  my  efforts  on  coding  each  in¬ 
dividual  task. 

Reentrancy 

Emboldened  by  my  success  with  us¬ 
ing  Turbo  Pascal  to  implement  multi¬ 
ple,  independent  tasks,  I  went  on  to 
try  multitasking  with  procedures 
that  are  shared  among  several  tasks. 
My  first  attempts  failed  miserably 
and  I  learned  the  hard  way  that  pro¬ 
cedures  and  functions  in  Turbo  Pas¬ 
cal  are  not  reentrant  even  if  they 
may  be  recursive. 

A  requirement  of  Pascal  is  recur¬ 
sion,  which  is  supported  by  Turbo 
Pascal  (using  the  {$A— }  option).  Re¬ 
cursion  is  where  procedures  or  func¬ 
tions  call  themselves  directly  or  indi¬ 
rectly  (by  calling  other  procedures  or 
functions  that  call  them).  An  exam¬ 
ple  of  recursion  would  be  the  imple¬ 
mentation  of  autoCR.  AutoCR  pre¬ 
cedes  a  line  feed  with  a  carriage 
return: 

procedure  putc(c:  char); 

begin 

if  c=LF  then  putc(CR); 

end; 

You  cannot  assume  that  all  lan¬ 
guages  support  recursion — for  exam¬ 
ple,  FORTRAN  does  not.  To  support  re¬ 
cursion  it  is  necessary  that  each 
invocation  of  a  procedure  has  its 
own  distinct  variable  space.  If  the 
space  is  not  unique  (if  recursion  is  not 
supported),  then  in  the  above  exam¬ 
ple  the  value  of  c  would  be  changed 
by  the  second  invocation  of  putc  to  a 
CR  and  in  all  likelihood,  the  LF  (the 
original  invocation)  would  not  be 
printed  but  replaced  by  a  Cfl;  two 
Cfis  would  be  produced  instead  of 
the  desired  CR-LF  sequence. 

Although  Turbo  Pascal  supports 
recursion  when  you  use  the  {$A  — } 
option,  it  does  not  support  reen¬ 
trancy.  For  a  procedure  to  be  reen¬ 
trant,  it  must  be  possible  to  defer  in 
the  middle  of  an  invocation,  switch 


to  another  task,  and  for  that  other 
task  to  reenter  the  same  procedure 
without  affecting  the  subsequent  op¬ 
eration  of  the  first  invocation  of  that 
procedure.  It  was  assumed  in  the  de¬ 
velopment  of  Turbo  Pascal,  I  pre¬ 
sume,  that  it  would  not  be  used  in  a 
multitasking  environment. 

The  most  straightforward  way 
around  this  difficulty  is  not  to  re¬ 
quire  reentrancy.  Any  procedure  or 
function  that  might  be  deferred  di¬ 
rectly  or  indirectly  and  that  is  called 
by  more  than  one  task  should  be  du¬ 
plicated  as  many  times  as  is  neces¬ 
sary  so  that  each  copy  is  used  by  only 
one  task.  Listing  Two,  page  90,  is  an 
example  of  this  approach. 

Listing  Two  is  a  program  I  devel-  j 
oped  to  demonstrate  the  use  of  j 
queues  to  enable  tasks  to  operate 
more  independently  of  each  other. 
In  operation,  it  displays  the  charac¬ 
ters  typed  at  the  keyboard  on  the 
screen.  What  is  noteworthy  about 
this  program  is  that  it  is  quite  easy  for 
the  typist  to  type  faster  than  the  dis¬ 
play  rate  and,  thus,  to  "type  ahead.”  : 
The  display  continues  to  show  more 
and  more  characters  even  after  the 
typist  has  paused;  no  characters  have 
been  "lost”  by  the  slowness  of  the  ! 
display  relative  to  the  keyboard. 

To  make  things  more  interesting,  I 
provided  the  XON/XOFF  protocol  to 
make  the  display  stop  altogether  on 
demand  and  to  resume  on  demand 
later.  If  you  were  to  type  a  Ctrl-S  then 
the  display  would  not  show  any  ac¬ 
tivity  even  though  you  might  be  typ¬ 
ing  another  sentence  or  two.  When 
you  eventually  type  a  Ctrl-Q,  the  dis¬ 
play  will  reactivate  and  show  what¬ 
ever  was  held  back. 

As  a  touch  of  friendliness,  you  can 
correct  your  typing  by  typing  a  back¬ 
space  to  undo  the  last  character  ] 
typed.  An  additional  convenience  is 
that  the  program  provides  line  feeds 
after  any  carriage  return  you  type  to 
put  you  on  the  next  line  without  i 
your  having  to  remember  to  type  the 
line  feed  as  well.  Should  you  type  a  ; 
line  feed,  it  will  be  discarded. 

Listing  Two  consists  of  three  tasks. 
The  first  task  ( keyboard )  gathers  | 
whatever  is  typed  and  quickly  stores  j 
it  away  so  that  it  can  be  digested  at 
leisure  without  missing  any  key-  | 
strokes.  The  method  of  storage  is  j 
known  as  a  queue,  reminiscent  of 
people  standing  in  a  line  in  which  j 
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!  the  first  person  in  line  is  the  first  to 
get  service.  Another  expression  for 
j  the  same  technique  is  FIFO  (first  in, 

^  first  out).  No  one  seems  to  use  the  ac¬ 
ronym  LILO  (last  in,  last  out),  al¬ 
though  it  probably  would  be  under¬ 
stood  equally  well  .  In  any  case,  the 
first  task  places  all  characters  re¬ 
ceived  into  the  first  queue  by  calling 
!  the  procedure  enqueuel. 

The  second  task  is  called  the  filter. 

\  Its  function  is  to  take  each  character 
that  it  obtains  from  the  queue  of 
characters  received  by  taskl  and  ei¬ 
ther  pass  them  along  or  carry  out 
particular  actions.  If  a  carriage  re¬ 
turn  is  encountered,  you  want  a  line 
feed  to  follow  it.  If  a  line  feed  is 
typed,  it  is  to  be  dropped.  Ctrl-S  and 
Ctrl-Q  characters  are  not  passed 
|  along  but  are  used  to  stop  and  start 
I  the  output,  respectively.  A  Ctrl-C 
causes  the  program  to  quit.  Most 
characters  are  passed  along. 

The  output  of  the  filter  does  not  go 
directly  to  the  output  device  but  is 
placed  in  a  second  queue  awaiting  a 
I  chance  to  go  to  the  display  whenever 
|  the  display  is  ready  to  take  this  out- 
j  put.  Thus  the  filter  produces  output 
I  by  calling  the  function  enqueueZ. 

The  third  task,  printer,  takes  char¬ 
acters  from  the  second  queue  by  call¬ 
ing  dequeueZ.  DequeueZ  either  re¬ 
turns  with  a  character  right  away  or 
may  take  its  time  (deferring  to  other 
j  tasks).  Delays  in  returning  a  charac- 
!  ter  mean  that  there  are  no  characters 
(and  you  need  to  wait  for  the  filter  to 
supply  some  more)  or  that  the  queue 
is  in  a  "noflow”  state.  Because  the 
video  display  is  normally  very  fast,  I 
chose,  for  purposes  of  illustration,  to 
slow  the  printer  task  artificially  by 
j  requiring  it  to  count  up  to  PRATE  be- 
j  fore  sending  each  character. 

Notice  that  the  functions  occupan- 
!  cy(p)  and  vacancy (p)  are  each  used 
by  more  than  one  task.  Taskl  uses  va¬ 
cancy  (through  enqueuel ).  TaskZ  uses 
occupancy  (through  dequeuel )  and 
vacancy  (through  enqueueZ ).  Task3 
uses  occupancy  (through  dequeueZ ). 

I  The  functions  occupancy  and  vacan¬ 
cy  can  be  'shared”  between  several  ! 
tasks  because  they  never  defer. 

On  the  other  hand,  I  have  learned 
the  hard  way  not  to  try  to  share  en- 
queue(p)  and  dequeue(p)  because  j 
these  functions  would  defer,  and  | 
they  need  to  be  reentrant.  Thus  I  j 
have  separate  but  equal  procedures:  | 


enqueuel  and  enqueueZ.  Also,  I  have 
the  separate  functions  dequeuel  and 
dequeueZ. 

Conclusion 

It  is  relatively  easy  to  create  a  multi¬ 
tasking  program  with  Turbo  Pascal 
in  CP/M-80  using  the  method  I  have 
shown  here.  You  have  to  be  careful, 
though,  that  functions  or  procedures 
that  need  to  be  reentrant  are  re¬ 
placed  by  several  copies  to  avoid  that 
need. 

DDJ 

(Listing  begins  on  page  88.) 
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ARTICLES 


The  Problems 
Parallelism 


Life  has  a  grammar  with  four 
terminal  symbols.  G,  T,  A,  and 
C  (guanine  et  all  are  four 
chemical  bases  that  combine  to  form 
the  two-stranded,  helical  molecules 
of  DNA,  the  grammar  behind  all  life 
on  Earth.  In  pairs,  the  bases  form  se¬ 
quences  up  to  hundreds  of  thou¬ 
sands  of  base  pairs  long  that  define 
the  genetic  makeup  of  an  organism. 
Several  thousand  such  functional  se¬ 
quences  of  base  pairs  have  been 
identified,  but  they  represent  only  a 
small  fraction  of  the  possible  se¬ 
quences.  Having  learned  that  struc¬ 
tural  similarity  is  the  first  clue  to 
functional  similarity  molecular  biol¬ 
ogists  such  as  J.  Douglas  Welsh  at 
Princeton  University  begin  the  pro¬ 
cess  of  identifying  the  function  of 
each  new  sequence  by  comparing, 
base  pair  by  base  pair,  the  new  se¬ 
quence  with  existing  sequences.  Un¬ 
raveling  the  thread  of  life  is  a  prob¬ 
lem  in  pattern  matching. 

Many  good  algorithms  for  pattern 
matching  are  known,  but  good  algo¬ 
rithms  are  not  always  good  enough. 
Welsh  found  that  the  problem  was 
using  more  computer  time  than  he 
could  afford,  and  he  worried  that  the 
pruning  heuristics  he  employed  to 
focus  only  on  "relevant"  sequences 
would  cause  him  to  overlook  impor¬ 
tant  functional  sequences.  He  want¬ 
ed  to  search  both  exhaustively  and 
efficiently.  Existing  algorithms  and 
architectures  seemed  to  prevent  him 
from  doing  so. 

Those  who  read  the  discussion  of 
the  Fgrep  algorithm  in  DDJ  (Septem¬ 
ber  1985)  will  recall  how  algorithms 
that  do  pattern  matching  in  parallel 
can  sometimes  outpace  their  sequen¬ 
tial  counterparts.  Princeton  graduate 
student  Daniel  Lopresti,  enlisted  to 
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solve  Welsh’s  problem,  followed  a 
similar  insight  and  found  a  parallel  al¬ 
gorithm  that  he  estimates  can  pro¬ 
duce  a  thousandfold  increase  in  pro¬ 
cessing  speed  over  the  algorithm 
Welsh  had  been  using.  Lopresti  has 
implemented  his  algorithm  in  a  mul¬ 
tiprocessor  chip  that  represents  an 
advance  in  the  technology  for  molec¬ 
ular  biology  and  could  also  find  appli¬ 
cations  in  many  other  disciplines  in 
which  string  comparisons  are 
important. 

Lopresti 's  example  shows  that  re¬ 
placing  traditional  sequential  algo¬ 
rithms  with  parallel  algorithms  can 
produce  significant  increases  in 
throughput  and  efficiency.  In  fact, 
problems  that  have  been  shown  to 
be  NP-complete  and  to  require  expo¬ 
nential  time  to  solve  by  sequential 
methods  can  often  be  solved  in  poly¬ 
nomial  time,  and  sometimes  in  linear 
time,  using  parallel  techniques.  The 
development  of  appropriate  parallel 
algorithms  for  fundamental  prob¬ 
lems  such  as  searching,  sorting,  pat¬ 
tern  matching,  matrix  operations, 
fast  Fourier  transforms,  and  so  on  is 
by  no  means  a  simple  matter,  how¬ 
ever.  Like  Lopresti,  the  designer  of  a 
successful  parallel  solution  to  a  pro¬ 
gramming  problem  today  is  likely  to 


be  programmer  and  microprocessor 
designer  in  one  body  because  imple¬ 
menting  a  parallel  solution  tends  to 
involve  the  entire  computational 
model,  and  the  parallel  algorithm 
can  rarely  be  viably  grafted  onto  an 
existing  sequential  Von  Neumann 
architecture. 

Concurrency 

There  are,  of  course,  many  examples 
of  concurrent  processing  in  other¬ 
wise  sequential  architectures.  Con¬ 
currency  at  the  level  of  the  operating 
system  in  the  case  of  Concurrent  DOS 
or  at  the  "operating  environment”  in 
the  cases  of  TopView  and  DESQview, 
for  example,  allows  entire  applica¬ 
tions  to  run  in  what  is,  at  that  level, 
parallel  fashion.  At  a  deeper  level,  the 
machine  is  executing  instructions  in 
strictly  sequential  fashion.  Taking  it  a 
step  higher,  one  can  implement  con¬ 
current  processes  within  an  applica¬ 
tion  program;  IBM  claims  that  Top- 
View  will  support  concurrency 
within  the  programs  that  it  is  running 
concurrently.  Another  article  in  this 
issue  examines  the  techniques  for  im¬ 
plementing  concurrent  processes. 
(See  "Concurrency  and  Turbo  Pascal” 
by  Ernest  Bergmann.) 

There  are  also  examples  of  deeper 
concurrency  that  still  don’t  force  any 
serious  rethinking  of  fundamental 
algorithms  or  of  the  architecture  of 
the  machine.  Print  spooling  and  the 
use  of  dedicated  math  coprocessors 
both  split  off  easily  segregated  opera¬ 
tions  and  hand  them  off,  freeing  the 
CPU  for  other  operations.  A  more 
complex  separation  of  functions  was 
presented  by  James  Vaughan  and 
Robert  Smith  of  Tantivy  Associates  of 
Palo  Alto,  California,  at  the  Wescon 
show  last  November.  Their  machine 
implements  a  structured  sequencer 
that  operates  in  parallel  with  arith¬ 
metic  operations.  The  sequencer  just 
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traverses  a  tree;  it  supplies  the  calling 
and  branching  operations  of  tradi¬ 
tional  sequential  programming.  The 
computational  component  is  a  co¬ 
processor  that  performs  all  the  tradi¬ 
tional  arithmetic  operations,  passing 
single-bit  messages  to  the  sequencer 
and  picking  up  its  instructions  and 
data  from  it.  But  the  resultant  con¬ 
currency  between  sequencer  and 
processor  is,  as  Vaughan  himself 
points  out,  similar  to  the  kind  of  con¬ 
currency  that  exists  between  a  main 
processor  and  a  math  coprocessor  in 
a  personal  computer. 

Parallel  Processing 

True  parallel  processing  involves 
both  a  rethinking  of  system  architec¬ 
ture  and  a  fundamental  recasting  of 
algorithms.  It  exists.  There  are  paral¬ 
lel-processing  computers  in  exis¬ 
tence  today  and  more  are  on  the 
way.  Full  use  of  those  computers — 
exploitation  of  parallel  processing  at 
the  level  at  which  we  have  exploited 
sequential  processing  today — repre¬ 
sents  a  large  step  forward,  but  it’s  not 
here  yet.  It’s  a  level  50  problem  in  the 
notation  of  Knuth's  Fundamental  Al¬ 
gorithms.  General-purpose  parallel¬ 
ism  in  machine  architecture  and  al¬ 
gorithm  design  may  well  require 
cooperation  on  the  level  of  the  ef¬ 
forts  that  produced  the  sequential 
machines  of  the  1940s.  That  coopera¬ 
tion  is  not  always  present. 

A  year  ago,  Peter  C.  Patton  was 
growing  frustrated  directing  efforts 
at  the  Microelectronics  and  Comput¬ 
er  Technologies  Corp.  (MCC)  in  Aus¬ 
tin,  Texas,  to  solve  the  problem  of  de¬ 
composing  tasks  into  components 
appropriate  for  parallel  execution. 
After  resigning  his  post  with  MCC,  he 
expressed  his  frustration  with  the  or¬ 
ganization’s  lack  of  focus  in  The  Wall 
Street  Journal:  “Most  people  think 
parallel  processing  is  the  future,  but 
nobody  can  agree  on  how  to  get 
there,"  he  said. 

One  organization  trying  to  provide 
some  focus  is  the  Parallel  Processing 
Research  Council,  a  group  that  grew 
out  of  a  1983  NSF  workshop  on 
parallel-computing  research.  Accord¬ 
ing  to  IEEE  Computer  (December  1985), 
the  group  plans  to  promote  collabora¬ 
tive  efforts  in  parallel-processing  re¬ 
search  among  government,  industry 
and  university  researchers  by  pro¬ 
ducing  a  newsletter,  distributing  in¬ 


formation  about  nonproprietary  re¬ 
search  and  projects  in  parallel 
hardware  and  software,  and  starting 
two  research  facilities.  A  report  is¬ 
sued  by  the  council  attributes  any 
lack  of  progress  in  the  area  to  lack  of 
facilities  and  significant  collaborative 
effort,  deficiencies  the  group  hopes  to 
remedy. 

One  of  the  differences  among  ap¬ 
proaches  to  parallelism  is  the  archi¬ 
tecture  vs.  algorithm  distinction.  It 
stems  from  the  necessity  of  finding  a 
good  match  between  algorithm  and 
architecture  and  the  question  of  just 
how  to  achieve  the  match.  Does  one 
start  with  the  architecture  and  tailor 
the  algorithms  to  it  or  develop  effi¬ 
cient  parallel  algorithms  and  create 
architectures  to  support  them? 

Communication 

As  in  the  1940s  with  the  development 
of  the  sequential  computer  and  its  as¬ 
sociated  algorithms,  algorithms  and 
architecture  for  parallel  processing 
may  have  to  be  developed  hand  in 
hand,  requiring  close  communica¬ 
tion  among  researchers. 

The  Computer  Measurement  Re¬ 
search  Facility  of  the  National  Bu¬ 
reau  of  Standards  is  collecting  paral¬ 
lel  benchmark  programs.  The  plan  is 
to  develop  a  public  repository  of  in¬ 
formation  about  parallel-computer 
performance;  the  Bureau  wants  pro¬ 
grams,  written  in  high-level  lan¬ 
guages,  that  measure  some  aspect  of 
parallel-processing  performance.  Di¬ 
rect  inquiries  to: 

Computer  Measurement  Research 

Facility 

Institute  for  Computer  Sciences  and 

Technology 

Materials  Building  MS  B364 
National  Bureau  of  Standards 
Gaithersburg,  MD  20899 
(301)  921-3274. 

Those  interested  in  joining  the  Par¬ 
allel  Processing  Research  Council 
should  contact: 

George  Almasi,  PPRC  Chair 
IBM  T.  J.  Watson  Research  Center 
P.O.  Box  218 

Yorktown  Heights,  NY  10598 
(914)  945-1305 
ALMASI.  YKTVMX@IBM 

DDJ 
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Speeding  MS  DOS 
Execution 


I  was  intrigued  to  read  in  Dr. 
Dobb  s  Clinic  ( DDJ ,  September 
1985)  that  he  thought  "the  DOS 
BIOS  doesn’t  use  the  ROM  BIOS  for  its 
disk  input,  and  DOS's  BIOS  does  it  bet¬ 
ter."  Because  I  know  that  this  is  not  so 
(DOS  does  use  the  ROM  BIOS),  I  thought 
I  would  experiment  and  discover 
more  of  the  story  and  the  answer  to 
the  riddles  presented  in  the  column. 

DOS  definitely  uses  the  ROM  BIOS  to 
handle  disk  I/O.  This  can  be  verified 
by  examination  of  the  DOS  BIOS  code 
as  it  resides  in  memory  or  by  loading 
the  DOS  BIOS  file  (IBMBIO.COM  for  PC 
DOS  or  IO.SYS  for  MS  DOS)  into  DEBUG 
and  unassembling  it.  Look  for  the  INT 
13  instructions:  There  is  the  disk  I/O 
handling.  You  will  not  see  any  of  the 
lowest  level  DMA  and  disk-controller 
handling  procedures  that  you  find  in 
the  ROM  BIOS.  It  would  be  against 
IBM's  and  Microsoft's  software  design 
principles  to  include  such  low  level 
machine  dependencies  in  the  DOS 
BIOS. 

I  used  E-X-E  Software’s  D0S200LS 
System  Utilities  package  to  perform 
timing  tests  to  verify  the  benchmarks 
published  in  the  column.  This  pack¬ 
age  contains  a  program  to  trap  DOS 
functions  and  time  them  and  anoth¬ 
er  program  to  produce  listings  of  the 
results.  Five  listings  are  included 
with  this  article,  showing  the  results 
I  obtained  in  performing  some  of  the 
tests  mentioned  in  the  column. 

I  was  able  to  verify  most  of  the  test 
results,  obtaining  very  similar  times 
even  though  the  tests  were  per¬ 
formed  on  an  IBM  PC/AT  and  not  an 
XT.  Because  the  limiting  factor  in  I/O 
would  be  the  disk's  physical  charac- 


Gregg  Weissman,  E-X-E  Software  Sys¬ 
tems,  205  E.  78th  St.,  New  York,  NY 
10021 


by  Gregg  Weissman 


When  writing  your 
own  BIOS  disk  han¬ 
dlers  using  interrupt 
13h ,  set  the  head  set¬ 
tle  time  to  Ofor  all 
read  operations. 


teristics  and  not  CPU  speed,  the  tim¬ 
ings  would  be  expected  to  be  similar. 

The  DOS  COPY  command  in  my  test 
(Listing  Four,  page  101)  ran  in  9.7  sec¬ 
onds,  compared  to  9.8  seconds  in  Cor- 
tesi's:  close  enough  to  consider  the 
results  identical.  My  interpreted  BA- 
SICA  test  (Listing  Five,  page  101)  ran  in 
44.2  seconds  of  DOS  time  and  66  sec¬ 
onds  total.  Cortesi  includes  no  figure 
for  the  time  spent  by  DOS  on  the  disk 
functions  only. 

In  the  tests  that  called  DOS  from  as¬ 
sembly  language,  Cortesi  claims  that 
"block  sizes  beyond  9K,  one  cylinder, 
don’t  give  further  improvement.” 
This  is  not  what  I  found:  In  my  tests 
(Listings  Six,  Seven,  and  Eight,  pages 
102  —  104),  a  block  size  of  9K,  or  2400h, 
gave  a  result  of  9.7  seconds,  while 
block  sizes  of  COOOh  through  FEOOh 
(49,152  to  65,024  bytes)  gave  substan¬ 
tially  lower  times,  leveling  off  at 
COOOh  at  7.09  to  7.14  seconds  (plus  or 
minus  one  clock  tick). 

It  could  be  that  the  block  size  at 
which  performance  levels  off  is  a 
function  of  the  disk  hardware  be¬ 
cause  I  obtained  the  same  results  with 
both  PC  DOS  Versions  2.1  and  3.1  and 
could  verify  that  the  BIOS  calling  se¬ 
quences  were  essentially  the  same. 
There  is  no  other  way  to  account  for 
Cortesi ’s  finding  that  performance 


did  not  improve  past  the  9K  block 
size. 

The  Answer  to  a  Puxxle 

The  reason  Cortesi  states  that  the  DOS 
BIOS  does  not  use  the  ROM  BIOS  for 
disk  I/O,  however,  is  based  on  the 
findings  of  an  (unlisted)  assembler 
program  that  reads  the  disk  directly 
through  the  BIOS  interrupt  13h.  Be¬ 
cause  this  program  was  slower  than 
the  fastest  DOS  time,  he  assumed  that 
DOS  does  not  use  ROM.  I  knew  there 
had  to  be  another  answer. 

I  tried  my  own  assembler  routine 
to  read  the  requisite  number  of  sec¬ 
tors  directly,  also  using  the  ROM  in¬ 
terrupt  13h.  This  appears  in  Listing 
One,  page  94.  There  are  only  a  hand¬ 
ful  of  logical  ways  to  do  this,  so  I  sus¬ 
pect  my  program  is  very  similar  to 
Cortesi’s.  My  program  also  ran  slow¬ 
er  than  DOS,  timing  out  at  11.42  sec¬ 
onds.  Because  I  knew  DOS  had  to  be 
using  BIOS,  I  coded  a  short  resident 
module  to  trap  the  BIOS  interrupt  13h 
so  I  could  see  what  DOS  was  doing  as 
it  happened. 

What  I  found  is  that  DOS  modifies 
the  head  settle  time  parameter  in  the 
table  of  disk  variables  that  BIOS  uses  to 
control  the  NEC  disk  controller.  The 
head  settling  delay  is  a  simple  do- 
nothing  loop  in  the  ROM  BIOS,  giving 
the  read/write  head  and  arm  time  to 
settle  into  position  after  a  seek  opera¬ 
tion  is  performed,  before  the  control¬ 
ler  attempts  to  read  or  write  any  data. 
Each  time  the  disk  has  to  move  from 
one  cylinder  to  another,  this  head  set¬ 
tle  delay  will  be  taken. 

The  absolute  memory  location 
0000:0078h  contains  a  pointer  to  a  ta¬ 
ble  of  values  that  users  can  modify  in 
order  to  accommodate  different  disk 
characteristics.  One  of  the  parame¬ 
ters  is  the  head  settle  delay. 

The  default  head  settle  time  on  the 
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AT  is  15  milliseconds  when  the  sys¬ 
tem  is  initialized  by  BIOS,  and  PC  DOS 
3.1  resets  this  to  1  millisecond.  On  the 
XT,  it  defaults  to  25  milliseconds;  PC 
DOS  2.1  knocks  this  down  to  15  milli¬ 
seconds.  These  head  settle  times  are 
required  when  writing  disk  data,  but 
not  when  reading,  as  I  discovered. 

When  DOS  reads  from  the  disk,  it 
sets  the  head  settle  time  in  the  disk 
parameter  block  to  0.  When  the  op¬ 
eration  is  complete,  DOS  restores  the 
original  value.  Therefore,  when  Cor- 
tesi  (and  I)  ran  our  assembler  BIOS 
tests,  the  head  settle  time  was  set  to 
the  original  default — in  my  case  1 
millisecond,  and  in  his,  possibly  up  to 
15  milliseconds. 

Two  JVcw  Puzzles 

If  I  changed  the  settle  time  parame¬ 
ter  to  0,  as  does  DOS,  my  assembler 
timing  went  from  11.42  seconds 
down  to  7.9 — but  this  presented  two 
puzzling  problems. 

The  first  problem  was  easy:  The 
new  lower  times  were  still  greater 
than  the  DOS  timings — the  DOS  tests 
consistently  showed  times  of  7.09  to 
7.14  seconds,  and  those  times  includ¬ 
ed  all  the  operating  system  overhead. 
With  a  little  thought  I  realized  that 
the  motor  start-up  time  must  be  con¬ 
sidered.  The  motor  starts  when  DOS 
executes  an  OPEN  function,  which  I 
was  not  counting  in  my  comparisons. 

When  I  started  the  disk  motor  be-1 
fore  beginning  the  timing,  the  time 
required  for  the  BIOS  to  read  16  cylin¬ 
ders  went  down  to  6.8  seconds,  the 
time  Cortesi  reports  for  the  DOS  I  NT  25 
function  as  the  fastest  possible  (which 
is  true).  If  you  refer  to  the  DOS  timing 
figures,  the  OPEN  calls  all  took  about  2 
seconds  (plus  or  minus  1  clock  tick),  so 
everything  fits  neatly  together. 

Pay  close  attention  to  Cortesi's 
phrase  “DOS  sequential  input  can 
reach  and  sustain  an  input  rate  of  one 
track  per  disk  rotation’’ — naturally 
the  best  performance  possible.  I'll  ex¬ 
plain  how  and  why  this  is  so  and 
show  you  how  to  achieve  this  your¬ 
self. 

The  attentive  reader  may  already 
have  thought  of  the  second,  less  trivi¬ 
al  problem.  The  head  settle  parame¬ 
ter  is  supposed  to  indicate  the  num¬ 
ber  of  milliseconds  of  delay. 
Eliminating  the  delay  on  the  AT  by 
setting  the  count  to  0  instead  of  1 
should  save  1  millisecond  per  seek- 


to-track.  The  test  reads  16  different 
tracks,  so  there  should  be  an  im¬ 
provement  of  16  milliseconds,  not 
more  than  3  seconds. 

Further  tests  indicated  that  in¬ 
creasing  the  settling  time  past  1  milli¬ 
second  resulted  in  no  further  deteri¬ 
oration  of  performance  until  the 
count  passed  90,  at  which  time  I  lost 
another  3-plus  seconds,  and  so  on. 


The  solution  appears  easy  now,  but  it 
took  some  work  to  arrive  at  it. 

I  pored  over  the  AT  BIOS  listing  to 
find  out  if  the  head  settle  parameter 
is  used  in  some  other  way  in  addition 
to  the  seek  operation.  The  answer  is 
no:  There  is  no  other  use  of  this  vari¬ 
able  other  than  counting  the  number 
of  1-millisecond  delays  taken  imme¬ 
diately  after  a  seek. 


0.002258300  —  Settle 

delay  loop  time 

as  tested. 

Settle  Delay, 

Rslt 

Cnt  &  Millisecs: 

Times: 

SettleCount: 

0 

Totl: 

6.662 

Delay  time: 

0.00 

Wait: 

6.612 

Total  calc,  delay: 

0.000 

SettleCount: 

1 

Totl: 

9.786 

Delay  time: 

2.26 

Wait: 

9.699 

Total  calc,  delay: 

0.036 

SettleCount: 

2 

Totl: 

9.786 

Delay  time: 

4.52 

Wait: 

9.661 

Total  calc,  delay: 

0.072 

SettleCount: 

4 

Totl: 

9.786 

Delay  time: 

9.03 

Wait: 

9.590 

Total  calc,  delay: 

0.145 

SettleCount: 

8 

Totl: 

9.786 

Delay  time: 

18.07 

Wait: 

9.450 

Total  calc,  delay: 

0.289 

SettleCount: 

16 

Totl: 

9.786 

Delay  time: 

36.13 

Wait: 

9.160 

Total  calc,  delay: 

0.578 

SettleCount: 

32 

Totl: 

9.786 

Delay  time: 

72.27 

Wait: 

8.595 

Total  calc,  delay: 

1.156 

SettleCount: 

64 

Totl: 

9.786 

Delay  time: 

144.53 

Wait: 

7.457 

Total  calc,  delay: 

2.313 

SettleCount: 

80 

Totl: 

9.785 

Delay  time: 

180.66 

Wait: 

6.890 

Total  calc,  delay: 

2.891 

SettleCount: 

88 

Totl: 

9.785 

Delay  time: 

198.73 

Wait: 

6.605 

Total  calc,  delay: 

3.180 

SettleCount: 

90 

Totl: 

9.786 

Delay  time: 

203.25 

Wait: 

6.536 

Total  calc,  delay: 

3.252 

SettleCount: 

91 

Totl: 

12.776 

Delay  time: 

205.51 

Wait: 

9.490 

Total  calc,  delay: 

3.288 

SettleCount: 

92 

Totl: 

12.975 

Delay  time: 

207.76 

Wait: 

9.658 

Total  calc,  delay: 

3.324 

SettleCount: 

120 

Totl: 

12.978 

Delay  time: 

271.00 

Wait: 

8.650 

Total  calc,  delay: 

4.336 

SettleCount: 

128 

Totl: 

12.976 

Delay  time: 

289.06 

Wait: 

8.376 

Total  calc,  delay: 

4.625 

SettleCount: 

255 

Totl: 

16.164 

Delay  time: 

575.87 

Wait: 

7.040 

Total  calc,  delay: 

9.214 

Table  1:  Disk  performance  by  head  settle  time 
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To  eliminate  any  noise  in  my  data 
caused  by  losing  interrupts  during 
processing  and  the  coarse  granulari¬ 
ty  of  the  usual  18.2-tick-per-second 
interrupt  clock,  I  coded  a  routine  to 
access  the  AT  high-resolution  timer, 
which  provides  1,024  interrupts  ev¬ 
ery  second.  For  those  who  are  inter¬ 
ested,  Listing  Two,  page  95,  is  the 


program  used  to  access  the  AT  clock. 

The  high-resolution  timings  con¬ 
firmed  the  other  results  and  also 
gave  a  more  accurate  figure  for  the 
delay  loop  as  coded  in  the  BIOS.  Al¬ 
though  the  number  of  cycles  in  the 
delay  instructions  total  approximate¬ 
ly  1  millisecond  of  CPU  time,  because 
of  cycle-stealing  memory  refresh 
and  other  perturbations,  the  actual 
time  for  one  iteration  of  the  loop  is 
actually  about  2.25  milliseconds.  This 


still  could  not  account  for  the  3.5  sec¬ 
onds  of  performance  improvement. 

Next  I  moved  the  BIOS  code  down 
into  RAM  so  patches  could  be  made 
and  breakpoints  set:  It  was  impossi¬ 
ble  to  determine  anything  more 
from  just  timing  the  disk  interrupt.  I 
inserted  a  patch  to  time  the  subrou¬ 
tine  that  waits  for  the  disk  adapter  to 
respond  to  the  last  command  sent. 
This  routine,  called  WAITMNT  in  the 
BIOS,  just  loops  until  an  interrupt  is 
received  from  the  adapter,  after  a 
command  has  been  sent  to  the  disk- 
controller  chip. 

Results  of  My  Tests 

I  performed  60  timing  runs  consist¬ 
ing  of  20  different  settle  time  param¬ 
eters,  run  3  times  each.  In  each  test  I 
counted  the  overall  time  required  to 
read  the  16  cylinders  and  the  total 
time  spent  in  the  WAITMNT  routine. 

Table  1,  page  45,  shows  the  means 
of  the  times  plotted  against  the  head 
settle  time  as  specified  in  the  param¬ 
eter  block  and  as  calculated  accord¬ 
ing  to  my  2.25-millisecond  figure  for 
the  delay  loop. 

What  is  interesting  to  note  in  this 
table  is  that  overall  disk  performance 
changes  as  a  step  function,  not  con¬ 
tinuously  and  the  times  are  constant 
over  a  wide  range.  Note  also  that  the 
WAITMNT  time  decreases  as  the  head 
settle  time  increases,  so  the  result  is 
constant  except  at  the  breakpoints  of 
2.26,  205.5,  and  575.87  milliseconds  of 
settle  time. 

Within  each  range,  the  longer  BIOS 
delays  after  a  seek,  the  less  time  it 
takes  for  WAITMNT  to  receive  the  in¬ 
terrupt  from  the  controller,  until  the 
delay  time  passes  a  certain  threshold. 
What  is  happening  at  that  threshold? 
If  you  examine  the  differences  be¬ 
tween  each  plateau,  you  will  see  that 
each  jump  in  overall  time  is  about  3 
seconds.  If  you  divide  the  differences 
by  the  number  of  seeks  (16)  then  you 
get  a  figure  (0.18,  0.19,  and  so  on)  sug¬ 
gestively  close  to  the  time  it  takes  for 
a  300-RPM  drive  to  make  one  revolu¬ 
tion — 0.2  seconds.  The  second  jump 
in  the  step  function  occurs  when  the 
settling  delay  increases  from  2  milli¬ 
seconds  to  205  milliseconds,  also  very 
suggestive. 

From  these  results,  I  developed  the 
hypothesis  that  the  overall  time  is 
constant  within  each  rotational  peri¬ 
od  of  the  disk.  If  a  1-millisecond  delay 


Settle  delay  loop  time  as  tested: 
0.002258 


Settle 

Calc’ed 

Total 

Result 

Calc’ed 

Count: 

1  Loop 

Timed: 

Waiting: 

16*Dlays 

(Milliseconds) 

0 

0.000 

6.662 

6.612 

0.000 

1 

2.258 

* 

9.786 

9.699 

0.036 

BREAK  POINT 

2 

4.517 

9.786 

9.661 

0.072 

4 

9.033 

9.786 

9.590 

0.145 

8 

18.066 

9.786 

9.450 

0.289 

16 

36.133 

9.786 

9.160 

0.578 

32 

72.266 

9.786 

8.595 

1.156 

64 

144.531 

9.786 

7.457 

2.313 

80 

180.664 

9.785 

6.890 

2.891 

88 

198.730 

9.785 

6.605 

3.180 

90 

203.247 

9.786 

6.536 

3.252 

91 

205.505 

* 

12.776 

9.490 

3.288 

BREAK  POINT 

92 

207.764 

12.975 

9.658 

3.324 

94 

212.280 

12.970 

9.330 

3.396 

96 

216.797 

12.978 

9.513 

3.469 

104 

234.863 

12.978 

9.223 

3.758 

112 

252.930 

12.978 

8.937 

4.047 

120 

270.996 

12.978 

8.650 

4.336 

128 

289.063 

12.976 

8.376 

4.625 

174 

392.944 

* 

16.166 

9.666 

6.287 

BREAK  POINT 

255 

575.867 

16.164 

7.040 

9.214 

260 

587.158 

* 

19.350 

9.674 

9.395 

BREAK  POINT 

346 

781.372 

* 

22.141 

9.283 

12.502 

BREAK  POINT 

*  Analysis  of  breakpoints: 

Mean 

6.662 

Delta 

Settle 

0.000 

Delta 

Total 

9.786 

in 

0.195 

time 

0.002 

in 

Time 

12.951 

Total 

0.198 

delay 

0.206 

Delay  0.203 

for 

16.165 

Times, 

0.201 

for 

0.393 

time:  0.187 

break¬ 

19.350 

per tk: 

0.199 

Major 

0.587 

0.194 

points: 

22.141 

0.174 

Breaks: 

0.781 

0.194 

> 

>Mean: 

0.193 

>>Mean:  0.195 

Disk  stats: 

Revolutions  per  head  settle  delay: 

RPM: 

300 

0.002 

0.011  =  0 

RPS: 

5 

0.206 

1.028  =  1 

SPR: 

0.200 

0.393 

1.965  =  2 

(Seconds  per  rev.) 

0.587 

2.936  =  3 

0.781 

3.907  =  4 

Table  2:  Disk  I/O  speeds,  16-cylinder  reads  with  different  head  settle  time 
delay  parameters 


Dr.  Dobb’s  Journal,  March  1986 

182 


46 


is  taken  immediately  after  a  seek  op¬ 
eration,  subsequent  processing  must 
wait  a  full  rotation  before  continu¬ 
ing.  No  further  degradation  occurs 
with  increased  delays  until  the  delay 
equals  or  exceeds  the  rotational  peri¬ 
od,  at  which  time  processing  time  in¬ 
creases  again  by  the  rotation  rate. 
The  longer  the  BIOS  waits  for  head 
settling,  the  less  time  WAIT—INT  waits 
for  the  rotation  of  the  disk  to  com¬ 
plete. 

The  data  in  Table  1,  page  45,  is  in¬ 
conclusive,  however,  because  there  is 
no  entry  for  400+  milliseconds  and 
beyond:  The  interval  between  2  and 
204  milliseconds  alone  is  not  enough 
to  prove  the  theory  and  the  test  at  575 
milliseconds  has  increased  the  delay 
too  much  to  verify  the  200-millisec¬ 
ond  period. 

Table  2  shows  the  results  of  addi¬ 
tional  tests  that  confirmed  the  hy¬ 
pothesis.  If  you  examine  the  table, 
you  will  see  that  the  jump  from  12.9 
to  16.1  seconds  of  processing  time  oc¬ 
curs  at  just  about  400  milliseconds 
and  from  16.1  to  19.3  at  600  millisec¬ 
onds.  Final  confirmation  is  given  by 
the  jump  at  781  (close  enough  to  800) 
milliseconds.  Intervening  data  points 
in  the  600-  to  800-millisecond  range 
are  omitted,  but  timings  showed  the 
same  plateaus  as  the  other  data. 

Now  we  can  see  why  DOS  "can 
reach  and  sustain  an  input  rate  of 
one  track  per  disk  rotation.”  The 
trick  is  that  by  skipping  the  head  set¬ 
tle  delay  altogether,  there  is  no  wait 
for  an  additional  rotation  of  the  disk 
and  no  latency  degradation.  One  mil¬ 
lisecond  of  delay  is  enough  to  force 
the  controller  to  wait  for  another  200 
milliseconds  before  the  operation 
can  complete. 

Other  Points 

Returning  to  other  points  in  Cortesi's 
column,  it  was  simple  to  check  more 
thoroughly  into  the  problem  of  BASIC 
and  disk  I/O  as  outlined  in  the  article. 
I  found  that  indeed,  as  Cortesi  writes 
(it's  even  documented  in  the  manual), 
BASIC  uses  a  default  disk  buffer  size  of 
128  bytes.  Increasing  the  buffer  size 
can  be  done  with  a  command-line 
switch:  To  specify  a  1,024-byte  disk 
buffer,  the  command  is  BASIC./S:1024. 

I  tried  the  test  program  with  a 
buffer  size  of  8,192  bytes,  and  BASIC 
took  only  10+  seconds  to  perform  its 
DOS  functions,  as  opposed  to  44  sec- 


SPEEDING  MS  DOS 


onds  with  a  128-byte  buffer.  Because 
BASIC  uses  DOS  for  its  file  I/O,  forcing 
the  head  settle  time  to  0  had  no  ef¬ 
fect:  The  minimum  value  is  in  effect 
whenever  DOS  performs  BIOS  disk 
read  calls. 

All  these  results  can  be  summa¬ 
rized  as  follows.  First,  there  is  no 
mystery,  magic,  or  extraordinary 
cleverness  involved  in  how  DOS  han¬ 
dles  disk  I/O,  and  it  certainly  uses  the 
ROM  BIOS.  The  magic  goes  away 
when  all  the  facts  are  in,  although 
there  are  new  problems  to  solve. 

According  to  my  findings,  when 
performing  file  I/O  through  DOS,  you 
can  expect  the  best  performance 
when  you  read  a  block  size  of  more 
than  COOOh  bytes.  DOS  reads  blocks  al¬ 
most  an  entire  segment  (64K)  at  a 
time  when  you  use  the  COPY  com¬ 
mand.  Why  settle  for  less  (no  pun  in¬ 
tended)  if  you  have  the  memory? 

When  writing  your  own  BIOS  disk 
handlers  using  interrupt  13h,  set  the 
head  settle  time  to  0  for  all  read  oper¬ 
ations.  It  must  be  longer  for  write  op¬ 
erations,  but  you  can  ignore  the  over¬ 
all  impact  the  settling  time  will  have 
on  performance  because  you  will 
catch  the  latency  delay  of  200  milli¬ 
seconds.  Use  the  documented  re¬ 
quired  values  for  write  head  settling 
times.  This  has  no  effect  when  file  I/O 
is  performed  through  DOS  because 
DOS  takes  care  of  the  settling  time  pa¬ 
rameter  already. 

You  can,  however,  shave  additional 
seconds  from  both  your  own  disk  I/O 
and  DOS's  with  the  motor-start-delay 
parameter:  Reduce  this  value  to  the 
minimum  value  that  does  not  cause 
errors  when  you  first  access  the  disk. 
(I  found  no  problems  with  a  start-up 
delay  of  0.)  Listing  Three,  page  100, 
shows  you  how  to  set  the  head  settle 
time  and  motor  start-up  delay  in  an 
assembly-language  program. 

DDJ 


(Listing  begins  on  page  94.) 
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Automatic  Porting 
Between  Pascal  Dialects 


n  the  course  of  programming 
events,  some  people  have  found 
it  necessary  to  write  Pascal  code 
that  could  be  ported  between  dia¬ 
lects  of  Pascal  that  ditfer  from  ma¬ 
chine  to  machine.  This  task  cannot 
be  accomplished  just  by  writing  "va¬ 
nilla”  code  to  a  maximal  degree,  as 
there  are  inevitably  syntactical  and 
semantic  differences  between  dia¬ 
lects.  At  QCAD,  we  have  developed  a 
technique  that,  in  conjunction  with 
vanilla  code,  allows  translation  from 
one  dialect  to  another  to  be  per¬ 
formed  automatically.  Generally, 
when  a  file  of  program  text  needs  to 
be  translated  to  a  new  dialect,  it  also 
needs  to  be  transmitted  to  a  physical¬ 
ly  separate  computer,  and  so  our 
translation  utility  exists  in  two  forms: 
a  stand-alone  translation  utility  and  a 
combination  translation/transmis- 
sion  utility. 

Finding  the  Denominator 

The  primary  task  is  to  reduce  func¬ 
tions  and  procedures  to  common  de¬ 
nominators — that  is,  if  a  function  does 
not  exist  in  one  dialect,  it  must  be  writ¬ 
ten  for  that  dialect  using  the  dialect’s 
own  primitives.  This  could  be  a  simple 
renaming.  Consider  the  following  two 
functions,  for  example: 

Turbo  Pascal: 

copyistring,  location,  length) 
VAX  Pascal: 

substrlstring,  location,  length) 

As  it  happens,  these  functions  are 
semantically  identical,  only  the 
names  have  been  changed  to  confuse 
the  unwary.  If  we  have  written 
some  code  in  Turbo  Pascal,  then  we 
simply  create  a  copy  function  for 
VAX  Pascal: 


®  1985  QCAD  Systems  Inc.,  1164  Hyde 
Ave.,  San  Jose,  CA  95129 


by  Michael  J.  Sorens 


DIALATE  converts  one 
dialect  of  Pascal  to 
another >  provided 
programs  are  written 
according  to  the 
guidelines. 


function  copylSTR:  string255; 

WHERE,  LEN:  integer):  string255; 
begin 

copy  :=  substrlstr,  where,  len); 
end; 

Thereafter,  we  can  use  the  copy 
function  in  either  Turbo  Pascal  or 
VAX  Pascal.  Of  course,  we  want  the 
above  definition  of  copy  to  exist  only 
in  the  VAX  environment  because  it 
will  generate  compilation  errors  in 
Turbo;  we  will  see  how  to  selectively 
compile  this  kind  of  entity  shortly. 

A  second  case  might  be  this:  In  eval¬ 
uating  a  logical  expression,  HP  Pascal, 
for  example,  has  a  compiler  option  to 
do  only  partial  evaluation  (a  la  C)  in 
which  an  expression  is  evaluated 
only  until  the  point  at  which  its  result 
is  determinable.  C  programmers  use 
this  to  establish  and  avoid  side  effects. 
(It  is  quite  a  useful  thing  to  have,  but, 
alas,  having  it  in  only  one  Pascal  dia¬ 
lect  makes  life  difficult.) 

If  the  function  foo  changes  some 
global  variable  y,  for  example,  then 
(false  andfoo(y)  j  will  not  change  y  if 
the  dialect  uses  partial  evaluation. 
This  is  because  of  the  way  the  Bool¬ 
ean  AND  operates.  Both  terms  must 
be  true  for  the  conjunction  to  be  true. 
Scanning  from  left  to  right,  because 
I  the  first  term  false  is  false,  we  do  not 
I  need  even  to  look  at  fool y)  to  deter¬ 


mine  the  result.  Without  the  partial 
evaluation  feature,  foo(y)  will  al¬ 
ways  be  evaluated,  potentially  yield¬ 
ing  differing  results. 

A  second  example  might  be  a  test 
such  as 

while  (count  <  =  lengthlstr) )  and 
Istrjcount]  =  'X')  do  .  .  . 

which  is  a  valid  statement  with  par¬ 
tial  evaluation  but  can  cause  a  run¬ 
time  error  without  it.  Why?  Well,  as 
long  as  count  is  less  than  or  equal  to 
the  length  of  the  string  str,  there  is  no 
problem.  When  count  becomes  one 
larger  than  the  length  of  str,  howev¬ 
er,  referencing  str  [count  I  may  cause 
a  run-time  error,  depending  on 
whether  range  checking  is  enabled 
for  a  particular  compiler. 

Therefore,  we  must  modify  the 
code  in  which  results  might  vary  de¬ 
pending  on  whether  partial  evalua¬ 
tion  is  available.  This  could  be  done 
by  introducing  a  two-step  evaluation. 
That  is,  rather  than  if  (false  and 
foo(y)  )  then  .  .  .  ,  we  substitute  if  false 
then  iffoo(y)  then  .  .  . ,  which  guaran¬ 
tees  an  equivalent  partial  evaluation. 
The  while  loop  requires  introducing 
some  ugliness.  We  need  a  Boolean 
variable — call  it  done — which  we  ini¬ 
tialize  to  false.  Then,  the  code  might 
be 

while  (count  <  =  lengthlstr) )  and 
(not  done)  do  begin 
done  :=  IstHcount]  =  ’X’); 
if  not  done  then  .  .  . 

The  simple  elegance  and  power  of 
partial  evaluation  begins  to  shine 
through,  no? 

A  more  cumbersome  reduction  in¬ 
volves  string  comparisons.  In  HP  Pas¬ 
cal  or  Turbo  Pascal,  you  could  com¬ 
pare  strings  si  and  s2  merely  by 
interposing  a  relational  operator — 
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for  example,  (si  < s2)  or  (si  =  s2).  In 
VAX  Pascal,  however,  only  strings  of 
the  same  length  can  be  compared 
(not  strings  of  the  same  maximal 
length  but  strings  of  the  same  length 
at  the  moment  of  comparison).  Thus, 
we  need  to  introduce  an  added  func¬ 
tional  level  in  all  three  Pascals  so  that 
the  code  can  be  identical.  We  create 
the  function  StrCmp  (see  Table  1, 
below).  Then,  if  we  have  existing 
code  that  needs  to  be  retrofitted,  we 
must  change  occurrences  of  (si  =  s2) 
to  (strcmptsl,  s2)  =  0)  and  likewise 
for  the  other  relational  operators. 

Make  That  Code  Disappear 

At  some  point,  there  will  be  pieces  of 
code  that  must  be  seen  by  one  compil¬ 
er  but  must  be  hidden  from  another. 
Enter  DIALATE.  DIALATE — a  combina¬ 
tion  of  the  words  dialect  and  trans¬ 
late — converts  one  dialect  of  Pascal  to 
another,  provided  a  program  text  file 
has  been  set  up  according  to  the 
guidelines  about  to  be  discussed. 

We  introduce  a  metanotation  to  be 
used  in  any  Pascal  we  are  interested 
in.  This  is  just  a  notation  that  is  in 
some  sense  "above”  the  Pascal  code 
in  that  our  translator  will  be  looking 
only  at  the  metanotation  and  not  at 
the  Pascal  text  itself.  In  our  metanota¬ 
tion,  we  have  metabrackets,  which 
are  the  only  constructs  that  DIALATE 
looks  for: 

{  @x  }  opening  metabracket  for 
dialect  x 

{  @  }  closing  metabracket 

We  use  the  curly  braces  {  and  }  as 
the  basis  of  our  dialect  notation  be¬ 
cause  they  already  have  the  capabili¬ 
ty  of  hiding  text  from  a  Pascal  com¬ 
piler — the  simple  comment.  DIALATE 
scans  for  comments  that  immediate¬ 
ly  begin  with  an  (5)  symbol,  indicat¬ 
ing  that  the  comment  is  a  special,  dia¬ 
lectic  comment.  Immediately 
following  the  @  can  be  one  or  more 
dialect  designations.  We  currently 
use  the  following  conventions: 

T — Turbo  Pascal  (IBM  PC) 

V— VAX  Pascal  (VMS) 

H— HP  Pascal 

A — Apple  Pascal  (Macintosh) 

Any  piece  of  code  that  cannot  run  on 
all  relevant  machines  must  be  sur¬ 
rounded  by  metabrackets.  DIALATE 


inserts  and  removes  the  right  curly 
brace  of  the  opening  metabracket  in  a 
judicious  manner  so  that  the  compiler 
"sees”  only  valid  language  constructs. 

Let’s  look  at  an  example.  Consider 
opening  a  file  for  input  in  Turbo  Pas¬ 
cal  and  in  HP  Pascal: 

Turbo  Pascal: 

assign(MyFile,  FileName); 
reset(MyFile); 

HP  Pascal: 

resetlMyFile,  FileName); 

Because  there  are  significant  differ¬ 
ences,  it  is  perhaps  wise  to  create  a 
procedure  OpenlnputFile  that  can  be 
used  in  both  Pascal  dialects.  Here  is 
what  the  procedure  will  look  like  in 
Turbo  Pascal: 

(1)  procedure  OpenlnputFile 

(var  F:  text; 

NAME:  string80); 

(2)  begin 

(3)  {  @T } 

(4)  assignlf,  name); 

(5)  resetlf ); 

(6)  { @  } 

(7)  { @H 

(8)  resetlf,  name); 

(9)  { @  } 

(10)  end; 

Examine  the  position  of  each  of  the 
curly  braces  carefully.  Notice  that  in 
line  3  there  is  a  }  but  that  in  line  7 
there  is  not.  Thus,  lines  4  and  5  are 
active  code,  while  line  8  is  passive 
code.  Lines  6  and  9  are  closing  meta¬ 
brackets  that  never  change.  The  {  in 
line  6  begins  a  comment  that  hides 
the  @  character,  while  the  { in  line  9 
is  ignored  because  it  is  already  inside 


a  comment.  Now  let’s  run  the  proce¬ 
dure  through  DIALATE,  converting  it 
to  HP  Pascal  code: 

(1)  procedure  OpenlnputFile 

(var  F:  text; 

NAME:  string80); 

(2)  begin 

(3)  { @T 

(4)  assign!  f,  name); 

(5)  resetlf ); 

(6)  {  @  } 

(7)  {  @H  } 

(8)  resetlf,  name); 

(9)  {  @  } 

(10)  end; 

The  only  difference  is  that  the  }  in 
line  3  has  gone,  and  there  is  a  new  } 
in  line  7.  This  has  reversed  the  active 
and  passive  sections  of  code.  Hence, 
to  write  a  piece  of  automatically 
translatable  code,  decide  which  dia¬ 
lect  you  wish  to  write  in  and  use  the 
appropriate  metabrackets. 

The  technique  is  extensible  to  mul¬ 
tiple  machines  with  a  concise  nota¬ 
tion.  Take,  for  example,  a  function  to 
find  the  location  of  a  pattern  string 
within  some  other  string.  In  Turbo 
Pascal  and  HP  Pascal,  this  function  is 
called  pos,  while  in  VAX  Pascal  it  is 
called  zndey.  We  could  then  write  a 
compatibility  function  called  zndey  to 
be  used  in  Turbo  or  HP  Pascal  or  one 
called  pos  to  be  used  in  VAX  Pascal.  A 
third  alternative,  though,  is  to  write  a 
function  with  a  new  name,  perhaps 
LocateSubString,  to  be  used  in  all 
three  languages.  Stylistically,  it  might 
be  better  to  use  a  very  different 
name  so  that  there  is  no  chance  of 
confusing  the  name  with  some  other 
valid  language  construct.  As  it  hap- 


function  StrCmp(S,  T:  string80):  integer; 

{ return  —  1  if  s<t;  0  if  s=t;  1  if  s > t } 

var  Result:  integer; 

begin 

if  length(s)  <  length(t)  then  begin 
result :  =  StrCmpfs,  copy(t,  1 ,  length(s) ) ); 
if  result  =  0  then  StrCmp  :  =  —  1  else  StrCmp  :  =  result 
end 

else  if  length(s)  >  length(t)  then  begin 
result :  =  StrCmp(copy(s,  1 ,  length(t) ),  t); 
if  result  =  0  then  StrCmp  :  =  1  else  StrCmp  :  =  result 
end 

else  if  s  =  t  then  StrCmp  :  =  0 
else  if  s  <  t  then  StrCmp  :  =  —  1 
else  if  s  >  t  then  StrCmp  :  =  1 
end; 


Table  1 


51 
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pens,  the  functions  pos  and  index  do  j 
precisely  the  same  thing,  though 
their  parameter  order  is  different,  so 
we  do  not  have  to  write  much  code. 

(1)  function  LocateSubString 

(Object, 

Target:  string80):  integer;  [ 

(2)  begin 

I  (3)  {  @HT 

i  (4)  LocateSubString :  = 

postobject,  target); 

(5)  {  @  } 

(6)  {  @V  } 

(7)  LocateSubString  :  = 

indexltarget,  object); 

(8)  {  @  } 

(9)  end; 

We  can  see  that  the  above  function  is 
!  written  in  VAX  Pascal  because  line  7, 
i  the  VAX  code,  is  active.  Line  4  is  passive 
|  code  that  is  for  both  the  HP  and  the 
|  Turbo  dialects  because  line  3  has  both 
j  a  T  and  an  H.  When  translated  to  ei-  j 
j  ther  of  these  dialects,  line  4  becomes 
|  active,  while  line  7  becomes  passive. 

i  Case  in  Point 

j  One  final  twist  has  precipitated  out 
j  of  the  Babel-like  differences  in  Pas- 
j  cals,  and  that  is  the  else  clause  of  a 
:  case  statement.  Some  Pascals,  such  as  | 
i  Turbo,  use  the  keyword  else  to  indi- 
j  cate  any  cases  not  explicitly  enumer- 
i  ated.  Other  Pascals,  such  as  VAX,  HP, 
and  Macintosh,  use  the  keyword  oth¬ 
erwise.  We  can  certainly  handle  this  j 
discrepancy  using  our  standard  me¬ 
tanotation  described  in  the  previous 
section.  A  typical  case  statement 
might  look  like  this: 

case  SelectionChar  of 
'R':  Runlt; 

’P’:  Processlt; 

'E':  Editlt; 

{ @T }  else  {  @  }  1 

{  @HVA  otherwise  {  @  } 

writelnl 'Invalid  selection 
!  character); 

end  {  case  }  ; 

This  can  quickly  become  an  annoy-  ! 
ance,  though.  Because  there  is  no  way 
to  make  some  kind  of  generic  func¬ 
tion  that  handles  all  case  statements 
(as  we  did  with  OpenlnputFile),  we 
must  use  the  metabrackets  every  time 
we  have  a  case  statement.  Or  rather, 
we  would  have  to  if  DIALATE  didn't 
have  a  better  solution. 


What  we  would  like  to  do  is  have 
the  translator  automatically  convert 
an  else  to  an  otherwise  if  we  are  going 
from  Turbo  to  either  HP,  VAX,  or  Mac¬ 
intosh  Pascal  and  convert  an  other¬ 
wise  to  an  else  if  we  are  going  in  the 
converse  direction.  But  wait,  what 
about  the  oft-found  if.  .  .  then 
.  .  .  else  .  .  .  statement?  How  will  we 
know  if  an  else  belongs  to  an  if  or  to  a 
case? 

What  we  have  chosen  to  do  is  have 
a  special  ELSE-OTHERWISE  conven¬ 
tion.  In  Turbo  Pascal,  we  write  ELSE 
to  denote  an  else  of  a  case  statement 
and  else  to  denote  an  else  of  an  if 
statement.  In  our  other  Pascals,  we 
write  OTHERWISE  to  denote  an  other¬ 
wise  of  a  case  statement  and  else  to 
denote  an  else  of  an  if  statement. 
That  is,  the  case  clause — whatever  it 
is  called — must  be  in  uppercase  let¬ 
ters,  while  the  if  clause  must  be  in 
lowercase  letters. 

Discussion 

This  dialect  translation  technique  has 
minor  disadvantages.  The  foremost  is 
that  you  must  have  all  metabrackets 
balanced  and  correct,  otherwise  you 
might  hide  too  little  or  too  much  code 
from  the  compiler.  This  might  cause 
compilation  errors,  but  it  also  might 
not,  possibly  creating  subtle  bugs.  If 
we  accidentally  made  the  VAX  code 
above  into  passive  code,  for  example, 
then  the  LocateSubString  function 
would  never  be  assigned  a  value.  This 
could  cause  random  or  unpredictable 
results  in  the  program.  On  the  other 
hand,  if  we  made  both  assignments 
active,  a  compiler  should  complain 
about  the  unknown  function  index  or 
pos,  depending  on  which  machine 
the  code  is  compiled.  It  takes  a  little 
getting  used  to,  but  typing  correct  me¬ 
tabrackets  is,  after  all,  no  more  diffi¬ 
cult  than  typing  correct  syntax  in  a 
programming  language. 

Second,  it  is  not  possible  to  put  actu¬ 
al  comments  inside  a  region  that  is 
metabracketed.  This  may  cause  com¬ 
pilation  errors  when  the  entire  re¬ 
gion  is  supposed  to  be  hidden  because 
the  closing  comment  bracket  could 
inadvertently  reactivate  a  portion  of 
the  hidden  code.  This  is  most  insid¬ 
ious,  however,  when  it  does  not  cause 
compilation  errors,  as,  for  example: 

procedure  DUMMY; 

begin 


I  { @H 
a  :=  10; 
b  :=  5; 

(@) 

{@T} 

a  :  =  5;  {  some  global  variables  } 

b  :=  10; 

{@} 

I  end; 

The  above  code,  as  written,  will 
work  fine  with  the  Turbo  compiler. 
When  we  translate  it  to  run  with  HP 
Pascal,  however,  we  will  get  the 
wrong  value  for  b  because  the  clos¬ 
ing  }  of  the  "real”  comment  will  pre¬ 
maturely  close  the  comment  created 
by  the  metabrackets. 

The  dialect  translation  technique 
discussed  in  this  article  is  an  effective 
and  rapid  way  to  work  in  several  dif¬ 
ferent  Pascals  with  virtually  the 
same  program  text.  It  may  seem 
awkward  at  first,  but  you  can  readily 
get  used  to  the  style.  And  for  those 
who  need  to  work  with  more  than 
one  dialect  or  more  than  one  ma¬ 
chine,  the  tool  may  prove  invaluable. 
DIALATE  was  developed  because  of  a 
perceived  need  at  QCAD.  We  manu¬ 
facture  a  large  software  package  (a 
parser  generator)  that  runs  on  the 
machines  discussed  above;  DIALATE 
allows  us  to  keep  the  same  code  on 
all  the  machines. 

Should  there  be  any  readers  who 
are  so  amazed  by  the  technique  re¬ 
vealed  in  this  article  (for  the  first 
i  time  anywhere),  I  will  gladly  supply 
both  object  and  source  code  for  DIA¬ 
LATE  for  a  mere  $10.24  (a  kilopenny) 
to  cover  diskette,  postage,  copying, 
and  so  on.  I  will  also  be  happy  to  tell 
you  about  some  of  the  neat  software 
tools  that  QCAD  sells  for  real  money. 

DDJ 

Reader  Ballot 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  6. 
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_ LETTERS 

LISTING  ONE  (Text  begins  on  page  8) 


Bose-Nelson  Sort  -  Recursive  Version 

by  R  J  Wissbaum 

15553  E  Wyoming  Dr  -  H 
Aurora,  CO  80012 

Reference : 

Dr.  Dobb's  Journal 
September  1985  (#107) 

Page  68 


linclude  "STDIO.H" 

int  count  -  0; 

main  (  argc,  argv  ) 
int  argc, *argv; 

(  int  n; 

char  arg(255J; 
if  {  argc  <2  ) 

(  printf  {  "USAGE:  bose5  n  >outfile  \n"  ); 
exit  ()  ; 

) 

else 

(  getarg(  1,  arg,  255,  argc,  argv  ); 
n  -  atoi (  arg  ) ; 
if  (  n<0  )  n  -  -n; 
bosesort  (  2,  1,  n,  0,  0  ); 
printf  (  "There  were  %d  swaps  \n",  count  ); 

) 

) 

bosesort (  n,  i,  x,  j,  y  ) 
int  n,  i,  x,  j,  y; 

{  int  a,  b; 
switch  (  n  ) 

< 

case  0:  {  /*  printf  (  ")\n"  );  */ 

} 

break; 

case  1:  {  /*  printf  (  "swap  (  %d,  %d  );  \n",  i,  x  );  */ 

count ++; 

} 

break; 

case  2:  {  if  (  x  !-  1  ) 

(  a  ■  {  x  /  2  ) ; 

bosesort  (  3,  i,  a,  (i+a),  (x-a)  ); 
bosesort  (  2,  (i+a),  (x-a),  0,  0  ); 
bosesort  (  2,  i,  a,  0,  0  ) ; 

) 


case  3 :  {  a  -  (  x  /  2  ) ; 

if  (  even  (x))  b-(y+l)/2; 

else  b  -  (  y  /  2  ) ; 

if  (  (  x  ==  1  )  &&  (  y  ==  1  )  )  bosesort  (  1,  i,  j,  0,  0  )  ; 

else  if  (  (  x  ==  1  )  &&  (  y  ==  2  )  ) 

{ 

bosesort  (  1,  i,  j,  0,  0  ) ; 
bosesort  (  1,  i,  (j+1),  0,  0  ); 

) 

else  if  (  (  x  —  2  )  &&  (  y  —  1  )  ) 

{ 

bosesort  (  1,  (i+1) ,  j,  0,  0  ) ; 

bosesort  (  1,  i,  j,  0,  0  ) ; 

) 

else  if  (  (  x  !=  0  )  &&  (  y  !=  0  )  ) 

{ 

bosesort  (  3,  (i+a),  (x-a),  j,  b  ); 

bosesort  (  3,  (i+a),  (x-a),  (j+b),  (y-b)  ); 

bosesort  (  3,  i,  a,  j,  b  ) ; 

) 


break; 
default:  { 

printf  (  "FATAL:  Error  in  stack  \n"  ) ; 
exit  (); 

) 

break; 

}  /*  End  of  WHILE  loop  */ 

)  /*  End  of  BOSESORT  */ 

even  <  x  ) 
int  x ; 

(  return  (  1  -  <  1  &  x  )  )  ;  ) _ 


End  Listing 
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LISTING  SIX  (Text  begins  on  page  14) 


char  *skipto (  c,  p,  esc  ) 
register  char  *p  ; 

register  int  c,  esc  ; 


/* 


Skip  to  c  or  to  end  of  string.  If  c  is  preceeded  by 
the  esc  character  it  is  skipped  over. 


while (  *p  &&  *p  !=  c  ) 

{ 

if  (  *p  !=  esc  ) 
P++  ; 

else  if  (  *++p  ) 
P++; 


return  (p) ; 


/*  skip  over  escaped  characters  */ 


End  Listing  Six 


LISTING  SEVEN 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 


*  DIR. H 


#defines  and  typedefs  needed  to  talk  to  the  routine  dir  () . 

A  pointer  to  the  DIRECTORY  structure  is  passed  to  dir () . 
DIRECTORY  structures  are  created  by  mk_dir()  and  deleted  with 
del  dir  () . 


On  entry: 
dirv 

lastdir 

maxdirs 

nfiles 

ndirs 

nbytes 


is  the  first  of  an  uninitialized  array  of  character 

pointers. 

should  be  initialized  to  point  at  dirv. 
is  the  size  of  the  above 


is  the  total  file  count,  the  total  directory  count 
and  the  total  byte  count.  These  will  be  incremented 
as  appropriate  and  are  usually  set  to  0  before 
calling  dir () . 

width  should  be  initialized  to  0  before  calling  dir(). 
vol_label  is  undefined  on  entry  to  dir(). 
longf  is  1  if  entrys  are  to  be  printed  in  long  format 
files  is  1  if  files  are  included  in  the  list, 

dirs  is  1  if  directors  are  included  in  the  list, 

graphics  is  1  if  directories  are  highlighted  with  boldface, 
hidden  is  1  if  hidden  files  are  to  be  included  in  the  list, 

path  is  1  if  the  path  name  is  to  be  included  in  the  list, 

label  is  1  if  you  want  to  get  the  volume  label 

exp  is  1  if  you  want  the  contents  of  a  subdirectory  to 

be  listed  rather  than  the  directory  name  when.  This 
is  only  looked  at  if  no  wild  cards  are  present  in 
the  file  spec. 

sort  is  1  if  you  want  the  list  sorted. 

all  other  fields  are  ignored.  On  exit  the  structure  will  have  been 
updated  as  follows: 

lastdir  will  be  incremented  to  point  at  the  last  entry  added 
to  the  dirv  table. 

maxdirs  will  be  decremented  to  reflect  the  added  entries, 
nfiles  is  the  number  of  added  entries  which  are  files, 
ndirs  is  the  number  of  added  entries  which  are  directories. 

Note  that  the  equivalent  of  argc  can  be  derrived  by 
adding  ndirs  and  nfiles  together, 
nbytes  will  have  the  total  size  in  bytes  of  all  files  added 
to  dirv.  This  number  is  the  number  of  bytes  actually 
occupied  by  the  file,  ie.  the  size  returned  by  DOS 
rounded  up  to  the  nearest  multiple  of  the  disk's 
cluster  size. 

vol_label  will  hold  the  volume  lable  provided  that  "label"  was 
set  on  entry. 

width  will  hold  the  length  of  the  widest  entry  added  to  dirv 


53 

*  all  other 

fields  will  have 

the  same  values  they  had  on  entry. 

54 

*/ 

55 

56 

typedef  struct 

57 

i 

58 

char 

**lastdir  ; 

/*  Most  recent  addition  to  dirv 

*/ 

59 

int 

maxdirs  ; 

/*  #  of  free  slots  in  dirv 

*/ 

60 

int 

nfiles  ; 

/*  #  of  used  slots  that  are  files 

*/ 

61 

int 

ndirs  ; 

/*  #  of  used  slots  that  are  directories 

*/ 

62 

long 

nbytes  ; 

/*  byte  count  of  files 

*/ 

63 

char 

vol_label  [12] ; 

/*  volume  lable  if  requested 

*/ 
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64 

65 

66 

unsigned  width 

7 

/*  Width  of  widest  element  in  dirv 

*/ 

/*  Various  flags  control  how  dir  works: 

*/ 

67 

unsigned  longf 

1 

/*  Use  long  format  for  entries 

*/ 

68 

unsigned  files 

1 

/*  Include  files  in  list 

*/ 

69 

unsigned  dirs 

1 

/*  Include  directories  in  list 

*/ 

70 

unsigned  graphics 

1 

/*  Use  graphics  around  directory  names 

*/ 

71 

unsigned  hidden 

1 

/*  List  hidden  files 

*/ 

72 

unsigned  path 

1 

/*  List  complete  path  if  given 

*/ 

73 

unsigned  label 

1 

/*  Load  vol  label  with  volume  label 

*/ 

74 

unsigned  exp 

1 

/*  Expand  sub-directories 

*/ 

75 

76 

77 

78 

79 

unsigned  sort 

1 

/*  Sort  added  entries 

*/ 

char  dirv[l); 

/*  The  first  of  the  dirv  entries 

*/ 

} 

DIRECTORY; 

End  Listing  Seven 

LISTING  EIGHT 


# include  <stdio.h> 

# include  <getargs.h> 
# include  <mydos.h> 

# include  <dir.h> 


/* 


DIR.C:  An  MSDOS  directory  access  function. 

(c)  Copyright  1985,  Allen  I.  Holub.  All  rights  reserved. 


11/22/85  Modified  so  that  the  total  amount  of  disk  space  used  | 


*/ 


1 
2 

3 

4 

5 

6 

7 

8 
9 

10 
11 
12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24  # define  BOLDFACE 

25  # define  ALL_OFF 

26 

27  # define  ATTRIBUTES 

28  #define  iswhite (c) 

29 

30  /* - 

31 


(ie.  #  of  clusters)  is  put  into  the  total,  rather 
than  the  file  size. 


/*  ROUND (n,u):  if  n  is  an  even  multiple  of  u,  evaluate  to  n,  else 
*  round  n  up  to  the  next  even  multiple  of  u. 

*/ 

#define  ROUND  (n,u)  (  !  ( (n)  %  (u) )  ?  (n)  :  ( ( (n)  /  (u) )  +1)  *  (u) ) 


"\033 [lm" 
"\033[0m" 


Ansi  esc  sequence  to  turn  bold  face  on  */ 
"  attributes  off  */ 


(READONLY  |  DIRTY  |  SYSTEM  |  HIDDEN 
((c)  ==  1  '  II  (c)  ==  '\t') 


SUBDIR) 


32 

extern 

char 

*calloc 

(unsigned, unsigned) 

;  /* 

In  standard  library 

33 

extern 

char 

*cptolower (char*, char*) ; 

/* 

In  /src/tools/cptolow.c 

34 

extern 

char 

*cpy 

(char*, char*) ; 

/* 

In  /src/tools/cpy.c 

35 

extern 

int 

dos 

(REGS  * ) ; 

/* 

In  /src/tools/dos.asm 

36 

extern 

void 

gregs 

(REGS  *) ; 

/* 

In  /src/tools/dos.asm 

37 

extern 

char 

*malloc 

(unsigned) ; 

/* 

In  standard  library 

38 

extern 

char 

*next 

(char**, int, int) ; 

/* 

In  /src/tools/next .c 

39 

extern 

void 

ssort 

(char*, int, int, int  (* 

)  0); 

r/*in  /src/tools/ssort .c 

40 

extern 

int 

stranp 

(char*,  char*); 

/* 

in  standard  library 

/* - * 

static  unsigned  Longfmt  =  0;  /*  True  if  we're  using  long  format.  This 

*  has  to  be  global  for  the  comparison 

*  routine  used  for  sroting  to  work. 

*/ 


static  unsigned  Cluster_size; 


/* 


Number  of  bytes  per  cluster  on 
requested  disk. 


41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56  #define  DOSCALL (id, regs)  {  regs.h.ah  =  id  ;  dos (  &regs  );  } 

57 

58  /* - 

59 

60  static  int  find_first  (  filespec,  attributes,  regp  ) 

61  char  * filespec  ; 


Do  a  DOS  system  call  using  the  dos()  routine 


*/ 


62  short 

63  register  REGS 
{ 


/* 


attributes; 

*regp; 

Get  directory  information  for  the  indicated  file. 
Ambiguous  file  references  are  ok  but  you  have  to  use 
find_next  to  get  the  rest  of  the  file  references. 

In  this  case.  The  regs  structure  used  by  find_first 
must  be  passed  to  find_next.  0  is  returned  on  success, 
otherwise  the  DOS  error  code  is  returned. 


(Continued  on  next  page) 
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LISTING  EIGHT  (Listing  continued,  text  begins  on  page  14) 


73 

regp->h.ah  =  (char)  FINDFIRST  ; 

74 

regp->x.dx  =  (short)  filespec  ; 

75 

regp->x.cx  =  attributes  ; 

76 

77 

return 

(int) (  (dos(regp)  &  CARRY)  ?  regp->x.ax  :  0  ); 

78 

i 

79 

80 

/* - 

81 

82 

static 

int 

find  next  (  regp  ) 

83 

REGS 

*regp; 

84 

f 

85 

/* 

Get  the  next  file  in  an  ambiguous  file  reference.  A 

86 

* 

call  to  this  function  must  be  preceded  by  a 

87 

* 

find  first  call.  The  regp  argument  must  be  the 

88 

★ 

same  register  image  used  by  the  find  first  call. 

89 

* 

0  is  returned  on  success,  otherwise  the  error  code 

90 

* 

generated  by  DOS  is  returned. 

91 

V 

92 

93 

regp->h.ah  -  FINDNEXT  ; 

94 

return 

(int) (  (dos(regp)  &  CARRY)  ?  regp->x.ax  :  0  ); 

95 

! 

96 

97 

/* - 

—  -  — 

98 

99 

int 

haswild  (s) 

100 

register  char 

*s; 

101 

i 

102 

/* 

Return  true  if  s  has  a  unix  wild  card  in  it.  */ 

103 

104 

for  (  ; 

*s  ;  s++) 

105 

if (  *S  ==  '*'  II  *s  ==  1  ?'  ) 

106 

return  1; 

107 

return 

0; 

108 

i 

109 

110 

111 

112 

static 

int 

isrootdir(  name  ) 

113 

register  char 

*name; 

114 

1 

115 

/* 

return  true  if  name  is  explicitly  specifying  the  root 

116 

* 

directory  (ie.  is  one  of:  d:/  d:\  /  \  where 

117 

* 

'd'  can  be  any  disk  designator. 

118 

*/ 

119 

120 

if  (  *name  &&  name[l]  ==  ) 

121 

name  +=  2; 

122 

123 

return!  (*name  ==  *\\'  ||  *name  ==  '/')  ss  Inamell]  ); 

124 

I 

125 

126 

/* - 

127 

128 

has  only(  str. 

inclusion  set  ) 

129 

register  char 

*str; 

130 

char 

* inclusion  Set; 

131 

i 

132 

/* 

Return  true  only  if  every  character  in  str  is  also  in 

133 

* 

inclusion  set.  True  is  returned  if  str  is  empty. 

134 

V 

135 

136 

register  char  *p; 

137 

138 

for ( ;  1 

*str  ;  str++) 

139 

i 

140 

for(  p  *=  inclusion  set  ;  *p  ss  *p  !=  *str  ;  p++  ) 

141 

142 

143 

if (  !*P  ) 

144 

return  0; 

145 

i 

146 

147 

return 

1; 

148 

i 

149 

150 

/* - 

151 

152 

static 

char 

*fixup  name (  name,  regs,  info  ) 

153 

register  char 

*name; 

154 

REGS 

*regs; 

155 

FILE  INFO 

*info; 

156 

157 

/*  if 

the  name  specifies  an  implicit  file  (ie.  it  asks  for 

158 

*  the  directory  rather  than  the  files  in  the  directory). 

159 

*  modify  it  to  ask  for  files  (eg.  becomes 

160 

*  If 

the  name  is  actually  modified,  a  pointer  to  a  modified 

161 

*  copy  of  the  original  name  is  returned.  Otherwise  the 
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162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184 

185 

186 

187 

188 

189 

190 

191 

192 

193 

194 

195 

196 

197 

198 

199 

200 
201 
202 

203 

204 

205 

206 

207 

208 

209 

210 
211  } 
212 

213  / 

214 


*  original  buffer  is  returned. 

*/ 

static  char  buf[80]  ;  /*  Place  to  put  modified  name  */ 

register  char  *p  =  buf  ;  /*  Always  points  into  buf  */ 

char  *start_name  =  name;  /*  Remember  start  of  name  */ 

if (  isrootdir (name)  ||  (name[0]  &&  name[l]  =  ':'  &&  !name[2])  ) 

{ 

/*  Handle  an  explicitly  requested  root  directory  or 
*  the  current  directory  on  another  disk. 

*/ 


sprintf(buf,  "%s*.*",  name  ); 

} 

else  if (  !find_first(  name,  ALL,  regs)  ) 

{ 

/*  Look  for  the  indicated  name  &  see  if  it's  a  directory. 
*  If  so,  append  slash-*.*  to  the  requested  name 
*/ 


} 

else 

{ 


if (  ! IS_SUBDIR (info)  ) 
return  name; 

else 

sprint f (buf,  "%s/*.*",  name  ); 


/*  If  we  get  here  then  a  non-existant  file  or  directory 

*  was  requested . 

*  If  the  name  consists  of  nothing  but  the  characters 

*  \  /  .  or  a  drive  designator,  assume  that  the  root 

*  directory  was  requested  and  adjust  the  name 

*  accordingly. 

*/ 


} 


if(  *name  &&  name[l]  ==  ':')  /*  Copy  drive  designator  if  */ 
{  /*  one's  present.  */ 

*p++  =  *name++  ; 

*p++  =  *name++  ; 

1 

if(  has_only (name,  ".\\/")  ) 
strcpy (  p,  "/*.*"  ); 

else 

return (  start_name  ) ; 


return (  buf  ) ; 


•*/ 


215  static  int  dirtoa (  target,  infop,  graphics,  pathname  ) 

216  register  char  * target  ; 

217  char  * pathname  ; 

218  register  FILE_INFO  *infop 

219  unsigned  graphics; 

220  { 


221 

/* 

Convert  directory  entry  held  in  infop  to 

an  ascii  string 

222 

* 

in  target.  If  Longfmt  use  a  long  format. 

if  graphics  then 

223 

* 

directory  names  are  printed  in  bold  face 

else  they're 

224 

★ 

printed  as  "<name>."  If  pathname  is  true 

then  the  name 

225 

★ 

will  be  preceeded  with  the  full  pathname 

226 

*/ 

227 

228 

char  *startstr  =  target; 

229 

int 

i; 

230 

231 

iff 

Longfmt  ) 

232 

( 

233 

♦target ++  =  (  IS  READONLY (infop)  )  ? 

'r ' 

:  ' . '  ; 

234 

*target++  =  (  IS  HIDDEN  (infop)  )  ? 

'h' 

:  ' . '  ; 

235 

*target++  =  (  IS  SYSTEM  (infop)  )  ? 

's' 

:  ' . '  ; 

236 

♦target ++  =  (  IS  SUBDIR  (infop)  )  ? 

'd' 

:  1 . '  ; 

237 

♦target ++  =  (  IS_DIRTY  (infop)  )  ? 

'm' 

:  ' . '  ; 

238 

239 

sprint f (target,  "  %61d  %2d/%02d/%02d 

%2d 

:%02d:%02d  -  ", 

240 

infop->fi  fsize. 

241 

C  MONTH (inf op) ,  C  DAY  (infop). 

C  YEAR (infop) -1900, 

242 

C_HR (infop) ,  C_MIN (infop) 

C_ 

SEC  (infop) 

243 

244 

while  (  *target  ) 

245 

target++; 

246 

I 

247 

248 

iff 

IS_SUBDIR (infop)  &&  graphics  ) 

249 

target  =  cpy(  target,  BOLDFACE  ); 

250 

251 

target  =  cpy  (  target,  pathname  ); 

252 

target  =  cptolower(  target,  infop->fi  name  ); 

253 

254 

iff 

IS_SUBDIR (infop)  &&  graphics  ) 

255 

target  =  cpy(  target,  ALL_OFF  ); 

256 

257 

return (  target  -  startstr  ); 

59 
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C  CHEST 


LISTING  EIGHT  (Listing  continued,  text  begins  on  page  14) 


258  } 

259 

260  /* - 

— 

- */ 

261 

262  static 

int 

add  entry (  infop,  dp,  path  ) 

263  FILE  INFO 

* infop  ; 

264  register  DIRECTORY  *dp 

265  char 

*path  ; 

266  { 

267 

/* 

Add  an  entry  to  the  DIRECTORY  structure.  Return  0  if 

268 

* 

it  was  added,  one  if  it  wasn't. 

269 

*/ 

270 

271 

char 

buf [128]  ; 

272 

register  int  len  ; 

273 

274 

/* 

275 

* 

If  we're  not  printing  hidden  directories  but  the  current 

276 

* 

directory  is  nonetheless  hidden,  return  immediately. 

277 

* 

Similarly,  return  if  the  directory  is  full. 

278 

*/ 

279 

280 

if  ( 

!dp->hidden  ss  (IS  HIDDEN  (infop)  ||  *infop->fi  name  ■='.')  ) 

281 

return  1; 

282 

283 

if  ( 

dp->maxdirs  <=  0  )  /*  No  more  room  in  dirv.  return  */ 

284 

return  0;  /*  error  status  */ 

285 

286 

/* 

287 

* 

Update  the  directory  count  or  the  file  count  as  appropriate 

288 

* 

return  inmeadialy  if  we're  looking  at  a  file  and  we  aren't 

289 

* 

supposed  to  list  file.  The  same  with  directories. 

290 

*/ 

291 

292 

if  i 

IS  SUBDIR  (infop)  ) 

293 

i 

294 

if(  dp->dirs  ) 

295 

dp->ndirs++  ; 

296 

else 

297 

return  1; 

298 

) 

299 

else 

300 

i 

301 

if(  dp->files  ) 

302 

dp->nfiles++  ; 

303 

else 

304 

return  1; 

305 

i 

306 

307 

/* 

308 

* 

Convert  the  FILE  INFO  structure  to  an  ascii  string  and  put 

309 

* 

it  into  buf.  Then  malloc  a  chunk  of  memory  the  correct  size 

310 

* 

copy  the  ascii  string  there,  and  put  the  malloced  memory 

311 

* 

into  dirv  at  the  correct  place. 

312 

*/ 

313 

314 

Longfmt  =  dp->longf; 

315 

316 

len 

=  dirtoa (  buf,  infop,  dp->graphics,  path  ) ; 

317 

318 

if  ( 

len  >  dp->width  ) 

319 

dp->width  =  len  ; 

320 

321 

iff 

*dp->lastdir  =  malloc (len  +  1)  ) 

322 

( 

323 

strcpy(  *dp->lastdir++,  buf  )  ; 

324 

325 

/*  Add  file  size  to  total.  Note  that  the  actual  amount 

326 

*  of  space  (#  of  clusters)  used  by  the  file  on  the 

327 

*  disk  is  used. 

328 

*/ 

329 

330 

dp->nbytes  +=  ROUND (  infop->fi  fsize.  Cluster  size  ); 

331 

332 

— dp->maxdirs; 

333 

return  1; 

334 

) 

335 

336 

fprintf (stderr, "Can't  get  memory  for  directory\n") ; 

337  return  0; 

338  } 

339 

340  /* - */ 

341 

342 

343  static  void  copy_path(  dest,  src  ) 

344  char  *dest,  *src; 

345  { 
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346  /*  Copy  only  the  pathname  part  of  the  file  spec  contained  in 

347  *  src  to  dest.  Path  names  longer  than  64  characters  are 

348  *  truncated  so  dest  must  be  at  least  64  characters  long. 

349  */ 

350 

351  register  char  *p,  * slash; 

352 

353  for(  p  =  slash  =  src  ;  *p  ;  p++  ) 

354  if  (  *p  ==  '/'  I  I  *p  —  'W  II  *p  ==  ) 

355  slash  =  p  +  1; 

356 

357  for(p  =  src;  p  <  slash  &&  p  -  src  <  64  ;  *dest++  =  *p++  ) 

358 

359 

360  *dest  =  0; 

361  } 

362 

363  /* - */ 

364 


365  static  void  clab(  dest,  src  ) 

366  register  char  *dest,  *src; 


367  { 

368  for(;  *src  ;  src++,  dest++  ) 

369  if (  *src  !=  1 . 1 ) 

370  *dest  =  *src  ; 

371  } 

372 

373  /* - */ 

374 

375  static  int  cmp(  ppl,  pp2  ) 

376  char  **ppl,  **pp2; 

377  { 

378  /*  Comparison  routine  needed  for  ssort  ()  */ 

379 

380  register  char  *pl  =  *ppl; 

381  register  char  *p2  =  *pp2; 

382 

383  if (  Longfmt  ) 

384  { 

385  /*  Skip  forward  to  the  that  will  preceede 

386  *  the  filename. 

387  */ 

388 

389  while (  *pl  &&  *pl  !=  ) 

390  pl++; 

391 

392  while (  *p2  &&  *p2  !=  ) 

393  p2++; 

394  } 

395 

396  return (  strcmp(pl,  p2)  ); 

397  } 

398 

399  /* - */ 

400 


401  DIRECTORY  *mk_dir(  size  ) 

402  register  unsigned  size; 


403  { 

404  /*  Make  a  DIRECTORY  with  the  indicated  number  of  dirv  entries. 

405  *  Note  that  since  one  dirv  entry  is  declared  as  part  of  the 

406  *  DIRECTORY  header,  we'll  actually  have  size+1  entries 

407  *  available,  though  the  last  one  is  never  used.  We  allocate 

408  *  it  so  that  we  can  terminate  the  list  with  a  null 

409  *  entry,  even  if  the  list  is  full. 

410  */ 

411 

412  register  DIRECTORY  *dp; 

413 

414 

415 

416 

417  if (  ! (  dp  =  (DIRECTORY  *)calloc(  (unsigned) 1, 

418  sizeof  (DIRECTORY)  +  (size  *  sizeof(char  *)))  )) 

419  return  0; 

420 

421  dp->maxdirs  -  size  ; 

422  dp->lastdir  =  (char  **)  dp->dirv; 

423  return  dp; 

424  } 

425 

426  /* - */ 

427 


428  del  dir (  dp  ) 

429  register  DIRECTORY  *dp; 

430  { 

431  /*  Delete  a  directory  made  with  a  previous  mk_dir  call. 

432  *  Note  that  all  the  strings  pointed  to  by  dirv  entries 

433  *  are  assumed  to  have  been  gotten  from  malloc  (this  is 

434  *  always  true  if  dir{)  is  used  to  fill  the  strings. 

(Continued  on  page  66) 
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435 

436 

437 

438 

439 

440 

441 

442 

443 

444 

445 

446 

447 

448 

449 

450 

451 

452 

453 

454 

455 

456 

457 

458 

459 

460 

461 

462 

463 

464 

465 

466 

467 

468 

469 

470 

471 

472 

473 

474 

475 

476 

477 

478 

479 

480 

481 

482 

483 

484 

485 

486 

487 

488 

489 

490 

491 

492 

493 

494 

495 

496 

497 

498 

499 

500 

501 

502 

503 

504 

505 

506 

507 

508 

509 

510 

511 

512 

513 

514 

515 

516 

517 

518 

519 

520 

521 

522 

523 


*/ 

register  char  **v; 

for(  v  =  (char  **)  dp->dirv;  v  <  dp->lastdir  ;  f ree (  *v++  )  ) 
free (  dp  ) ; 


/* - 

dir(  spec,  dp  ) 
char  *spec; 

DIRECTORY  *dp; 

{ 

/* 


- */ 


*/ 


Get  a  directory  for  the  indicated  spec.  DOS  wildcards  are 
permitted.  If  the  DIRECTORY  pointed  to  by  dp  already  has 
entries  in  it,  new  ones  will  be  appended  onto  the  existing 
ones.  If  *spec  is  null,  no  files  will  be  gotten,  this  is 
useful  if  all  you  want  is  the  volume  label. 

Note  that  the  DTA  is  not  modified  by  this  routine.  It 
sets  the  DTA  to  its  own  address,  but  then  restores  the 
DTA  before  returning. 


REGS 

FILE_INFO 

char 

char 

short 

unsigned 


regs 

info 

path [80]  . 

**firstdir. 
seg,  off 


se  c_per_c  luster, 

bytes_per_sector, 

garbage; 


gregs (  &regs  )  ; 

DOSCALL (  GETDTA,  regs  ); 

seg  =  regs.x.es  ; 
off  =  regs.x.bx  ; 

regs.x.dx  =  (word)  &info; 
DOSCALL (  SETDTA,  regs  ); 


/*  Needed  for  DOS  calls  */ 
/*  DOS  puts  dirs  here  */ 
/*  place  to  put  path  */ 
/*  Used  for  sorting  */ 
/*  Segment  and  offset  of  */ 
/*  original  DTA  */ 
/*  Used  to  compute  number  of  */ 
/*  bytes  in  a  cluster  */ 


/*  Get  the  original  DTA  */ 


/*  remember  it  in  setroff  */ 


/*  Change  the  Disk  Transfer  Addr  */ 
/*  to  point  at  info  structure  */ 


V 


Find  the  number  of  bytes/cluster  on  the  indicated 
disk  drive  (or  on  the  current  drive  if  none  is 
specified. 


if(  !diskinfo(  (!*spec| |spec[l] !  =  ' : ')  ?  0  :  (toupper (*spec) - 1 A' ) +1, 
&sec_per_cluster,  &bytes_per_sector,  sgarbage,  figarbage) ) 
fprintf (stderr, "dir:  Can't  access  indicated  disk\n"); 

Cluster_size  =  sec_per_cluster  *  bytes_per_secrtor  ; 

/*  If  a  volume  label  is  requested,  get  it  and  copy  it  into 

*  dp->vol_lab.  Any  imbedded  ' . ' s  are  stripped  by  clab. 

*  If  no  volume  label  is  present,  the  string  is  nulled. 

*/ 

if(  dp->label  ) 

{ 

*dp->vol_label  =0; 

if(  spec [1]  ! =  ) 

strcpy(  path,  "/*.*"  ); 

else 


{ 


*path  =  *spec  ; 

strcpy(  path+1,  ); 


if  (  ! f ind_f irst (path,  LABEL,  &regs)  ) 

clab(  dp->vol_label,  info.fi_name  ) ; 


Now  get  the  directories: 


if (  dp->exp  &&  Ihaswild (spec)  ) 

spec  =  fixup_name (  spec,  &regs,  &info  ) ; 

copy_path(  path,  dp->path  ?  spec  :  ""  ); 


(Continued  on  page  68) 
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524 

firstdir  =  dp->lastdir; 

525 

526 

/*  Now  go  look  for  the  file: 

527 

*/ 

528 

529 

if (  ifind  first (spec,  ATTRIBUTES,  Sregs)  ) 

530 

if (  !add  entry (&info,  dp,  path)  ) 

531 

goto  abort; 

532 

533 

if (  haswild (spec)  ) 

534 

while  (  Ifind  next (  &regs  )  ) 

535 

if (  ladd  entry (&info,  dp,  path)  ) 

536 

goto  abort; 

537 

538 

if  (  dp->sort  ) 

539 

ssort  (  (char  *) firstdir,  dp->lastdir  -  firstdir. 

540 

sizeof (char*) ,  cmp) ; 

541 

542  abort 

543 

regs.x.ds  =  seg  ;  /*  Restore  the  original  disk  */ 

544 

regs.x.dx  =  off  ;  /*  transfer  address.  */ 

545 

DOSCALL (  SETDTA,  regs  ) : 

546  } 

End  Listing  Eight 

LISTING  NINE 

1  # include  <stdio.h> 

2  # include  <ctype.h> 

4  #define 

MAXARGC  (unsigned) 128 

5  #define  isquote(c)  ((c)==""  ||  (c)  — ' \ '  * ) 

7  extern 

char  *getenv (  char*  ) ; 

8  extern 

char  *malloc(  unsigned  ); 

11 

12  static 

char  *nextarg(  pp  ) 

13  char 

*  *pp; 

14  ( 

15 

register  char  *p; 

16 

char  *start; 

17 

register  int  term; 

18 

19 

if  (  !*(p  -  *pp)  ) 

20 

return  (char  *)  0; 

21 

22 

while (  isspace(*p)  ) 

23 

P++; 

24 

25 

if (  isquote(*p)  )  /*  Can't  use  a  conditional  because  */ 

26 

term  =  *p++;  /*  of  order  of  evaluation  problems  */ 

27 

else 

28 

term  =  '  ' ; 

29 

30 

for(  start  =  p;  *p  ;  p++) 

31 

t 

32 

if(  *p  ==  term  &&  *(p-l)  !=  'W  ) 

33 

i 

34 

*p++  =  ' \0 ' ; 

35 

break; 

36 

) 

37 

t 

38 

39 

*pp  =  p; 

40 

41 

return  start; 

42  ) 

43 

45 

46  int 

reargv(  argcp,  argvp  ) 

47  char 

***argvp; 

48  int 

*argcp; 

49  { 

50 

register  int  argc  =  0  ; 

51 

register  int  maxc  =  MAXARGC  ; 

52 

char  **argv,  **start  argv  ; 

53 

char  *env,  *p  ; 

54 

55 

if (  ! (env  =  getenv ("CMDLINE") )  | |  !*env  ) 

56 

return  0; 

57 

58 

if(  ! (p  -  malloc(  strlen (env) +1  ))) 

59 

return  0; 

(Continued  on  page  70) 
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60 

61 

if(  ! (argv  =  (char  **)  malloc (  MAXARGC  *  sizeof(char 

*))  )) 

62 

return  0; 

63 

64 

strcpy (p,  env) ; 

65 

start  argv  =  argv; 

66 

for(  maxc=MAXARGC;  — maxc  >=  0  &&  (*argv++  =  nextarg (&p) ) ;  argc++) 

67 

; 

68 

69 

if  (  maxc  <  0  ) 

70 

fprintf  (stderr,  "Command  line  truncated\n") ; 

71 

72 

*argcp  =  argc; 

73 

*argvp  -  start  argv; 

74 

return  1; 

75  ) 

76 

77  /* - 

78 

79  #ifdef 

80 

DEBUG 

- */ 

81  main(  argc,  argv  ) 

82  char 

83  { 

**argv; 

84 

printf ("Original  command  line  is:  |"); 

85 

while (  — argc  >=  0  ) 

86 

printf ("%s | ",  *argv++  ); 

87 

88 

if (  !reargv(  &argc,  &argv  )  ) 

89 

printf ("\nCMDLINE  not  present \n" ) ; 

90 

else 

91 

( 

92 

printf ("New  argc  =  %d\n",  argc  ); 

93 

printf ("NnModified  command  line  is:  |") ; 

94 

95 

while  (  — argc  >=  0  ) 

96 

printf ("%s | ",  *argv++  ); 

97 

98 

99 

100  } 

101 

102  #endif 

printf  ("\n") ; 

1 

End  Listing  (Vine 

LISTING  TEN 

i  /* 

SSORT.C  Works  just  like  qsort()  except  that  a 

shell 

2  * 

sort,  rather  than  a  quick  sort,  is  used.  This 

3  * 

is  more  efficient  than  quicksort  for  small  numbers  of 

elements 

4  * 

and  it's  not  recursive  so  will  use  much  less  stack  space. 

6  * 

Copyright  (C)  1985,  Allen  I.  Holub.  All  rights  reserved 

7  */ 

8 

9  void 

ssort (  base,  nel,  width,  cmp  ) 

10  char 

*base; 

11  int 

nel,  width; 

12  int 

13  { 

(*cmp)  () ; 

14 

register  int  i,  j; 

15 

int  gap,  k,  tmp  ; 

16 

char  *pl,  *p2; 

17 

18 

for  (  gap  =  nel  »1  ;  gap  >  0  ;  gap  »-l  ) 

19 

for(  i  =  gap;  i  <  nel;  i++  ) 

20 

for(  j  =  i-gap;  j  >■=  0  ;  j  -=  gap  ) 

21 

( 

22 

pl  =  base  +  (  j  *  width) 

23 

p2  =  base  +  ( ( j+gap)  *  width) 

24 

25 

if(  (*cmp) (  pl,  p2  )  <=  0  ) 

26 

break; 

27 

28 

for(  k  =  width;  — k  >=  0  ;) 

29 

< 

30 

tmp  =  *pl ; 

31 

*pl++  =  *p2; 

32 

*p2++  ■=  tmp; 

33 

1 

34 

1 

35  } 

End  Listings 
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LISTING  ONE  (Text  begins  on  page  34) 

/*  GLOBAL. H 

/* 

* 

*  ctype 

h  may  be  needed  for 

an  isspace  used  in  read.c 
don't! 

*  Global  include  file  for  the  Variable  Metric  Minimizer  program. 

*  some 

systems  need  it,  some 

* 

*  check 

your  math.h  for  fabs 

and  atof  declarations! 

*  (c)  Copyright  1985,  Billybob  Software.  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 

*/ 

*/ 

♦endif 

♦define  C80 

double 

dot()  ; 

/* 

*  remove  the  above  line  if  you  are  not  using  C/80 

struct 

bound 

int  fl  ; 

*/ 

double  up  ; 
double  lo  ; 

♦ifdef  C80 

}; 

double  mi  ; 

/* 

*  required  for  the  Software  Toolworks  C/80  Version  3.0  compiler 
*/ 

struct 

xydata 

double  x  ; 

♦define  double  float 

double  y  ; 

♦include  "fprintf.h" 

♦include  "scanf.h" 

); 

♦define 

BOUND 

struct  bound 

/* 

♦define 

DATA 

struct  xydata 

*  the  following  is  the  <math.h>  for  C/80 

♦define 

VECMAX 

10 

*/ 

♦define 

MATMAX 

VECMAX* VECMAX 

♦define 

NEPS 

2 

float  sin()  ,  cos()  ,  atan()  ,  sqrt()  ,  exp()  , 

♦define 

STDES 

0 

pow()  ,  powlOO  ,  ln()  ,  log()  ,  fabs()  ,  atof() 

♦define 

DFP 

1 

♦define 

BFGS 

2 

♦  else 

♦define 

ALLDONE 

-1 

♦define 

NEGEDM 

-3000 

/* 

♦define 

BADMIN 

-2000 

*  other  compilers 

♦define 

BADLS 

-1000 

*/ 

♦define 

MAXITERS 

0 

♦define 

OK 

0 

♦include  <stdio.h> 

♦define 

EDM1 

1000 

♦include  <math.h> 

♦define 

EDM2 

2000 

♦include  <ctype.h> 

♦define 

TOOSML 

3000 

End  Listing  One 
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LISTING  TWO  (Listing  continued,  text  begins  on  page  24) 


/*  VMM.C 
* 

*  The  main  driver  routine,  function  library  routine 

*  and  all  library  functions  for  vmm. 

*  (c)  Copyright  1985,  Billybob  Software.  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 

*/ 

# include "global. h" 

#define  DMAX  50  /*  Size  of  experimental  data  array  */ 

#define  NFUN  3  /*  Num  of  functions  in  function  library  */ 

/**★★*★*★**★**★★★★★★★*★★★★*******★★★★******★*★★******★★*★***★***★★**★*★*★/ 

main  () 

{ 


static 

int 

nparam  ; 

/*  number  of  parameters 

*/ 

static 

double 

const  [VECMAX]  ; 

/*  constants  used  in  function 

*/ 

static 

double 

param  [VECMAX]  ; 

/*  parameters  to  be  found 

*/ 

static 

double 

dstep  [VECMAX]  ; 

/*  step  sizes  for  derivatives 

*/ 

static 

double 

epsilon [VECMAX] 

;/*  stopping  criteria 

*/ 

static 

BOUND 

limit  [VECMAX]  ; 

/*  limits  if  constrained 

*/ 

static 

char 

‘pname  [VECMAX] 

?/*  parameter  names 

*/ 

static 

double 

gO  ; 

/*  expected  value  of  minimum 

*/ 

static 

int 

debug  ; 

/*  debug  level,  0  if  off 

*/ 

static 

int 

itermin  ; 

/*  minimum  number  of  iterations 

*/ 

static 

int 

iterlim  ; 

/*  maximum  number  of  iterations 

*/ 

static 

int 

nreset  ; 

/*  reset  y  after  this  many  iters 

*/ 

static 

DATA 

exp [DMAX]  ; 

/*  xy  experimental  data 

*/ 

static 

int 

npoints  ; 

/*  number  of  data  points 

*/ 

static 

double 

*  (*fun)  ()  ; 

/*  ptr  to  function  to  minimize 

*/ 

static 

int 

iters  ; 

/*  number  of  iterations  it  took 

*/ 

static 

int 

retcode  ; 

/*  return  code  from  minimization 

*/ 

static 

double 

gmin  ; 

/*  the  value  at  the  minimum 

*/ 

static 

int 

method  ; 

/*  method  used  to  update  y 

*/ 

static 

int 

control  ; 

int 

i  *  j  ; 

for  (  i= 

=1  ;  ;  ++i  ) 

{ 

raz  (  &nparam  ,  fiitermin  ,  Siterlim  ,  &nreset  ,  Sdebug  , 

limit  ,  dstep  ,  param  ,  &g0  ,  epsilon  ,  Smethod  )  ; 

if (  (control  =  reader  (  &fun  ,  const  ,  &nparam  ,  param  , 

limit  ,  dstep  ,  pname  ,  epsilon  ,  & itermin  , 
& iterlim  ,  &nreset  ,  &g0  ,  sdebug  ,  exp  , 
Snpoints  ,  DMAX  ,  &method) )  ==  ALLDONE  ) 

break  ; 

if  (  control  ) 

continue  ; 

if  (  dfault  (  nparam  ,  Sitermin  ,  fiiterlim  ,  Snreset  , 
epsilon  ,  limit  ,  dstep  ,  debug  )  ) 
continue  ; 

ret code  =  minim  (  nparam  ,  fun  ,  param  ,  dstep  ,  limit  , 

gO  ,  itermin  ,  iterlim  ,  epsilon  ,  &gmin  , 

& iters  ,  debug  ,  nreset  ,  exp  ,  npoints  , 
const  ,  method  )  ; 

print f (" \t *********************** ****\n" )  ; 
printf ("\t*  results  from  dataset  %2d  *\n",  i  )  ; 
printf ("\t***************************\n")  ; 
printf ("stopped  after  %ld  iterations,  ",  iters  )  ; 

switch  (  retcode  ) 

( 

case  NEGEDM  :  printf ("negat ive  e.d.m.Xn")  ;  break  ; 

case  BADMIN  :  printf ("new  min  >  last  min\n")  ;  break  ; 

case  BADLS  :  printf ("line  search  failed\n")  ;  break  ; 

case  MAXITERS:  print f ( "maximum  iterations'^") ;  break  ; 
case  EDM1  :  printf ("e .d .m.  within  tol.\n")  ;  break  ; 

case  EDM2  :  printf ("e.d.m.  within  tol.\n")  ;  break  ; 

case  TOOSML  :  printf ("change  too  small\n")  ;  break  ; 

default  :  printf ("unknown  reason !!! \n")  ;  break  ; 

} 

printf ("value  of  the  minimum  was  %11.4e\n",  gmin  )  ; 
printf ("parameter  values  at  minimum: \n")  ; 


Dr.  Dobb's  Journal,  March  1986 

198 


76 


_ METRIC  MINIMIZER 

LISTING  TWO  (Listing  continued,  text  begins  on  page  24) 


) 


} 


for  (j=0  ;  j<nparam  ;  ++j) 

printf("%15s  %11.4e\n"  ,  pname[j]  ,  paramtj]); 

print f ( n******************************* ************** \n" )  ; 


/************************************************************************ 

*  Function  library.  Note  that  NFUN  is  ^defined  at  the  top  of  this 

*  module . 

*/ 


funlib 

(  funname  ,  fun  , 

,  np  ,  nc  ,  pname  ) 

char 

funname [ ]  ; 

/* 

name  of  function  to  be  minimized 

*/ 

int 

*fun  ; 

/* 

address  of  function  (non-portable) 

*/ 

int 

*np  ; 

/* 

number  of  parameters  in  the  function 

*/ 

int 

*nc  ; 

/* 

number  of  constants  in  the  function 

*/ 

char 

*pname [ ]  ; 

/* 

parameter  names  vector 

*/ 

{ 

/* 

*  use  funname  to  return  fun  and  np,  nc  from  a  list 

*  for  each  new  function  in  the  library,  you  must: 

*  (1)  declare  the  function  "double"  and  link  it  in  the  load  module 

*  (2)  declare  the  function  below  under  "functions  available" 

*  (3)  add  an  entry  in  the  function  table, including  parameter  names 

*  (4)  add  an  entry  in  the  switch  table  in  the  code 

*  (5)  update  the  value  of  NFUN 

* 

*  Available  functions  are: 

*/ 

double  cohen  ()  ; 
double  sinus  ()  ; 
double  rosen()  ; 


/* 

*  function  table 
*/ 


static  struct 


{ 


char 

*name  ; 

/* 

function  name  in  funname  call 

*/ 

int 

nnpp  ; 

/* 

number 

of  parameters  in  the  function 

*/ 

int 

nncc  ; 

/* 

number 

of  constants  in  the  function 

*/ 

char 

*ppnn [VECMAX] ; 

/*  list  of 

names  for  the  parameters 

*/ 

}  fctlib [NFUN]  =  { 


/* 

0 

*/ 

{  "cohen" 

2, 

0  , 

"alpha" 

,  "beta" 

) 

/* 

1 

*/ 

{  "sine" 

4, 

0  , 

"P0"  , 

"PI" 

"P2"  , 

"P3" 

) 

/* 

2 

*/ 

{  "rosen" 

10, 

5 

"xl"  , 

"x2" 

/  "x3"  , 

"x4" 

"x5 

"x6" 


"x7"  ,  "x8"  ,  "x9" 


"xlO" 


int  j,  k; 

for  (  j=0  ;  j<NFUN  ;  ++j  ) 

if  (  !  strcmp(  funname  ,  fctlib [ j] .name  )  ) 
break  ; 

if  ( j==NFUN) 

return (  1  )  ; 


*np  =  fctlib[ j] .nnpp  ; 

*nc  =  fctlibj j] .nncc  ; 

for  (k=0  ;  k  <  *np  ;  ++k) 

pname[k]  =  fctlib [ j] .ppnn [k]  ; 

switch (  j  ) 

{ 

case  0  :  *fun  =  cohen  ;  break  ; 

case  1  :  *fun  =  sinus  ;  break  ; 

case  2  :  *fun  =  rosen  ;  break  ; 

} 

return (  0  )  ; 

} 


/************************************************** *********** ***********/ 
double  cohen  (  const  ,  xx  ,  data  ,  npoints  ,  user  ) 

double  const []  ;  /*  vector  of  constants  used  by  this  fen  */ 

double  xx []  ;  /*  the  current  values  of  the  vector  x  */ 
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LISTING  TWO  (Listing  continued;  text  begins  on  page  24) 


DATA 

data[]  ; 

/*  dummy 

*/ 

int 

npoints  ; 

/*  dummy 

*/ 

int 

/ 

user  ; 

/*  dummy,  reserved  for  each  user! 

*/ 

( 

/* 

*  computes  the  function  to  be  minimized 

★ 

*  this  is  the  test  function  given  in  Cohen,  page  280 

*  note  that  there  are  no  constants  for  this  fen  — 

*  the  vector  const  is  included  for  compatability  with  other  fens 

* 

*  note  program  calls  function  with  user  =  0 
*/ 

double  tl  ,  t2  ,  t3  ,  t4  ; 

tl  =  (xx[l]  -  xx [0] *xx [0] )  ; 
t2  =  tl  *  tl  ; 

t3  =  (xx [0]  *  (1.0  -  xx [ 1 ] )  +  1.0)  ; 
t4  =  t3  *  t3  ; 
return  (  t2  +  t4  )  ; 

) 


double 

double 

double 

DATA 

int 

int 

( 


sinus  (  const 
const  [  ]  ; 
xx[]  ; 
dataf]  ; 
npoints  ; 
user  ; 


xx  ,  data  ,  npoints  ,  user  ) 

/*  vector  of  constants  for  this  fen 
/*  parameter  vector 
/*  data  from  file 
/*  number  of  data  points 
/*  user  parameter 


/* 

*  extract  parameters  for  polynomial  fit  to  sine  function 
*/ 


double  tl  ,  t2  ,  t3  ,  t4  ; 
int  i; 


for  (  i=0  ,  t4  =  0.0  ;  i<npoints  ;  i++  ) 

( 

tl  =  data[i].x  *  data[i].x  ; 
t2  =  data [i] .x  * 

(xx [0]  +  tl*(xx[l]  +  tl* (xx [2]  +  tl*xx [3] )  )) 
t3  =  (data[i].y  -  t2) /data [i] .y  ; 
t4  +=  t3  *  t3  ; 

} 


*/ 

*/ 

*/ 

*/ 

*/ 


return (  t4  /= 


(double)  (npoints-4) 


)  ; 


double 

rosen  (  const  , 

,  XX 

,  data  ,  npoints  ,  user  ) 

double 

const []  ; 

/* 

vector  of  constants  used  by  this  fen 

*/ 

double 

xx[)  ; 

/* 

the  current  values  of  the  vector  x 

*/ 

DATA 

data[]  ; 

/* 

dummy 

*/ 

int 

npoints  ; 

/* 

dummy 

*/ 

int 

user  ; 

/* 

dummy,  reserved  for  each  user! 

*/ 

/* 

*  Rosenbrock's  test  function 
*/ 

double  tl  ,  t2  ,  t3  ; 
int  1  ,  m  ; 

for  (  1=0  ,  m=0  ,  t3  =0.0  ;  1<10  ;  1  +=  2  ,  ++m  ) 

( 

tl  =  xx [ 1 ]  ; 
t2  =  xx [1+1]  ; 

t3  +=  const [m] * (t2-tl*tl) * (t2-tl*tl)  +  (1 . 0-tl) *  (1 . 0-tl)  ; 

) 

return (  t3  )  ; 

I  End  Listing  Two 

LISTING  THREE 

/*  MINIM. C 
* 

*  The  main  minimization  routine 

*  (c)  Copyright  1985,  Billybob4 Software .  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 

*/ 


#include  "global. h" 
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LISTING  THREE  (Listing  continued,  text  begins  on  page  24) 

/**********************************************************************H 

*  *  *  *  j 

minim 

(  n  ,  fun  ,  xextern  ,  xstep  ,  xlim  ,  gO  ,  itermin  ,  iterlim  ,  epsilon  , 

gmin  , 

iters 

debug  f  nreset  ,  data  ,  npoints  ,  const  ,  method 

int 

n  ; 

/*  number  of  parameters  in  the  fit 

*/ 

double 

<*fun) 

()  ; 

/*  pointer  to  the  function  to  minimize 

*/ 

double 

xextern  [  ]  ; 

/*  vector  containing  the  starting  values  of 

the  parameters;  returns  values  at  minimum 

*/ 

double 

xstep [ 

]  ; 

/*  step  sizes  on  parameters  for  deriv  calcs 

*/ 

BOUND 

xlim  [  ] 

; 

/*  limits  on  the  vector  x 

*/ 

double 

go  ; 

/*  expected  value  of  the  minimum  of  the  fen 

*/ 

int 

itermin  ; 

/*  minimum  number  of  iterations 

*/ 

int 

iterlim  ; 

/*  limit  on  the  number  of  iterations 

*/ 

double 

epsilon [ ]  ; 

/*  iteration  control  parameters 

*/ 

double 

*gmin 

; 

/*  value  of  minimum  for  returned  vector  x 

*/ 

int 

*iters 

; 

/*  number  of  iterations  to  converge 

*/ 

int 

debug 

/*  flag  =  0  for  no  print,  >0  for  debug  print 

*/ 

int 

nreset 

; 

/*  reset  limit  for  the  y  matrix 

*/ 

DATA 

data [ ] 

; 

/*  the  data 

*/ 

int 

npoints  ; 

/*  number  of  data  points 

*/ 

double 

const [ ]  ; 

/*  vector  of  constants  required  by  fen 

*/ 

int 

{ 

method 

; 

/*  update  method  for  the  matrix  y 

*/ 

/* 

*  variable  metric  minimization  algorithm 

*  Reference 

(using  DFP  method)  is:  Numerical  Analysis 

* 

A.M.  Cohen  et .  al . 

* 

Halstead  Press 

* 

John  Wiley  and  Sons 

* 

1973 

* 

pages  276-280 

*  See 

*/ 

also  original  papers  by  Fletcher  and  Powell 

int 

i  -  j 

rc  ; 

static 

int 

ycount  ;  /*  counter  for  resetting  the  Y  matrix 

*/ 

static 

double 

y [MATMAX ]  ;  /*  the  Y  matrix 

*/ 

static 

double 

a(MATMAX)  ;  /*  the  A  and  B  matrices  are  calculated 

to  */ 

static 

double 

b [MATMAX]  ;  /*  update  the  Y  matrix  at  each  iteration  */ 

static 

double 

xintern [VECMAX] ; /*  parameters  in  internal  coordinates  */ 

static 

double 

zint [ VECMAX ]  ;  /*  gradients  in  internal  coordinates  */ 

static 

double 

znewi [VECMAX]  ;  /*  same  for  the  next  iteration 

*/ 

static 

double 

sigma [VECMAX]  ;  /*  changes  vector 

*/ 

static 

double 

s [VECMAX]  ;  /*  changes  direction  vector 

*/ 

static 

double 

xi [VECMAX]  ;  /*  change  in  gradient  vector  between  */ 

*  iterations 

*/ 

static 

double 

xold [VECMAX)  ;  /*  holds  previous  values  of  x 

*/ 

static 

double 

alpha  ; 

*/ 

static 

double 

g  ;  /*  value  of  fen  for  a  given  vector 

X  */ 

static 

double 

gnew  ;  /*  likewise  for  the  next  iteration 

*/ 

double 

dot  () 

*/ 

/* 

*  get 

started 

g  =  (*fun)  (  const  ,  xextern  ,  data  ,  npoints  ,  0  )  ; 

gozinta(  n  ,  xintern 

xextern  ,  xlim  )  ; 

derivs 

(  n  ,  fun  ,  xintern  ,  xstep  ,  xlim  ,  zint  ,  data  , 

/* 

*  main 

loop 

npoints  ,  const  ,  debug) ; 

*/ 

for  (  i 

=  1  , 

ycount 

nreset  ;  i  <=  iterlim  ;  ++i  ,  ++ycount  ) 

if  (ycount  == 

nreset) 

reset  ( 

n  ,  y  )  ; 

ycount 

=  0  ; 

if  (debug) 

print f ( 

" \t \t  +  +++  +  +  +  ++++  +  +  +++  +  +  +  +  +  +  \n")  ; 

print f ( 

"\t\t+  Begin  iteration  %2d  +\n",  i  )  ; 
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printf  ("\t\t++++++++++++++4+++++++\n")  ; 
printf ("external  parameter  values  are:\n")  ; 
vout (  n  ,  xextern  )  ; 

printf ("internal  parameter  values  are:\n")  ; 
vout (  n  ,  xintern  )  ; 

printf ("internal  gradient  vector  is:\n")  ; 
vout (  n  ,  zint  )  ; 

printf ("approximate  inverse  hessian  matrix  is:\n")  ; 
mout (  n  ,  y  )  ; 

printf ("the  current  minimum  is  - >%11.4e< - \n",  g  )  ; 

} 

matvec  (  n  ,  y  ,  zint  ,  s  )  ; 
for  ( j =0  ;  j<n  ;  ++j) 

( 

xold[j]  =  xintern [j]  ; 

s[j]  *=  -1.0  ; 

} 

if  (debug>l) 

( 

print f ( "vector  s  is:\n");  vout (  n  ,  s  )  ; 

) 

/* 

*  do  line  search  and  quit  if  it  fails 

*  line  search  was  successful  if  getalpha  returns  OK  (  zero  ) 
*/ 

if  (  rc  =  getalpha  (  n  ,  fun  ,  xintern  ,  xstep  ,  xlim  ,  zint  , 
s  ,  g  ,g0  ,  Salpha  ,  debug  ,  data  ,  npoints  ,  const  )  ) 
break  ; 

/* 

*  update  parameters 
*/ 

for  (j=0  ;  j<n  ;  ++j) 

{ 

sigma [j]  =  alpha  *  s [ j ]  ; 
xintern (j]  +=  sigma (j); 

} 

if  (debug>l) 

( 

printf ("vector  sigma  is:\n")  ;  vout (  n  ,  sigma  )  ; 

} 

/* 

*  get  values  for  next  iteration 
*/ 

gozouta  (  n  ,  xintern  ,  xextern  ,  xlim  ) ; 

gnew  =  (*fun)  (  const  ,  xextern  ,  data  ,  npoints  ,  0  )  ; 

derivs  (n  ,  fun  ,  xintern  ,  xstep  ,  xlim  ,  znewi  , 

data  ,  npoints  ,  const  ,  debug  )  ; 

for  (j=0  ;  j<n  ;  ++j) 

xi [ j )  =  znewi[j]  -  zint[j]  ; 

if  (debug>l) 

( 

print f ("orthogonality  satisfied  to  %11.4e\n", 
dot  (  n  ,  znewi  ,  sigma  )  )  ; 
printf ("vector  xi  is:\n")  ; 
vout (  n  ,  xi  )  ; 

} 

/* 

*  decide  whether  to  continue  or  not 

*  continue  if  decide  returns  OK  (  zero  ) 

*/ 

if  (  rc  =  decide (  g  ,  gnew  ,  n  ,  znewi  ,  sigma  ,  y  , 

epsilon  ,  itermin  ,  i  ,  debug  )  ) 

break  ; 

/* 

*  update  all  other  quantities  for  the  next  pass 
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*  three  methods  available: 

*  steepest  descent  (slowest  and  included  only  for  completeness) 

*  Davidon  Fletcher  Powell  (default,  empirically  the  favorite) 

*  Broyden  Fletcher  Goldfarb  Shanno  (thought  to  be  better  by 

*  some) 

*  The  method  is  selected  by  keyword  on  input. 

*/ 


if  (  method  —  STDES  ) 

;  /*  nothing  to  do,  y  is  not  updated  */ 


else  if  (  method  ==  DFP  ) 

{ 

dfpa  (  n  ,  sigma  ,  xi 

dfpb  (  n  ,  y  ,  xi 

gety  (  n  ,  a  ,  b 

} 

else  if  (  method  ==  BFGS  ) 

{ 

bfgsa  (  n  ,  y  ,  sigma 
bfgsb  (  n  ,  y  ,  sigma 
gety  (  n  ,  a  ,  b 


a  ,  debug  )  ; 

b  ,  debug  )  ; 
y  ,  debug  )  ; 


xi  ,  a  ,  debug  ) 

xi  ,  b  ,  debug  ) 

y  ,  debug  ) 


for  ( j=0  ;  j<n  ;  ++j) 

zint [ j ]  =  znewi ( j )  ; 


gozouta  (  n  ,  xintern  ,  xextern  ,  xlim  )  ; 
g  =  gnew  ; 

/* 

*  all  done  with  this  pass 
*/ 

} 


/* 

*  outside  of  the  main  loop  here 
*/ 


♦iters  =  (  i  >  iterlim  )  ?  iterlim  :  i  ; 


/* 

*  first  handle  the  case  of  abnormal  exits 

*  these  have  returned  rc  negative  above,  from  either  getalpha  or  decide 
*/ 


if  (  rc  <  0  ) 

{ 

for  (j=0;  j<n;  ++j) 

xintern [j]  =  xold[j]  ; 
gozouta  (  n  ,  xintern  ,  xextern  ,  xlim  )  ; 

*gmin  =  g  ; 

} 

else 

{ 

/* 

*  regular  exit  and  fall  through  These  represent  positive  or 

*  zero  values  of  rc;  zero  means  max  iterations. 

*/ 

gozouta  (  n  ,  xintern  ,  xextern  ,  xlim  )  ; 

*gmin  =  gnew  ; 

} 

if  (debug) 

{ 

print f  ( "\t\t +  +++  +  +  +  +++++  +  +++  +  +  +  ++++  + \n")  ; 
printf ("\t\t+  exiting  minimization  +\n")  ; 
printf  ("\t\t  +  +++  +  +  +  +++  +  ++++++  +  +  +++  +  +  \n")  ; 
printf ("\tnumber  of  iterations  was:  %lld\n", *iters)  ; 
printf ("\t  return  code  is:  %lld\n",rc)  ; 

printf ("\t  minimum  is:  %11.4e\n",  *gmin)  ; 

printf ("best  parameter  values :\n")  ; 
vout (  n  ,  xextern  )  ; 

printf ("last  internal  gradient  vector :\n")  ; 
vout (  n  ,  znewi  )  ; 

) 

return  (  rc  )  ;  End  Listing  Three 

Listings  to  be  continued  next  month 
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LISTING  ONE  (Text  begins  on  page  36) 


{task  #1:  keyboard  ->  serial  out 
task  #2:  serial  in  ->  video  out 
control-C  will  abort:  program} 
program  main; 
const  TASKS=2; 

STACKSIZE=70; 

{next  7  constants  are  needed  for  the  Kaypro} 
KDATA=5; 

KSTAT=7; 

BAUDP=0; 

SDATA=4; 

SSTAT=6; 

RMASK-1; 

TMASK=4; 


CC=3; 

type  stack  =  array [0. .STACKSIZE]  of  integer; 
tasknum  =  -1.. TASKS; 

var  spO, spl, sp2:  integer; {when  zero,  task  not  initialized} 

oldn:  tasknum; 
nextn:  tasknum; 

Procedure  defer;  forward; 
procedure  exit; 

begin 

writeln ( 'TASK  #',oldn, '  terminated.'); 

oldn:— 1; 

defer; 

end; 

function  keyimbyte; 
begin 
repeat 
defer; 

until  (RMASK  =  (RMASK  and  port [KSTAT] ) ) ; 
keyin:=  port [KDATA] ; 
end; 

procedure  videout (b:byte) ; 
begin 
bdos  (6,b) ; 
end; 

function  serin:  byte; 
begin 
repeat 
defer; 

until  (RMASK  =  (RMASK  and  port [SSTAT] ) ) ; 

serin:=  port[SDATA); 

end; 

procedure  serout (b:byte) ; 
begin 
repeat 
defer; 

until  (TMASK  =  (TMASK  and  port  [ SSTAT ])) ; 

port [SD AT A] :=b; 

end; 

Procedure  taskl; 

var  mystack:  stack; 


key:  byte; 
begin 

stackptr :  =addr  (mystack  [STACKSIZE] ) ; 
repeat 

key:=keyin; 
if  key=CC  then  exit 
else  serout (key) ; 
until  false; {forever} 
exit; 
end; 

Procedure  task 2; 
var  mystack:  stack; 

begin 

stackptr: =addr (mystack [STACKSIZE] ) ; 
repeat 

videout (serin) ; 
until  false { forever] ; 
exit; 
end; 

procedure  initall; 
var  i:  integer; 

Begin 
spl 2-0; 
sp2:=0; 
oldn:=0; 

{initialize  Kaypro 's  SIO} 
port [BAUDP] : =14; {9600  Baud} 
port  [SSTAT] :=24; 
port  [SSTAT]  :=4; 
port  [SSTAT]  :=68; 
port  [SSTAT]  : -Im¬ 
port  [SSTAT]  :=0; 
port [SSTAT] :=3; 
port [SSTAT] :=193; 
port [SSTAT] :=5; 
port [SSTAT] :=234; 
end; 

Procedure  schedule; 
begin 

if  oldn=TASKS  then  nextn: =1 

else  nextn: =oldn+l; 

end; 

procedure  defer; 
var  sp:  integer; 
begin 

case  oldn  of 

0:  sp0:=stackptr; 

1:  spl:=stackptr; 

2:  sp2:=stackptr; 
end {case} ; 
schedule; 
oldn:=nextn; 
case  nextn  of 
0:  sp:=sp0; 

1:  sp:=spl; 
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2:  sp:=sp2; 
end {case} ; 

if  spoO  {initialized} 
then  begin 
stackptr:=sp; 
end 

else  {not  initialized} 
begin 

writeln ('Starting  task  #',  nextn); 
case  nextn  of 
1:  taskl; 

2:  task2; 
end { case} ; 
end; 
end {defer}; 
begin{main} 
initall; 

writeln ( 'Multitasking  version  of  simple  terminal  program'); 

writeln ( 'Control-C  will  terminate  it'); 

writeln; 

defer; 

writeln ( 'Main:  done'); 

end.  ...  ^ 

End  Listing  One 


LISTING  TWO 


{task  #1:  keyboard  ->  fifol 
task  #2:  fifol  ->  filter  ->  fifo2 

task  #3:  fifo2  ->  slow  display  } 

program  main; 
const  TASKS=3; 

STACKSIZE=20; 

NFIF0S=2;{#1  is  for  input  and  §2  for  output} 

PRATE=3 00; {SLOWs  the  display  function} 

{the  following  three  constants  are  for  the  Kaypro  Computer} 
KDATA=5;  KSTAT=7;  RMASK=1 ; 

CR=13; 

LF=10; 

CC=3 ; 

BS=8; 

RUB=127; 

SPACE=32; 

CQ=17; {XON} 

CS=19; {XOFF} 

type  stack  =  array [0. .STACKSIZE)  of  integer; 
fifo  =  record 

buf:  array [0. . 255]  of  byte; 
inptr:  byte; 
outptr:  byte; 

flow:  boolean; {for  flow  control} 
end; 

fifon  =  1..NFIFOS; 
tasknum  =  -1..  TASKS; 

var  sp0/spl,sp2,sp3:  integer; {when  zero, task  not  initialized) 
oldn:  tasknum; 
nextn:  tasknum; 

fifos:  array [1 . .NFIFOS]  of  fifo; 

Procedure  defer;  forward; 
function  occupancy (p:  fifon) :byte; 
begin  with  fifos [p]  do 
occupancy :=  inptr-outptr; 
end; 

function  vacancy (p:  fifon) :  byte; 
begin  with  fifos [p]  do 
vacancy: =outptr-inptr-l ; 
end; 

function  dequeuel:  byte; 

begin  with  fifos [1]  do 
begin 

while  (occupancy (1) =0)  or  not  flow 
do  defer; 

dequeuel :=  buf [outptr]; 
out  pt  r : =out pt  r +1 ; 
end; 
end; 

function  dequeue2:  byte; 

begin  with  fifos [2]  do 
begin 

while  (occupancy (2) =0)  or  not  flow 
do  defer; 

deque ue2 :=  buf [outptr] ; 
out  pt  r : =out pt  r +1 ; 
end; 
end; 

procedure  exit; 


begin 

writeln ('JOB  #',oldn,'  terminated.'); 

oldn:  =-l; 

defer; 

end; 

procedure  enqueuel (b:byte) ; 

begin  with  fifos [1]  do 
begin 

buf [inptr] :=b; 
while  vacancy  (1)=0  do 

defer; {hang  while  full} 
inptr: =inptr+l; 
end; 
end; 

procedure  enqueue2 (b:byte) ; 

begin  with  fifos [2]  do 
begin 

buf [inptr] :=b; 
while  vacancy (2) =0  do 

defer; {hang  while  full} 
i nptr : =inpt  r+ 1 ; 
end; 
end; 

function  keyin:byte; 
begin 

repeat  until  (RMASK  =  (RMASK  and  port [ KSTAT ] ) ) ; 
keyin:=  port [KDATA] ; 
end; 

procedure  vout (b:byte) ; 
begin 
bdos  (6,  b) ; 
end; 

Procedure  print; {task#3} 
var  mystack:  stack; 

i:  integer; 
begin 

stackptr :=addr (mystack [STACKSIZE] ) ; 
i:=0; 

{initialize  fifo#2} 
with  fifos [2]  do 
begin 
outptr :=0; 
inptr:=0; 
flow: =t rue; 
end; 
repeat 
i:=i+l; 

if  i=PRATE  then 
begin 
i  :=0; 

vout  (dequeue2) ; 
end 
else 

defer; 

until  false; {forever} 

exit; 

end; 

Procedure  keyboard; {task  #1} 
var  mystack:  stack; 

cb:  byte; 
begin 

stackptr :=addr (mystack [STACKSIZE] ) ; 

{initialize  fifo  #1} 
with  fifos [1]  do 
begin 
inptr :=0; 
outptr :=0; 
flow:=true; 
end; 
repeat 

if  (1  =  (1  and  port [KSTAT] ) ) 
then 
begin 

cb:  =  port  [KDATA] ; 
enqueuel (cb) ; 
end 

else  defer; 
until  false {forever}; 
exit; 
end; 

Procedure  filter; {task  #2} 
var  mystack:  stack; 

b:  byte; 
begin 

stackptr :=addr (mystack [STACKSIZE] ) ; 
repeat 

b:=dequeuel; 
case  6  of 
CR:  begin 
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CONCURRENCY 

LISTING  TWO  (Listing  continued,  text  begins  oi 

i  page  36) 

enqueue  2  (CR) ; 

3:  sp3:=stackptr; 

enqueue 2  (LF) ; 

end {case} ; 

end; 

schedule; 

LF :  { ignore } ; 

oldn:=nextn; 

CC:  exit; 

case  nextn  of 

BS, RUB: 

0:  sp:=sp0; 

begin 

1:  sp: -spl; 

enqueue2 (BS) ; 

2:  sp:=sp2; 

enqueue2 (SPACE) ; 

3:  sp:=sp3; 

enqueue2 (BS)  ; 

end {case} ; 

end; 

if  sp<>0  {initialized} 

CQ:  fifos[2] .flow:=true; 

then  begin 

CS:  fifos[2] .flow:=false; 

stackptr:=sp; 

else  enqueue2 (b) ; 

end 

end (case); 

else  {not  initialized} 

until  false; (forever! } 

begin 

exit; 

case  nextn  of 

end; 

1:  keyboard; 

procedure  ini tall; 

2:  filter; 

var  i:  integer; 

3:  print; 

Begin 

end {case} ; 

spl:=0; 

end; 

sp2:=0; 

end  {defer}; 

sp3:=0; 

begin{main} 

oldn:=0; 

initall; 

end; 

writeln  (^Demonstration  of  multitasking  with  queues  (FIFOs) >'); 

Procedure  schedule; 

writeln; 

begin 

writeln( 'Control-S  stops  output  (you  can  still  type  ahead!)'); 

if  oldn=TASKS  then  nextn:=l 

writeln ('Control-Q  restarts  output  (you  can  see  what  you  have 

else  nextn: =oldn+l; 
end; 

procedure  defer; 

typed  ahead) ' ) ; 

writeln ('RUB  or  BACKSPACE  will  "undo"  on  screen  the  last 

var  sp:  integer; 

letter' ) ; 

begin 

writeln ( 'Control -C  terminates  this  program'); 

case  oldn  of 

writeln; 

0 :  spO : =stackptr ; 

defer; 

writeln ('main:  done'); 

1 ;  spl : =stackptr ; 

end. 

2:  sp2:=stackptr; 

End  Listings 
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SPEEDING  MS  DOS 


LISTING  ONE  (Text  begins  on  page  44 ) 


Weissman/Dr.  Dobbs  submission  Listing  1: 
Assembler  BIOS  diskette  read  test  program. 


Assembler  code  to  test  diskette  times, 
reading  16  tracks  through  INT  13. 
10/1/85  Gregg  Weissman 

E-X-E  Software  Systems 


HI_RES_T  IMER  equ  1 

;  Set  this  to  1  if  you  implement 

;  the  1024  tick/sec  AT  timer. 

;  It  will  return  time  in  lk'ths  of 
;  a  second.  If  using  the  usual  IBM 
;  18.2  ticks  per  second  timer,  set  to  0 
;  and  receive  counts  at  that  rate. 

if  HI_RES_TIMER 

GET_TIME  equ  lOh 

else 

GET_TIME  equ  0 

end  if 


;  Define  the  proper  AH  function  value 
;  For  int  lah 


Start  the  test  code: 


CODE  segment 

assume  cs : code, ds: code, es: code, ss:code 


START: 


SIDE  1: 


N2: 


org 

80h 

dw 

2 

;  Time  accumulator  out  of  the  way. 

dw 

0 

org  10 Oh 

;  First,  read  a  dummy  sector 

to  start  the  ; 

;  diskette:  this  way  motor  start  time  will  ; 

;  not 

affect  the  timings. 

{ 

mov 

ax, 0201h 

;  Read,  1  sector. 

mov 

cx,  1 

;  Starting  @  track  0,  sector  1 

mov 

dx,  1 

;  Side  0,  diskette  B: 

mov 

bx, offset  DATA  AREA 

int 

13h 

;  Perfom  the  op. 

jb 

STOP 

;  Error:  abort. 

;  Now 

get  the  time  of  day  and  perform 

;  the 

test.  Read  32  tracks. 

16  cyl's.  ; 

cli 

mov 

ah, GET  TIME 

int 

lah 

mov 

TIME  LO,dx 

mov 

TIME  HI, cx 

sti 

xor 

bp,  bp 

;  Set  a  register  to  count  reads. 

mov 

di, 290 

;  number  of  sectors  total  in  test file. 

mov 

dx,  1 

;  disk  B: 

mov 

cx, 0001 

;  Start  at  trk  0,  sect  1 

mov 

bx, offset  DATA_AREA 

mov 

al,  9 

cmp 

di,al 

;  Number  not  mod  9,  might  do  partial 

jnb 

N2 

;  read  on  last  track. 

mov 

ax,  di 

;  Move  partial  read  value  into  al 

mov 

ah,  2 

;  Read  disk  function  code  into  AH 

int 

13h 

;  Perform  disk  read. 

jb 

STOP 

;  Error:  don't  bother  with  re-try. 

sub 

di,  9 

;  Subtract  default  count  of  sectors. 

jbe 

DONE 

;  We're  done  if  di  <=  0 

inc 

bp 

;  Count  the  op.  to  verify  number  done. 
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DONE: 


STOP: 


xor 

dh,  1 

;  Flip  sides. 

jne 

SIDE_1 

;  If  we  flipped  to  side  1,  do  it. 

inc 

ch 

;  else  bump  to  next  track  (cylinder) 

jrap 

SIDE_1 

;  and  go  back  for  more. 

mov 

int 

ah, GET  TIME 
lah 

;  OK,  stop  the  clock. 

sub 

dx,  TIME  LO 

;  Get  end_time  -  Start_time. 

sbb 

cx, TIME  HI 

;  WARNING! 

;  This  program  does  not  return  to  DOS! 
;  Do  not  run  this  except  under  DEBUG! 


int  3 

org  200h 


;  DEBUG  breaks  here,  read  time  in  DX 
;  BP=20h  and  Carry  Clear  if  no  errors. 


DATA_AREA  label  byte 

CODE  ends 
end  START 


End  Listing  One 


LISTING  TWO 


Weissman/Dr.  Dobbs  Submission.  Listing  2: 
AT  timer  handler. 


Memory-resident  handler  for  the  1024 
tick/sec.  realtime  clock  in  the  IBM  AT: 

Enables  INT  70,  the  clock  interrupt,  and 
counts  the  ticks  at  the  lk  rate.  The  range  is 
2**32  div  2**10,  or  2**22  seconds.  Long  enough. 
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SPEEDING  MS  DOS 


LISTING  TWO  (Listing  continued;  text  begins  on  page  44) 


Sets  up  the  usual  INT  1A  (Get /set  time  of  day) 
to  handle  get/set  of  the  hi-resolution  timing 
data  via  special  codes  in  AH  register. 

With  AH=10h,  caller  recieves  current  time  in  lk 
ticks. 

CX  returns  high  16  bits,  DX  the  low. 
AH=llh  allows  user  to  set  the  32-bit  count. 
CX=High  count  to  set,  DX  is  low. 

10/1/85  Written  by  Gregg  Weissman 
E-X-E  Software  Systems 
Released  to  the  public  domain. 


CODE  segment 

assume  csrCODE, ds : CODE, es: CODE,  ss:CODE 


Conserve  memory  space:  maintain  variables 
in  the  unused  areas  of  the  program  prefix. 


org 

5ch 

I1AJMP 

dd 

;  Vector  to  usual  1A  int 

I70JMP 

dd 

■p 

;  Ditto  the  INT  70. 

TIMELO 

dw 

o 

;  low  16  bits  of  time. 

TIMEHI 

dw 

9 

;  Hi  16  bits  of  time. 

org 

100h 

;  Start  of  .COM  program 

BEGIN: 

jmp 

short  START 

;  Jump  around  handlers. 

Handle  the  Get/Set  time-of-day  INT  1A: 

As 

mentioned,  AH=10h 

Returns  time. 

AH-llh 

Sets  time 

Illegal  values  >llh 

return  Carry  status 

INT  1A  proc 

far 

assume  ds : nothing, es: nothing, ss 

: nothing 

cmp 

ah, lOh 

;  See  if  it' 

s  our  range  of  cmnd  vals. 

jb 

NOPE  1A 

;  If  less  than,  assume  BIOS  int  la. 

sub 

ah, lOh 

;  Remove  special  code  "bias"  of  lOh 

je 

GET  TIME 

;  and  branch  if  equal  to  "Get"  cmnd. 

dec 

ah 

;  See  if  "Set"  cmns. 

jne 

BAD_CMD_1A 

;  If  not,  branch  to  error. 

— 

set  time:  cx,dx 

mov 

TIMEHI, cx 

mov 

TIMELO, dx 

iret 

GET_TIME 

mov 

cx, TIMEHI 

;  Obtain  the 

number  of  times  the  1024 

mov 

dx, TIMELO 

;  tick  per  sec.  interrupt  has  occurred. 

iret 

BAD_CMD_1A: 

stc 

ret 

2 

;  Return  an 

error  flag. 

NOPEJLA: 

jmp 

I1AJMP 

;  Continue  to  BIOS  handler  via  vector. 

INT  1A  endp 
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_ SPEEDING  MS  DOS 

LISTING  TWO  (Listing  continued,  text  begins  on  page  44) 


Handle  the  1024  ticks/second  realtime 
clock  interrupt:  maintain  32-bit  count. 


Still  assume  ds,  etc.  nothing  in  effect. 


INT_70  proc  far 

push  ax 

push  ds 

mov  ax, cs 

mov  ds,ax 

assume  ds:CODE 

inc  TIMELO 

jne  CONT_70 

inc  TIMEHI 


CONT  70: 


pushf 

call  I70JMP 

call  ENABLE_INT 

pop  ds 

pop  ax 

iret 


INT_70  endp 


;  Bump  low  counter. 

;  Continue  if  count  not  wrapped  around 
;  Bump  high  counter. 


;  Simulate  INT  nn 
;  Call  the  realtime  clock  handler, 

;  to  let  BIOS  handle  user-event -wait . 
;  And  return  here  so  we  can  re-init 
;  the  timer:  BIOS  turns  it  off. 


This  routine  enables  the  "PIE",  or  ; 
periodic  interrupt  event.  It  is  called  ; 
when  the  system  initializes,  and  after  ; 
each  tick,  in  case  BIOS  turned  it  off.  ; 


This  communicates  with  the  CMOS 
module  via  ports  70h  &  71h.  The 
"JMP  $+2"  is  for  a  delay  between 
port  accesses,  allowing  the  device 
time  to  settle  down.  The  80286  is 
too  fast. 


INT 

proc  near 

cli 

;  Prevent  interruption. 

mov 

al, Obh 

;  First,  identify  the  reg. 

out 

70h, al 

;  we  want  (0b  is  the  one) . 

jmp 

$+2 

?  Just  a  long  NOP. 

in 

al,71h 

or 

al, 01000000b 

;  This  bit  is  int.  enable 

mov 

ah,  al 

;  Save  value:  we  need  al 

mov 

al, Obh 

;  Address  the  register  again. 

out 

70h, al 

jmp 

$+2 

;  NOP 

mov 

al,ah 

;  Get  back  the  desired  value. 

out 

71h, al 

;  Now  stored  in  CMOS  &  ready. 

in 

al, Oalh 

;  Int.  control  chip  register. 

and 

al,0feh 

;  Bit  0  is  another  int.  enable 

out 

Oalh, al 

;  now  set  to  allow  interrupt. 

mov 

al, 20h 

;  Send  "End  of  interrupt"  for 

out 

0a0h,al 

;  good  measure. 

out 

020h, al 

;  ditto  controller  chip  1. 

sti 

ret 

INT 

endp 

Initialize  the  interrupt  handlers  and 
the  interrupt  generator  itself.  Leave 
behind  the  resident  code. 


We  leave  out  amenities  like  DOS  version 
test  and  check  for  an  actual  AT. 


START: 

assume  ds : CODE, es : CODE,  ss: CODE 


mov 

clc 

ah, lOh 

;  First  check  to  see  if  already 
;  resident. 

mov 

cx, 1234h 

;  by  constructing  an  unlikely 

mov 

dx,  cx 

;  time  value  of  12341234h 

int 

lah 

;  See  if  we  get  the  time  back. 

crop 

cx,  dx 

;  If  cx=1234=dx,  not  present. 
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je  NOTJTHERE 

mov  dx, offset  ALREADY 

mov  ah, 9 

int  21h 

mov  ax/4c01h 

int  21h 

NOT_THERE : 

mov  ax,3570h 

int  21h 

mov  word  ptr  I70JMP,bx 

mov  word  ptr  I70JMP+2,es 

mov  ax, 351ah 

int  21h 

mov  word  ptr  IlAJMP,bx 

mov  word  ptr  IlAJMP+2,es 

push  cs 

pop  es 

mov  THIS_SEG, cs 

cli 

mov  dx, offset  INT_la 

mov  ax, 251ah 

int  21h 

mov  dx, offset  INT_70 

mov  ax, 2570h 

int  21h 

mov  dx, offset  HELLO 

mov  ah,  9 

int  21h 

call  ENABLE_INT 

mov  dx, offset  START+15 

mov  cl,  4 

shr  dx,cl 


mov  TIMELO,  0 

mov  TIMEHI,  0 

mov  ax, 3100h 

int  21h 


;  Tell  the  user  it's  in  already 
;  using  DOS  print  function. 

;  Terminate  with  errorlevel  1 

;  Get  the  current  vectors 
;  from  DOS. 

;  Save  in  prefix  are  variables. 

;  Got  the  70,  now  get  1A 

;  Restore  es  for  form's  sake 

;  Set  interrupt  vectors  to  our  handlers 
;  Ditto  for  int  70. 

;  Print  a  message 

;  Start  the  timer. 

;  Set  terminate  address  in 
;  paragraphs,  rounding  up  & 

;  dividing  by  16. 

;  Clear  the  current  time. 

;  Terminate  &  stay  put. 

;  End. 


_ SPEEDING  MS  DOS _ 

LISTING  TWO  (Listing  continued,  text  begins  on  page  44) 

; —  Messages  for  the  user: 

HELLO  db  ' Hi-resolution  AT  timer  now  loaded. ',13,10, 

ALREADY  db  'The  resident  timer  handler  is  already  installed. ',13,10, '$' 

CODE  ends 

end  begin  End  Listing  Two 


LISTING  THREE 


Weissman/Dr.  Dobbs  Submission  LISTING  3: 
Sample  program  fragment  to  change  diskette 
BIOS  parameters. 


Define  the  structure  of  the  BIOS  diskette  parms 


DISKPARMS 

struc 

SPEC1 

db 

2 

;  Don't  change  these  values 

SET  PARMS 

proc 

SPEC2 

db 

? 

SPEC3 

db 

2 

push 

bx 

Save 

the  reg's 

SPEC4 

db 

2 

push 

ds 

SPEC5 

db 

2 

xor 

bx,  bx 

need 

sysO 

SPEC6 

db 

2 

mov 

ds,bx 

SPEC7 

db 

2 

SPEC8 

db 

2 

assume 

ds:SYS0 

SPEC9 

db 

2 

HEAD  SETTLE 

db 

2 

Ids 

bx, DISK  PTR 

MOTOR  WAIT 

db 

2 

assume 

ds : nothing 

DISKPARMS 

ends 

xchg 

[bx] . HEAD  SETTLE, al 

xchg 

[bx] .MOTOR  WAIT, ah 

;  Define  the 

location  of  the  pointer  to  the  parms  ; 

pop 

ds 

pop 

bx 

SYSO  segment 

at  0000 

ret 

org 

78h 

SET_PARMS 

endp 

DISK  PTR 

label 

dword 

; —  You 

need  your  own  "assume"  and  "end" 

statements  1 

Here  is  fragment  to  access  the  current 
parameter  block,  and  set  the  settle-time 
and  motor  wait . 

Enter  with  the  settle  time  in  AL,  and 
the  motor-wait  value  (in  l/8ths  of  a  sec.) 
in  AH. 

So  you  can  preserve  and  restore  the  current 
values,  AL  &  AH  return  with  them:  you  must 
save  them  for  later  if  you  want  to  restore. 


End  Listing  Three 
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LISTING  FOUR 


Timing  the  DOS  command:  "COPY  B: TESTFILE. 001  NUL:" 

D0S2OOLS  LOGDOS/GETSTATS  (1.1)  DOS  timing  statistics  output. 

Function  *:  Count:  Total  Time:  Mean  Time: 


3D 

3F 


0:2.1970 

0:7.4149 


0:0.7323  (OPEN) 
0:2.4716  (READ) 


Other  DOS  function  timings  not  related  to  the  test  are  left  out 

STATISTICS  SUMMARY: 

Total  DOS  function  calls  counted: 

83 

Total  DOS  execution  time: 

0:9.7218 

Mean  DOS  execution  time: 

0:0.1171 

Histogram  of  the  relevant  time  taken  up  by  different  functions  -  as  before,  irrelevant  DOS  calls  left  out. 
3D:  22. 6% ******************** 


LISTING  FIVE 


BASICA  Interpreter  with  default  128-byte  buffer  size. 

D0S2OOLS  LOGDOS/GETSTATS  (1.1)  DOS  timing  statistics  output. 


Function  #: 

Count : 

Total  Time: 

Mean  Time 

3D 

1 

0:2.1970 

0:2.1970 

(OPEN) 

3F 

1153 

0:41.963 

0:0.0364 

(READ) 

STATISTICS  SUMMARY: 

Total  DOS  function  calls  counted: 
1171 

Total  DOS  execution  time: 

0:44.215 

Mean  DOS  execution  time: 

0:0.0378 


End  Listing  Four 


SPEEDING  MS  DOS 


LISTING  FIVE  (Listing  continued,  text  begins  on  page  44) 


3D:  05.0%*** 

3F :  94.9%********************************************************************* 

End  Listing  Five 

LISTING  SIX 


ASSEMBLER  code  calling  DOS  with  record  size  of  200h  bytes 


D0S200LS  LOGDOS/GETSTATS  (1.1)  DOS  timing  statistics  output. 


Function  #: 

Count : 

Total  Time: 

Mean  Time 

3D 

1 

0:1.9773 

0:1.9773 

3F 

289 

1:0.8025 

0:0.2104 

STATISTICS  SUMMARY: 

Total  DOS  function 

calls  counted: 

293 

Total  DOS  execution  time: 
1:2.7798 

Mean  DOS  execution  time: 
0:0.2143 


3D:  03.1%** 
3F :  96.9%** 


End  Listing  Six 
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SPEEDING  MS  DOS 

LISTING  SEVEN  (Listing  continued;  text  begins  on  page  44.) 

ASSEMBLER  code,  block  read  size  of  OFEOOh 


D0S200LS  LOGDOS/GETSTATS  (1.1)  DOS  timing  statistics  output. 


Function  ♦: 

Count: 

Total  Time: 

Mean  Time 

3D 

1 

0:2.1970 

0:2.1970 

3F 

3 

0:7.1403 

0:2.3801 

STATISTICS  SUMMARY: 

Total  DOS  function  calls  counted: 
7 

Total  DOS  execution  time: 

0:9.3923 

Mean  DOS  execution  time: 

0:1.3418 


3D:  23.4%***************** 
3F:  76.0%***************** 

LISTING  EIGHT 


End  Listing  Seven 


ASSEMBLER  code,  block  read  size  of  2400h  (  9  k-bytes  ) 

DOS2QOLS  LOGDOS/GETSTATS  (1.1)  DOS  timing  statistics  output. 


Function  #  : 

Count: 

Total  Time: 

Mean  Time 

3D 

1 

0:2.0322 

0:2.0322 

3F 

17 

0:9.5021 

0:0.5589 

STATISTICS  SUMMARY: 

Total  DOS  function  calls  counted: 
22 

Total  DOS  execution  time: 

0:11.534 

Mean  DOS  execution  time: 

0:0.5243 


3D:  17.6%############## 

3f :  82.4%#####################################################################  End  Listings 
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ASSEMBLE 

LISTING  ONE  (Text  begins  on  page  122) 

MOV.D 

R6,TOS 

/*  a  square  root  algorithm 

MOV.D 

ADDR 

Qnshfts, TOS 

Z  6+4  6,  TOS 

04/21/85,  R.  A.  Campbell 

*/ 

JSR 

Qprintf 

ADJSP 

ENDPROC 

-8 

#define  NUMBER  60000 

Z6: 

BYTE 

115,113,114, 

32,37, 53,100, 61,37, 51,100, 32 

long  number,  ndivs,  nshfts; 

BYTE 

0,10,84,111, 

116, 32, 68,105, 118, 115, 61,37 

BYTE 

5i,  li.7, 32,  65 

,  118,101, 32, 68, 105, 118,115,  46 

long  sqrrt,  sqrrto; 

BYTE 

40,120,49,48 

,41,61,37,50,117,0,10,84 

BYTE 

111,116, 32,83, 104,102, 116, 115, 61, 37, 51,117 

mam  ()  /*  a  test  loop  for  square  root  calculation  */ 

{  nshfts  =  ndivs  =0; 

BYTE 

BYTE 

32,  65,118,  id,  32,83, 104, 102, li.6,  il5,  46, 61 
37.50.117.0 

sqrrto  =  iuu; 

for  (  number  =0;  number  <= 

NUMBER;  ++number  ) 

End  Listing  Two 

{  sqrrt  =  sqrt  (  number  ) ; 

/*  for  timing,  comment  out  next  2  lines  */ 

LISTING  THREE 

if  (  sqrrt  !=  sqrrto  ) 

printf  ("sqr  %6d=%4d  ",  number,  sqrrt  ); 

Qsqrt: 

PROC 

; square  root,  dividing  version 

sqrrto  =  sqrrt; 

Znumb: 

DOUBLE 

; registers  R0,  R6  &  R7  used  by  compiler 

i 

VAR 

; registers  R1  -  R5  for  register  variables 

printf  ("\nTot  Divs=  %u  AVe 

Divs.(xl0)=  %u". 

BEGIN 

<R4,R3,R2,R1 

,>  ;push  used  registers 

ndivs,  (10  *  ndivs) /NUMBER) ; 

; 

BR 

Q15 

;for  timing 

printf  ("\nTot  Shfts=  %u  Ave 

Shfts.  (xlO)  =  %u". 

MOV.D 

Znumb,  R1 

;get  number  into  R1 

nshfts,  (10  *  nshfts) /NUMBER) ; 

CMPQ.D 

0,R1 

;is  number  zero? 

} 

BEQ  Q8 

; mustn't  divide  by  zero 

Q7: 

MOVQ.D 

1,R2 

; guessl  =  1 

sqrt  (  numb  )  /*  a  'rational'  square  root  */ 

MOV.D 

R1,R3 

;guess2  =  number 

register  long  numb; 

Q9: 

MOV.D 

R2,R6 

;load  guessl 

{  register  long  guess 1,  guess2,  error; 

ASH.D 

1,R6 

; guessl  «  1 

/*  return;  for  timing  checks  */ 

CMP.D 

R3,R6 

; compare  with  guess2 

if  (  numb  !=  0  ) 

BLE.S 

Qll 

; while  (  (guessl  «  1)  <  guess2  ) 

{  guessl  =1; 

Q10: 

ASH.D 

1,  R2 

; guessl  «=  1 

guess 2  =  numb; 

ASH.D 

-1,  R3 

;guess2  »=  1 

while  (  (guessl  «  1) 

<  guess2  ) 

BR.S 

Q9 

;see  if  done 

{  guessl  «=  1; 

/*  multiply  guessl  by  2  */ 

Oil: 

guess2  »=  1; 

/*  divide  guess2  by  2  */ 

Q13: 

ADD.D 

R3,R2 

; guessl  +=  guess2 

++nshfts; 

/*  for  statistics  */ 

ASH.D 

-1,  R2 

; guessl  /=  2 

i 

MOV.D 

R1,R6 

;numb 

do 

/*  now,  check  */ 

QUO.D 

R2,R6 

;numb  /  guessl 

{  guessl  +=  guess2; 

/*  figure  sum  */ 

MOV.D 

R6,R3 

;guess2  =  numb  /  guessl 

guessl  »=  1; 

/*  fig  mean,  divide  by  two  */ 

MOV.D 

R2,R6 

guess2  =  numb  /  guessl;  /*  figure  quotient  */ 

SUB.D 

R3,R6 

error  =  guessl  -  guess2;  /*  figure  error  */ 

MOV.D 

R6,R4 

; error  =  guessl  -  guess2 

++ndivs; 

/*  for  statistics  */ 

CMPQ.D 

0,  R4 

)  while  (  error  >  0  ) ; 

BGE.S 

Q14 

; while  (  error  >  0  ) 

return  guessl; 

BR.S 

Q13 

i 

End  Listing  One 

Q14 : 

MOV.D 

R2,R6 

; return  guessl 

else 

BR.S 

Q15 

return  0; 

Q8: 

Q16: 

Q15: 

MOVQ.D 

0,  R6 

; return  0 

LISTING  TWO 

ENDPROC 

IMPORT 

Q  shell  00 

exit 

;SCN:v5  (C)  1985 

IMPORT 

Qprintf  01 

PROGRAM 

STATIC  1 

END  ;  SCN, 

03/22//85 

End  Listing  Three 

Qnumber:  DOUBLE 

Qndivs:  DOUBLE 

LISTING  FOUR 

Qnshfts:  DOUBLE 

Q sqrrt :  DOUBLE 

Qsqrrto:  DOUBLE 

Qsqrt: 

PROC 

; square  root,  bit-shifting 
version 

PROGRAM 

Znumb: 

DOUBLE 

JUMP  Q  shell 

VAR 

Qtnain:  PROC 

BEGIN 

<R4,R3,R1,> 

push  registers  used 

VAR 

; 

BR.S 

SQRTZ 

;for  timing 

BEGIN 

MOV.D 

Znumb, R0 

number  to  R0 

MOVQ.D  0,  R6 

MOVQ.D 

0,R1 

; estimate  =  0 

MOV.D  R6, Qndivs 

MOVQ.D  0 

,R6 

; trial  root  =  0 

MOV.D  R6, Qnshfts 

MOV.  B 

16,  R4 

;loop  count 

MOV.D  100, Qsqrrto 

SQRTL: 

ROT.D 

2,  R0 

;2  msb's  to  2  lsb's  of  number 

MOVQ.D  0, Qnumber 

MOV.B 

R0,R3 

;get  shifted  number  in  R3 

Ql:  CMP.D  60000, Qnumber 

AND.B 

3,  R3 

; isolate  2  lsb's  of  R3 

BLT.S  Q3 

ASH.D 

2,  R1 

; shift  estimate 

Q2:  MOV.D  Qnumber, TOS 

OR.  B 

R3,R1 

;OR  2  lsb's  into  estimate 

BSR  Qsqrt 

ASH.D 

1,  R6 

; shift  trial  root 

MOV.D  R6,Qsqrrt 

MOV.D 

R6,R3 

;get  trial  root 

CMP .  D  Qsqrrto ,  Qsqr  rt 

ASH.D 

1,  R3 

; trial  root  *  2 

BEQ.S  Q5 

CMP.D 

R1,R3 

; compare  to  estimate 

<24 ;  MOV .  D  Qsqrrt ,  TOS 

BLS.S 

SQRT2 

;need  a  bit? 

MOV.D  Qnumber, TOS 

ADDQ.D 

1,  R6 

;add  to  trial  root 

ADDR  Z6,TOS 

ADDQ.D 

1,  R3 

;add  to  estimate 

JSR  Qprintf 

SUB.D 

R3,R1 

; adjust  estimate 

ADJSP  -8 

SQRT2 : 

ACB.S 

-1,R4, SQRTL  ; 

count  down,  loop 

Q5:  MOV.D  Qsqrrt , Qsqrrto 

SQRTZ : 

ENDPROC 

; return  root,  in  R6 

ADDQ.D  1, Qnumber 

BR.S  Ql 

03:  MOV.D  10,  R6 

MUL . D  Qndivs , R6 

QUO.D  60000, R6 

MOV.D  R6,TOS 

MOV.D  Qndivs, TOS 

ADDR  Z6+13,  TOS 

JSR  Qprintf 

ADJSP  -8 

MOV.D  Qnshfts, R6 

QUO.D  60000,  R6 

End  Listings 
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_ 8080  SIMULATOR 

LISTING  TWO  (Continued  from  February) 


sui  move.b  (pseudopc)+,d0 
sub.b  d0,rega 
move  sr,d0 
and.u  regcon0f,d0 
move . b  0 ( f lagptr , d0 .u) , regf 
Jmp  (return) 

rst10  move.l  pseudopc.dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.u  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  $1 0( tar gbase) .pseudopc 
jmp  (return) 

rc  btst  /0,regf 

beq  mloop 

move.b  1 (pseudosp) ,d0 

rol.v  /8,d0 

move.b  (pseudosp) ,d0 

addq.l  /2, pseudosp 

lea.l  0(targbase,d0.1) .pseudopc 

Jmp  (return) 

nopD9  bra  lllegl 

jc  move.b  1 (pseudopc) ,d0 

rol.u  /8,d0 
move . b  ( pseudopc ) , d0 
addq.l  /2, pseudopc 
btst  /0,regf 
beq  mloop 

lea.l  0(targbase,d0.1), pseudopc 
Jmp  (return) 

In  moveq  /0 , d0 

move.b  (pseudopc)+,d0 
move.l  Z$ff0000,a0 
move.b  0(a0,d0.1) ,rega 
jmp  (return) 

cc  move.b  1 (pseudopc) ,d0 

rol.u  /8,d0 
move . b  ( pseudopc ) , d0 
addq.l  /2, pseudopc 
btst  /0,regf 
beq  mloop 
move.l  pseudopc.dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.u  /8,d1 

move.b  di ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  0(targbase,d0.1) .pseudopc 
Jmp  (return) 

nopDD  bra  lllegl 


sbl  asr.b/l.regf 

move.b  ( pseudopc )+,d0 

moveq  /0,d1 

subx.b  d0,rega 

move  sr,d0 

and.u  regcon0f,d0 

move.b  0(flagptr,d0.u) ,regf 

Jmp  (return) 

rst18  move.l  pseudopc.dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.u  /8,d1 

move.b  di ,-1 (pseudosp) 


;  D6  Sui  nn 


rpo 


;  D7  Rst  10 


subq.l  /2  ,’pseudosp 

lea.l  $18(targbase) .pseudopc 

jmp  (return) 

btst  /2,regf 
bne  mloop 

move.b  1( pseudosp ),d0 

rol.u  /8,d0 

move . b  ( pseudosp ) , d0 

addq.l  /2, pseudosp 

lea.l  0(targbase,d0.1) .pseudopc 

Jmp  (return) 


poph 


;  D8  Rc 


Jpo 


;  D9  Illegal 
for  8080 


xthl 


;  DA  Jc  addr 


move.b  (pseudosp)+,regl(regs) 
move.b  (pseudosp)+,regh(regs) 
jmp  (return) 

move.b  1 (pseudopc) ,d0 
rol.u  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /2,regf 
bne  mloop 

lea.l  0(targbase,d0.1) .pseudopc 
Jmp  (return) 

move.b  regl(regs) ,d0 
move.b  (pseudosp) .regl(regs) 
move . b  d0 , ( pseudosp ) 
move.b  regh ( regs ) , d0 
move . b  1 ( pseudosp ) , regh ( regs ) 
move.b  d0,1 (pseudosp) 

Jmp  (return) 


;  DB  In  nn 


cpo 


;  DC  Cc  addr 


move.b  1 (pseudopc), d0 
rol.u  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /2,regf 
bne  mloop 
move.l  pseudopc.dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.u  /8,d1 

move.b  di ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea-.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 


;  E0  Rpo 


;  El  Pop  H 


;  E2  Jpo  addr 


;  E5  Xthl 


;  E4  Cpo  addr 


pushh  move . b  regh ( regs ) , - ( pseudosp ) 

move.b  regl(regs) .-(pseudosp) 
jmp  (return) 


anl 


i  DD  Illegal 
for  8080 


and.b  (pseudopc)+,rega 
move.b  rega,d0 
and.u  regconff,d0 
move.b  16(flagptr,d0.u) ,regf 
jmp  (return) 


;  DE  Sbl  nn 


rst20  move.l  pseudopc.dl 
sub.l  targbase.dl 
move.b  dl  ,-2(pseudosp) 
rol.u  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  $20 (targbase) .pseudopc 
jmp  (return) 


;  DF  Rst  18 


rpe  btst  /2,regf 
beq  mloop 

move.b  1 (pseudosp) ,d0 
rol.u  /8,d0 


;  E5  Push  H 


;  E6  Ani  nn 


;  E7  Rst  20 


;  E8  Rpe 
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move.b  (pseudosp) ,d0 
addq.l  /2, pseudosp 
lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

pchl  move.u  regh(regs) ,d0  ;  E9  Pchl 

lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

jpe  move.b  1 (pseudopc) ,d0  ;  EA  Jpe  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /2,regf 
beq  mloop 

lea.l  0(targbase,d0.1),pseudopc 
Jmp  (return) 

xchg  move.u  regd(regs) ,d0  ;  EB  Xchg 

move.u  regh(regs) .regd(regs) 
move.u  d0,regh(regs) 
jmp  (return) 

cpe  move.b  1 (pseudopc) ,d0  ;  EC  Cpe  addr 

rol.u  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /2,regf 
beq  mloop 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.u  /8,dl 

move.b  di ,-1 (pseudosp) 


subq.l  /2, pseudosp 

lea.l  0(targbase,d0.1) .pseudopc 

jmp  (return) 

*preED  bra  illegl  ;  ED  Illegal  for  8080 

*  ED  Is  a  prefix  for  the  popular  Z-80  Instructions.  Some  support 

*  for  then  Is  provided  by  the  minimal  Z-80  simulation  routines  In 

*  the  next  file. 

xrl  move.b  (pseudopc)+,d0  ;  EE  Xrl  nn 

eor.b  d0,rega 
move.b  rega,d0 
and.u  regconff,d0 
move.b  16(flagptr,d0.u) ,regf 

jmp  (return) 

rst28  move.l  pseudopc, dl  ;  EF  Rst  28 

sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.u  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  $28(targbase) .pseudopc 
jmp  (return) 

rp  btst  /7,regf  ;  F0  Rp 

bne  mloop 

move.b  1 (pseudosp) ,d0 
rol.u  /8,d0 
move.b  (pseudosp) ,d0 
addq.l  /2, pseudosp 


(Continued  on  next  page) 
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LISTING  TWO  (Continued  from  February) 


lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

popp 

move.b  (pseudosp)+,regf 
move.b  (pseudosp)+,rega 

Jmp  (return) 

;  FI  Pop  P 

Jp 

move.b  1 (pseudopc) ,d0 
rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /7,regf 
bne  mloop 

lea.l  0(targbase,d0.1) , pseudopc 

Jmp  (return) 

;  F2  Jp  addr 

dl 

Jmp  (return) 

;  F3  Dl 

cp 

move.b  1 (pseudopc) ,d0 
rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /7,regf 
bne  mloop 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move.b  dl ,-2(pseudosp) 
rol.w  /8,d1 

move.b  dl ,-1 (pseudosp) 

subq.l  /2, pseudosp 

lea.l  0(targbase,d0.1) .pseudopc 

Jmp  (return) 

;  F4  Cp  addr 

pushp 

move.b  rega,-( pseudosp) 
move.b  regf .-(pseudosp) 

Jmp  (return) 

;  F5  Push  P 

oria 

or.b  (pseudopc)+,rega 
move.b  rega,d0 
and.w  regconff,d0 
move.b  16(flagptr,d0.u),regf 

Jmp  (return) 

;  F6  Ori  nn 

rst30 

move.l  pseudopc, dl 
sub.l  targbase.dl 
move . b  d 1 , -2 ( pseudosp ) 
rol.w  /8,d1 

move.b  di ,-1 (pseudosp) 

subq.l  /2, pseudosp 

lea.l  $30(targbase) .pseudopc 

Jmp  (return) 

;  F7  Rst  30 

rm 

btst  /7,regf 
beq  mloop 

move.b  1 (pseudosp) ,d0 
rol.w  /8,d0 

;  F8  Rm 

move.b  (pseudosp) ,d0 
addq.l  /2, pseudosp 
lea.l  0(targbase,d0.1) .pseudopc 
jmp  (return) 

sphl  move.w  regh(regs) ,d0  :  F9  Sphl 

lea.l  0(targbase,d0.1) .pseudosp 
Jmp  (return) 

jm  move.b  1 (pseudopc) ,d0  ;  FA  Jm  addr 

rol.u  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /7,regf 
beq  mloop 

lea.l  0 ( tar gbase,d0.1) .pseudopc 
Jmp  (return) 

el  Jmp  (return)  ;  FB  El 

cm  move.b  1( pseudopc ),d0  ;  FC  Cm  addr 

rol.w  /8,d0 
move.b  (pseudopc) ,d0 
addq.l  /2, pseudopc 
btst  /7,regf 
beq  mloop 
move.l  pseudopc, dl 
sub.l  targbase.dl 
move . b  dl ,  -2 ( pseudosp ) 
rol.w  /8,d1 

move.b  dl .-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  0(targbase,d0. 1) .pseudopc 
Jmp  (return) 

nopFD  bra  illegl  :  FD  Illegal 

for  8080 

cpl  cmp.b  (pseudopc)+,rega  ;  FE  Cpi  nn 

move  sr,d0 
and.w  regcon0f,d0 
move.b  0(flagptr,d0.w),regf 
Jmp  (return) 

rst38  move.l  pseudopc, dl  ;  FF  Rst  38 

sub.l  targbase.dl 
move.b  d1,-2(pseudosp) 
rol.u  /8,d1 

move.b  dl ,-1 (pseudosp) 
subq.l  /2, pseudosp 
lea.l  $38(targbase) .pseudopc 
jmp  (return) 


.end 

End  Listing  Two 


LISTING  THREE 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
X  X 

*  This  file  contains  the  special  Z-80  simulation  routines  and  * 

*  the  Morrow  HDC/DMA  support  routines.  * 

x  x 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

globl  preED.outspec 
xdef  mloop, illegl 

return  equ  @16, r  ;  JMP  (return)  is  fast  return  to  MLOOP. 

pseudopc  equ  @15, r  ;  8080's  PC  is  register  A5. 

opptr  equ  @14, r  ;  Pointer  to  opcode  dispatch  table. 


(Continued  on  page  112) 
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_ 8080  SIMULATOR 

LISTING  THREE  (Continued  from  February) 


pseudosp  equ  @13,r 

8080’s  SP  is  register  A3. 

flagptr 

equ  @12, r 

Pointer  to  8080’s  flag  lookup  table 

is  A2 

targbase  equ  @11,r 

Pointer  to  8080’s  address  space  is 

A1 . 

regs 

equ  @1 1 ,r 

Base  pointer  to  8080’s  registers  is 

A1 . 

regcon0e  equ  7,r 

Register  based  constant  /$E  (for  speed). 

regcon0' 

equ  6,r 

Register  based  constant  /$ 1 . 

regcon0f  equ  5,r 

Register  based  constant  /$F. 

regcondd  equ  4,r 

Register  based  constant  /$FF. 

regf 

equ  5,r 

8080’s  Flags 

rega 

equ  2,r 

8080’s  Accumulator 

regb 

equ  -8 

Offsets  from  register  base  pointer 

for 

regc 

equ  -7 

8080’s  pseudo-registers. 

regd 

equ  -6 

A  Sc  F  are  in  Data  Registers. 

rege 

equ  -5 

Pseudo-PC  is  kept  in  an  Address  Register. 

regh 

equ  -4 

regl 

equ  -3 

regopl 

equ  -2 

Operand  1  for  DAA  storage 

regop2 

equ  -1 

”  2  ”  ” 

page 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
X  X 

*  Opcode  dispatch  table.  One  longword  entry  per  opcode  of  the  * 

*  target  (Z-80)  processor,  including  illegals.  * 

x  x 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 
X  X 

*  Only  a  few  of  the  most  popular  instructions  are  simulated.  * 

*  Support  for  the  Z-80  Block  move  instructions  is  provided  * 

*  as  the  flags  for  this  simulation  resemble  those  of  the  Z-80  * 

*  rather  than  the  8080.  Certain  packages  (notably  BDS-C)  check  * 

*  the  flags  and  mistakenly  assume  a  Z-80,  then  use  LDIR/LDDR.  * 

*  Therefore,  minimal  Z-80  support  is  provided  for  these  * 

*  instructions.  By  no  means  is  this  a  complete  simulation  * 

*  of  the  Z-80.  * 

X  X 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 


EDoptab  dc. 

i 

0,0, 

0 

0 

0 

0 

0,0 

;  ED00 

dc. 

i 

0,0 

0 

0 

0 

0 

0,0 

dc. 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED10 

dc 

i 

0,0 

0 

0 

0 

0 

'0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED20 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED30 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED40 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED50 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED60 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED70 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  ED80 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

j  ED90 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  EDA0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

dc 

i 

ldir.cpir 

0 

0,0, 0,0,0 

;  EDB0 

dc 

i 

lddr,0,0, 

3, 0,0, 0,0 

dc 

i 

0,0 

0 

0 

0 

0 

0,0 

;  EDC0 

dc 

i 

0,0 

0 

0 

,0 

0 

0,0 

dc 

i 

0,0 

0 

0 

,0 

0 

.0,0 

;  EDD0 

dc 

a 

0,0 

0 

,0 

.0 

0 

0,0 

dc 

.1 

0,0 

0 

,0 

,0 

0 

,0,0 

;  EDE0 

dc 

.1 

0,0 

0 

,0 

,0 

0 

,0,0 
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dc.l  0,0, 0,0, 0,0, 0,0 
dc.l  0,0, 0,0, 0,0, 0,0 


page 

text 

preED  moveq  /0,d1 

move.b  (pseudopc)+,d1 

asl  /2,d1 

lea.l  EDoptab,a0 

move.l  0(a0,d1 ,u),-(sp) 

beq  lllgED 

rts 

illgED  move.l  (sp)+,d1 
dec.l  pseudopc 
bra  lllegl 


Zero-fill  high  bits. 
Grab  next  opcode. 


Do  the  operation. 


;  Trash  the  address, 

;  fix  PPC  for  ILLEGAL. 


page 

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 


Z-80  opcode  simulation  routines. 


XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 


ldir  move.l  d2,-(sp) 

move.u  regb(regs) ,d0 
dec.w  d0 
moveq  /0,d1 
moveq  /0,d2 
move.u  regh(regs) ,d1 
move.w  regd(regs) ,d2 
move.l  a5,-(sp) 
lea.l  0(targbase,d2.1) ,a5 
lea.l  0(targbase,d1 .1) ,a0 
ldirlop  move.b  (a0)+,(a5)+ 
inc.w  dl 
inc.u  d2 
dbra  d0, ldirlop 
move.l  (sp)+,a5 
move.u  dl .regh(regs) 
move.u  d2,regd(regs) 
move.u  /0,regb(regs) 
moveq  /0,regf 
move.l  (sp)+,d2 
jmp  (return) 

lddr  move.l  d2,-(sp) 

move.u  regb(regs) ,d0 
dec.u  d0 
moveq  /0,d1 
moveq  /0,d2 
move.u  regh(regs) ,d1 
move.u  regd(regs) ,d2 
move.l  a5,-(sp) 
lea.l  1(targbase,d2.1),a5 
lea.l  1 (targbase.dl .1) ,a0 
lddrlop  move.b  -(a0),-(a5) 
dec.u  dl 
dec.u  d2 
dbra  d0, lddrlop 
move.l  (sp)+,a5 
move.u  dl .regh(regs) 
move.u  d2,regd(regs) 
move.u  /0,regb(regs) 
moveq  /0,regf 
move.l  (sp)+,d2 
jmp  (return) 


Grab  count, 

adjust  for  DBRA  later. 


Grab  source. 

Grab  dest. 

Need  an  address  reg. 


;  Restore  result  registers. 


;  Grab  count, 

;  adjust  for  DBRA  later. 


Grab  source. 

Grab  dest. 

Need  an  address  reg. 


;  Restore  result  registers. 


page 

move.u  regb(regs) ,d0 
dec.u  d0 
moveq  /0,d1 


;  Grab  count, 

;  adjust  for  DBRA  later. 
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move.w  regh(regs) ,d1 

;  Grab  source. 

lea.l  0(targbase,d1 .1) ,a0 

cpirlop  inc.w  dl 

cmp.b  (a0)  +  ,rega 

dbeq  d0, cpirlop 

seq  regf 

move.w  dl .regh(regs) 

;  Restore  result  registers. 

inc.w  d0 

move.w  d0,regb(regs) 

tst.b  regf 

bne  cpirl 

moveq  /0,regf 

;  Not  found. 

jmp  (return) 

cpirl  tst  d0 

beq  cpir2 

moveq  /$44,regf 

;  Found,  in  the  string. 

jmp  (return) 

cpir2  moveq  /$40,regf 

;  Found,  but  at  last  place. 

jmp  (return) 

page 

#############################*#################################*######### 

*  Output  instruction  simulator 

for  Morrow  HDDMA  * 

* 

* 

######################################################################### 

outspec  move.l  d3,-(sp) 

cmp.b  /$55,d0 

beq  hdstart 

;  Start  command?  Do  it, 

move.l  /hdbuf.dl 

;  else  build  first  link  to  host  buffer 

move.l  /$50,a0 

;  if  it's  a  HDRESET  command. 

move.b  dl , (a0)+ 

ror.l  /8,dl 

move.b  di , (a0)+ 

ror.l  /8,d1 

move.b  di , (a0)+ 

move.l  Z$ff0000,a0 

;  Do  the  output  to  HDDMA. 

adda.l  d0,a0 

move.b  rega,(a0) 

move.l  (sp)+,d3 

jmp  (return) 

hdstart  move.l  dmalink,a0 

;  Move  target  buffer  to  host  buffer,  do 

adda.l  targbase,a0 

;  all  appropriate  patching  of  addresses. 

moveq  /0,d1 

move.b  (a0)+,d1 

;  Get  link  address. 

ror.l  /8,d1 

move.b  (a0)+,d1 

ror.l  /8,d1 

move.b  (a0)+,d1 

rol.l  /8,d1 

rol.l  /8,d1 

move.l  di ,a0 

adda.l  targbase,a0 

move.l  a6,-(sp) 

lea.l  hdbuf,a6 

move.w  /3,di 

hdloop  move.b  (a0)+,(a6)+ 

dbra  dl.hdloop 

moveq  /0,d3 

;  Fix  DMA  address  to  ->  target  area. 

move.b  (a0)+,d3 

ror.l  /8,d3 

move.b  (a0)+,d3 

ror.l  /8,d3 

move.b  (a0)+,d3 

rol.l  /8,d3 

rol.l  /8,d3 

add.l  targbase,d3 

move.b  d3,(a6)+ 

ror.l  /8,d3 

move.b  d3, (a6)+ 

ror.l  /8,d3 

move.b  d3, (a6)+ 

move.w  /5,d1 

;  Move  rest  of  command  buffer. 

hdloop2  move.b  (a0)+,(a6)+ 

dbra  dl ,hdloop2 

(Continued  on  page  118) 
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LISTING  THREE  (Continued  from  February) 


move.l  /hdbuf, dl 
move.b  dl , (a6)+ 
ror.l  /8,d1 

;  Point  host  buffer  to  self. 

move.b  di , (a6)+ 
ror.l  /8,d1 
move.b  dl , (a6)+ 
move.l  (sp)+,a6 
move.l  a0,-(sp) 

;  Save  STATUS  address  for  return  val. 

suba.l  targbase,a0 
move.l  a0, dmalink 

;  Stash  new  target  link  address. 

move.l  Z$ff0000,a0 
adda.l  d0,a0 
move.b  rega, (a0) 

;  Do  the  output  to  HDDMA. 

move.l  /hdbuf+12,a0 

;  Wait  for  completion 

hdloop3 

tst.b  (a0) 
beq  hdloop3 
move.b  (a0),d1 

;  Fragile,  but  uhat  do  you  want  for  $1.00? 

move.l  (sp)+,a0 

;  Grab  the  STATUS  address  in  target  space. 

move.b  dl ,-(a0) 
move.l  (sp)+,d3 

;  And  stash  status  for  it. 

jmp  (return) 

j  Return  to  simulation. 

data 

even 

dmalink 

dc.l  $50 

;  Storage  for  current  HDDMA  command  buffer. 

hdbuf 

ds.b  16 

end 

End  Listing  Three 

LISTING  FOUR 


xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

X  X 

*  This  file  contains  the  mnemonic  strings  for  the  8080  opcodes.  * 

*  These  are  used  in  tracing.  * 

x  x 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 

globl  mnops 

data 

page 


mnops 


dc . 1  mnnop00 , mnlxib , mnstaxb , mninxb , mninrb , mndcrb , mnmvib , mnr lea 

dc . 1  mnnop08 , mndadb , mnldaxb , mndcxb , mninre , mndcrc , mnmvic , mnrrca 

dc . 1  mnnopl  0 , mnlxid , mnstaxd , mninxd , mninrd , mnderd , mnmvid , mnral 

dc . 1  mnnop 1 8 , mndadd , mnldaxd , mndcxd , mninre , mndcre , mnmvie , mnrar 

dc. 1  mnnop20,mnlxih,mnshld,mninxh,mninrh,mndcrh,mnmvih,mndaa 

dc . 1  mnnop28 , mndadh , mnlhld , mndcxh , mninr 1 , mndcr 1 , mnmvil , mnema 

dc . 1  mnnop30 , mnlxis , mnsta , mninxs , mninrm , mnderm , mnmvim , mnstc 

dc . 1  mnnop38 , mndads , mnlda , mndexs , mninra , mndcra , mnmvia , mneme 

dc . 1  mnmovbb , mnmovbc , mnmovbd , mnmovbe , mnmovbh , mnmo vb 1 , mnmovbm , mnmovba 

dc . 1  mnmovcb , mnmovee , mnmoved , mnmovee , mnmovch , mnmovcl , mnmovcm , mnmovea 

dc .  1  mnmovdb , mnmovdc , mnmovdd , mnmovde , mnmovdh , mnmovdl , mnmovdm , mnmovda 

dc . 1  mnmoveb , mnmovee , mnmoved , mnmovee , mnmoveh , mnmovel , mnmovem , mnmovea 

dc .  1  mnmovhb ,  mnmovhc ,  mnmo  vhd ,  mnmo  vhe ,  mnmovhh ,  mnmovhl ,  mnmo  vhm ,  mnmo  vha 

dc .  1  mnmovlb ,  mnmovlc ,  mnmovld ,  mnmovle ,  mnmovlh ,  mnmovll ,  mnmovlm ,  mnmovla 

dc . 1  mnmovmb , mnmovmc , mnmovmd , mnmovme , mnmovmh , mnmovml , mnhalt , mnmovma 

dc .  1  mnmo  vab ,  mnmovac ,  mnmovad ,  mnmo  vae ,  mnmo  vah ,  mnmoval ,  mnmo  vam ,  mnmo  vaa 

dc . 1  mnaddb , mnaddc , mnaddd , mnadde , mnaddh , mnaddl , mnaddm , mnaddaa 

dc . 1  mnadeb , mnadcc , mnaded , mnadee , mnadch , mnadcl , mnadem , mnadca 

dc . 1  mnsubb , mnsubc , mnsubd , mnsube , mnsubh , mnsubl , mnsubm , mnsubaa 

dc . 1  mnsbbb , mnsbbc , mnsbbd , mnsbbe , mnsbbh , mnsbbl , mnsbbm , mnsbba 

dc . 1  mnandb , mnandc , mnandd , mnande , mnandh , mnandl , mnandm , mnanda 

dc . 1  mnxrab , mnxrac , mnxrad , mnxrae , mnxrah , mnxral , mnxram , mnxraa 

dc . 1  mnorab , mnorac , mnorad , mnorae , mnorah , mnoral , mnoram , mnoraa 
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dc . 1  mncmpb , mncmpc , mncmpd , mncmpe .mncmph , mncmpl , mncmpam , mncmpaa 
dc . 1  mnrnz , mnpopb , mnj  nz , mnj  mpa , mncnz , mnpushb , mnadi , mnrst0 
dc .  1  mnrz ,  mnret ,  mnj  z ,  mnnopCB ,  inncz ,  mncal  1 ,  mnaci ,  mnrst8 
dc . 1  mnrnc , mnpopd , mnj  nc , mnout , mncnc , mnpushd , mnsui , mnrst 1 0 
dc . 1  mnrc , mnnopD9 , mnj  c , mnin , mncc .mnnopDD , mnsbi , mnrst 1 8 
dc . 1  mnrpo , mnpoph , mnj  po , mnxthl , mncpo , mnpushh , mnani , mnrst20 
dc . 1  mnrpe , mnpchl , mnjpe , mnxchg , mncpe , mnpreED , mnxr i , mnrst28 
dc . 1  mnrp , mnpopp , mn j  p , mndi , mncp , mnpushp , mnor ia , mnrst30 
dc . 1  mnrm , mnsphl , mnjm , mnei , mncm , mnnopFD , mncpi , mnrst38 

page 

##xx*###**#*******x#****x#*#*#**#*x******##*#*#***##*****###*####***#»#*« 
*  * 

*  Mnemonic  Strings.  The  first  character  flags  operands.  * 

*  Blank  is  nothing,  A  is  an  address,  C  is  a  constant.  * 

*  * 
#*###»X###*##»##***####**#**#**#K#*#»**#*#**##*#*#*******###*##»###**#*## 

mnnop00  dc.b  ”  N0P$” 
mnlxib  dc.b  "ALXI  B,$" 
mnstaxb  dc.b  "  STAX  B$" 
mninxb  dc.b  ”  INX  B$” 
mninrb  dc.b  "  INR  B$" 
mndcrb  dc.b  ”  DCR  B$” 
mnmvib  dc.b  "CMVI  B,$” 


mnrlca 

dc.b  ' 

’  RLC$” 

mnnop08  dc.b  ' 

*  ILLEGAL  FOR  8080$" 

mndadb 

dc.b 

11  DAD  B$” 

mnldaxb 

dc.b 

"  LDAX  B$” 

mndcxb 

dc.b 

"  DCX  B$” 

mninrc 

dc.b 

“  INR  C$” 

mndcrc 

dc.b 

“  DCR  C$” 

mnmvic 

dc.b 

"  MVI  C$" 

mnrrca 

dc.b 

"  RRC$" 

mnnop10  dc.b 

”  ILLEGAL  FOR  8080$” 

mnlxid 

dc.b 

"ALXI  D,$" 

mnstaxd 

dc.b 

"  STAX  D$" 

mninxd 

dc.b 

"  INX  D$" 

mninrd 

dc.b 

"  INR  D$" 

mndcrd 

dc.b 

”  DCR  D$” 

mnmvid 

dc.b 

"CMVI  D,$” 

mnral 

dc.b 

”  RAL$” 

mnnop18  dc.b 

”  ILLEGAL  FOR  8080$" 

mndadd 

dc.b 

"  DAD  D$” 

mnldaxd 

dc.b 

”  LDAX  D$” 

mndcxd 

dc.b 

"  DCX  D$” 

mninre 

dc.b 

”  INR  E$" 

mndcre 

dc.b 

”  DCR  E$” 

mnmvie 

dc.b 

"CMVI  E,$” 

mnrar 

dc.b 

”  RAR$” 

mnnop20  dc.b 

"  ILLEGAL  FOR  8080$" 

mnlxih 

dc.b 

"ALXI  H,$” 

mnshld 

dc.b 

"ASHLD  $" 

mninxh 

dc.b 

”  INX  H$” 

mnlnrh 

dc.b 

”  INR  H$" 

mndcrh 

dc.b 

”  DCR  H$" 

mnmvih 

dc.b 

"CMVI  H,$” 

mndaa 

dc.b 

"  DAA$" 

mnnop28  dc.b 

"  ILLEGAL  FOR  8080$" 

mndadh 

dc.b 

"  DAD  H$" 

mnlhld 

dc.b 

"ALHLD  $” 

mndcxh 

dc.b 

”  DCX  H$" 

mninrl 

dc.b 

”  INR  L$" 

mndcrl 

dc.b 

"  DCR  L$” 

mnmvil 

dc.b 

"CMVI  L,$” 

mncma 

dc.b 

”  CMA$” 

mnnop30  dc.b 

"  ILLEGAL  FOR  8080$" 

mnlxis 

dc.b 

"ALXI  S,$" 

mnsta 

dc.b 

"ASTA  $" 

mninxs 

dc.b 

”  INX  S$” 

mninrm 

dc.b 

”  INR  M$” 

mndcrm 

dc.b 

”  DCR  M$" 

mnmvim 

dc.b 

"CMVI  M,$” 

mnstc 

dc.b 

”  STC$” 

mnnop38  dc.b 

”  ILLEGAL  FOR  8080$” 

mndads 

dc.b 

"  DAD  S$" 

mnlda 

dc.b 

"ALDA  $” 

mndcxs 

dc.b 

”  DCX  S$" 

mninra 

dc.b 

"  INR  A$” 
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mndcra  dc.b  ”  DCR  A$” 

mnaddm  dc.b  ”  ADD  M$” 

mnrst8  dc.b  ”  RST  8$” 

nnmvia  dc.b  ”CMVI  A,$" 

mnaddaa  dc.b  ”  ADD  A$” 

mnrnc  dc.b  ”  RNC$” 

mncmc  dc.b  "  CMC$” 

mnadcb  dc.b  ”  ADC  B$” 

mnpopd  dc.b  ’’  POP  D$" 

mnmovbb  dc.b  ”  MOV  B,B$” 

mnadcc  dc.b  ”  ADC  C$” 

rnnjnc  dc.b  "AJNC  $" 

mnmovbc  dc.b  ”  MOV  B,C$" 

mnadcd  dc.b  ”  ADC  D$” 

mnout  dc.b  ”COUT  $” 

mnmovbd  dc.b  "  MOV  B,D$” 

mnadce  dc.b  ’’  ADC  E$" 

mncnc  dc.b  ”ACNC  $’’ 

mnmovbe  dc.b  ”  MOV  B,E$” 

mnadch  dc.b  ”  ADC  H$" 

mnpushd  dc.b  ”  PUSH  D$” 

mnmovbh  dc.b  ”  MOV  B,H$” 

nmadcl  dc.b  "  ADC  L$" 

mnsui  dc.b  ”CSUI  $" 

mnmovbl  dc.b  "  MOV  B,L$” 

mnadcm  dc.b  ”  ADC  M$” 

mnrst10  dc.b  ”  RST  10$” 

mmnovbm  dc.b  ’’  MOV  B,M$” 

mnadca  dc.b  ”  ADC  A$” 

mnrc  dc.b  ”  RC$” 

mnmovba  dc.b  ”  MOV  B,A$” 

mnsubb  dc.b  ”  SUB  B$" 

mnnopD9  dc.b  "  ILLEGAL  FOR  8080$” 

nmnovcb  dc.b  "  MOV  C,B$" 

mnsubc  dc.b  ”  SUB  C$” 

mnjc  dc.b  "AJC  $” 

mnmovcc  dc.b  ”  MOV  C,C$” 

mnsubd  dc.b  ”  SUB  D$" 

nrnin  dc.b  "CIN  $" 

mnmovcd  dc.b  ”  MOV  C,D$" 

mnsube  dc.b  ”  SUB  E$” 

mncc  dc.b  ”ACC  $” 

mnmovce  dc.b  ”  MOV  C,E$" 

mnsubh  dc.b  ”  SUB  H$” 

mnnopDD  dc.b  "  ILLEGAL  FOR  8080$” 

mnnovch  dc.b  "  MOV  C,H$" 

mnsubl  dc.b  ”  SUB  L$” 

mnsbi  dc.b  ”CSBI  $" 

mnmovcl  dc.b  ”  MOV  C,L$” 

mnsubm  dc.b  ”  SUB  M$” 

mnrst18  dc.b  "  RST  18$” 

mnmovcm  dc.b  ”  MOV  C,M$” 

mnsubaa  dc.b  ”  SUB  A$” 

mnrpo  dc.b  ”  RPO$" 

mnmovca  dc.b  ”  MOV  C,A$” 

mnsbbb  dc.b  ”  SBB  B$” 

nmpoph  dc.b  "  POP  H$” 

mnmovdb  dc.b  ”  MOV  D,B$” 

mnsbbc  dc.b  ”  SBB  C$” 

mnjpo  dc.b  "AJPO  $” 

nmmovdc  dc.b  "  MOV  D,C$” 

mnsbbd  dc.b  ”  SBB  D$” 

mnxthl  dc.b  ”  XTHL$" 

mnmovdd  dc.b  ”  MOV  D,D$” 

mnsbbe  dc.b  ”  SBB  E$” 

mncpo  dc.b  ”ACPO  $” 

mnmovde  dc.b  ”  MOV  D,E$” 

mnsbbh  dc.b  "  SBB  H$" 

mnpushh  dc.b  "  PUSH  H$” 

mnmovdh  dc.b  ”  MOV  D(H$" 

mnsbbl  dc.b  ”  SBB  L$” 

nnani  dc.b  "CANI  $” 

mnmovdl  dc.b  ’’  MOV  D,L$” 

mnsbbm  dc.b  ”  SBB  M$” 

mnrst20  dc.b  ”  RST  20$" 

mnmovdm  dc.b  ”  MOV  D,M$" 

mnsbba  dc.b  ”  SBB  A$” 

mnrpe  dc.b  ”  RPE$" 

mnmovda  dc.b  ”  MOV  D,A$” 

mnandb  dc.b  ”  ANA  B$" 

mnpchl  dc.b  ”  PCHL$” 

mrmoveb  dc.b  ”  MOV  E,B$" 

mnandc  dc.b  "  ANA  C$” 

mnjpe  dc.b  ”AJPE  $” 

mnmovec  dc.b  ”  MOV  E,C$” 

nnandd  dc.b  ”  ANA  D$” 

mnxchg  dc.b  ”  XCHG$” 

mnmoved  dc.b  ’’  MOV  E,D$” 

mnande  dc.b  ”  ANA  E$” 

mncpe  dc.b  ”ACPE  $" 

mnmovee  dc.b  "  MOV  E,E$” 

mnandh  dc.b  "  ANA  H$” 

mnpreED  dc.b  ”  ILLEGAL  FOR  8080$” 

mnmoveh  dc.b  "  MOV  E,H$” 

mnandl  dc.b  "  ANA  L$" 

mnxri  dc.b  ”CXRI  $” 

mnmovel  dc.b  ”  MOV  E,L$” 

mnandm  dc.b  ”  ANA  M$” 

mnrst28  dc.b  ”  RST  28$” 

mnmovem  dc.b  ”  MOV  E,M$” 

mnanda  dc.b  ”  ANA  A$" 

mnrp  dc.b  ”  RP$” 

mnmovea  dc.b  ”  MOV  E,A$” 

mnxrab  dc.b  ”  XRA  B$” 

mnpopp  dc.b  "  POP  P$” 

mnmovhb  dc.b  ”  MOV  H,B$” 

mnxrac  dc.b  ”  XRA  C$” 

mnjp  dc.b  "AJP  $” 

mnmovhc  dc.b  ”  MOV  H,C$” 

mnxrad  dc.b  "  XRA  D$” 

mndi  dc.b  ”  DI$” 

mmnovhd  dc.b  ”  MOV  H,D$” 

mnxrae  dc.b  ”  XRA  E$” 

mncp  dc.b  "ACP  $” 

mnmovhe  dc.b  ”  MOV  H,E$" 

mnxrah  dc.b  ”  XRA  H$” 

nnpushp  dc.b  ”  PUSH  P$” 

mnnovhh  dc.b  ”  MOV  H,H$” 

mnxral  dc.b  ”  XRA  L$” 

mnoria  dc.b  "CORI  $" 

mnmovhl  dc.b  "  MOV  H,L$" 

mnxrain  dc.b  ”  XRA  M$” 

mnrst50  dc.b  ”  RST  30$" 

mnmovhm  dc.b  ”  MOV  H,M$" 

mnxraa  dc.b  ”  XRA  A$” 

mnrm  dc.b  ”  RM$" 

mruaovha  dc.b  ”  MOV  H,A$" 

mnorab  dc.b  ”  ORA  B$” 

mnsphl  dc.b  ”  SPHL$” 

nmmovlb  dc.b  ”  MOV  L,B$" 

mnorac  dc.b  "  ORA  C$” 

mtijm  dc.b  "AJM  $" 

mnmovlc  dc.b  ”  MOV  L,C$" 

mnorad  dc.b  ”  ORA  D$” 

mnei  dc.b  ”  EI$” 

mnmovld  dc.b  ”  MOV  L,D$” 

mnorae  dc.b  ”  ORA  E$” 

mncm  dc.b  "ACM  $” 

mnmovle  dc.b  ”  MOV  L,E$” 

mnorah  dc.b  ”  ORA  H$” 

mnnopFD  dc.b  ”  ILLEGAL  FOR  8080$” 

mnmovlh  dc.b  ”  MOV  L,H$” 

mnoral  dc.b  ”  ORA  L$” 

mncpi  dc.b  ”CCPI  $” 

mnmovll  dc.b  ”  MOV  L,L$" 

innoram  dc.b  ”  ORA  M$” 

mnrst58  dc.b  ”  RST  38$” 

mnmovlm  dc.b  "  MOV  L,M$” 

ninoraa  dc.b  ”  ORA  A$” 

.end 

mnmovla  dc.b  ”  MOV  L,A$" 

mncinpb  dc.b  ”  CMP  B$” 

nmmovmb  dc.b  ”  MOV  M,B$" 

mncmpc  dc.b  ”  CMP  C$" 

mnmovmc  dc.b  ”  MOV  M,C$” 

rnncmpd  dc.b  ”  CMP  D$” 

nmmovmd  dc.b  ”  MOV  M,D$" 

mncmpe  dc.b  ”  CMP  E$” 

mnmovme  dc.b  ”  MOV  M,E$” 

mncmph  dc.b  ”  CMP  H$” 

mnmovmh  dc.b  ”  MOV  M,H$” 

mncmpl  dc.b  ’’  CMP  L$” 

mnmovml  dc.b  ”  MOV  M,L$” 

mncmpan  dc.b  "  CMP  M$” 

EiUU  LilBllllUB 

mnhalt  dc.b  ”  HLT$” 

mncmpaa  dc.b  ”  CMP  A$" 

nmmovma  dc.b  ”  MOV  M,A$" 

mnrnz  dc.b  ”  RNZ$” 

mnmovab  dc.b  ”  MOV  A,B$" 

urnret  dc.b  ”  RETS” 

mnmovac  dc.b  "  MOV  A,C$" 

mnpopb  dc.b  ”  POP  B$" 

nmmovad  dc.b  ”  MOV  A,D$” 

mnjnz  dc.b  ’’AJNZ  $” 

mnmovae  dc.b  ”  MOV  A,E$” 

mnjmpa  dc.b  "AJMP  $” 

mnmovah  dc.b  "  MOV  A,H$" 

mncnz  dc.b  "ACNZ  $” 

mnmoval  dc.b  ”  MOV  A,L$" 

mnpushb  dc.b  ”  PUSH  B$" 

nnmovam  dc.b  ”  MOV  A,M$” 

mnadi  dc.b  ”CADI  $" 

nmmovaa  dc.b  "  MOV  A,A$” 

nmrsta  dc.b  ”  RST  0$” 

mnaddb  dc.b  ”  ADD  B$” 

mnrz  dc.b  ’’  RZ$” 

mnaddc  dc.b  ”  ADD  C$” 

mnjz  dc.b  ”AJZ  $” 

mnaddd  dc.b  ”  ADD  D$” 

annopCB  dc.b  ”  ILLEGAL  FOR  8080$” 

mnadde  dc.b  ”  ADD  E$” 

nncz  dc.b  ”ACZ  $” 

mnaddh  dc.b  ”  ADD  H$” 

mncall  dc.b  "ACALL  $” 

mnaddl  dc.b  ”  ADD  L$” 

mnaci  dc.b  ”CACI  $” 
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THE  RIGHT  TO  ASSEMBLE 

NS32000  Square  Roots 


The  square  root  routine  for  the 
68000  by  Jim  Cathey  (16-Bit  Soft¬ 
ware  Toolbox,  May  1985)  is  an  exam¬ 
ple  of  the  looping  and  bit-shifting 
routines  that  must  be  used  on  a  mi¬ 
croprocessor  with  limited  arithmetic 
ability  (i.e.,  8-  or  16-bit  registers  and 
only  addition  and  subtraction).  How¬ 
ever,  this  kind  of  bit-level  thinking 
seems  unnecessary  and  even  unde¬ 
sirable  with  a  microprocessor  such 
as  the  NS320XX  or  the  68000.  A  pro¬ 
grammer  would  be  better  off  attack¬ 
ing  such  problems  as  computing 
square  roots  from  a  higher  level. 

The  NS320XX  group  is  made  by  Na¬ 
tional  Semiconductor  (my  NS16032 
was  an  earlier  version)  and  the  68000 
by  Motorola:  They  can  perform  8-, 
16-,  and  32-bit  addition,  subtraction, 
multiplication,  division,  and  modulo 
operations  on  data  in  registers  and 
memory.  The  NS320XX,  in  particular, 
was  clearly  designed  with  high-level 
language  compilation  in  mind.  Al¬ 
though  it  does  have  bit-level  capabili¬ 
ties,  it  actually  performs  better  at  a 
higher  level. 

I  have  described  a  routine  for  cal¬ 
culating  square  roots  and  have  pre¬ 
sented  it  in  both  C-language  program 
form  (Listing  One,  page  106)  and  as¬ 
sembly  language  for  the  NS320XX  pro¬ 
cessor  (Listing  Two,  page  106).  Com¬ 
piling,  assembling,  and  linking  takes 
about  IV2  minutes  on  a  system  with 
relatively  slow  floppy-disk  access.  I 
hope  that  one  of  these  presentations 
will  be  helpful  to  you.  I  often  find  it 
frustrating  to  try  to  understand  an 
interesting  programming  approach 
to  a  problem  when  it  is  only  general- 
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ly  described  or  when  it  is  presented 
in  a  language  I  am  vaguely  familiar 
with. 

The  square  root  of  a  real  number  is 
one  of  two  equal  factors  of  that  num¬ 


ber  and,  of  course,  the  square  of  the 
square  root  equals  the  number. 
When  dealing  with  integers,  howev¬ 
er,  the  situation  is  somewhat  differ¬ 
ent.  The  square  root  of  an  integer  is 
the  smallest  of  the  two  most  nearly 
equal  factors  of  that  number.  For  ex¬ 
ample,  the  two  most  nearly  equal  in¬ 
teger  factors  of  255  are  15  and  17,  and 
the  square  root  of  255  is  15.  The  inte¬ 
ger  square  root  when  squared  may 
not  equal  the  number. 

This  routine  has  two  stages.  The 
first  is  to  find  two  roughly  equal  fac¬ 
tors  of  the  number,  guessl  and 
guessZ,  in  the  quickest  possible  way. 
Initially,  guessl  is  set  to  1  and  guess2 
is  set  to  the  number  for  which  the 
square  is  desired.  Guessl  is  then  mul¬ 
tiplied  and  guess2  is  divided  by  two 
until  their  values  are  approximately 
equal.  An  average  of  the  two  guesses 
is  calculated  as  the  trial  square  root, 
and  we  move  to  the  testing  stage.  In 
all  cases,  multiplication  and  division 
by  two  are  done  by  the  faster  meth¬ 
ods  of  left  and  right  shifting. 

This  trial  square  root  now  becomes 
guessl  and  is  tested  by  dividing  it  into 
the  number,  and  the  quotient  be¬ 
comes  guess2.  An  error  term  is  calcu¬ 
lated  by  subtracting  guess2  from 
guessl.  If  this  error  is  negative  or 
zero,  guessl  is  taken  as  the  square 
root.  If  this  error  is  positive  (the  trial 
square  root  is  too  high),  a  new  trial 
square  root  (the  mean  of  the  two 
guesses)  is  computed,  and  the  above 
division  test  is  repeated  until  the  er¬ 
ror  becomes  zero  or  negative. 

The  trial  square  root  from  the  fac¬ 
toring  stage  is  biased  high,  which  is 
advantageous  because  it  leads  to 
downward  adjustment  only  of  the 
trial  square  root.  This  is  good  because 
when  the  correct  square  root  of  an 
integer  number  is  divided  into  the 
number  it  may  yield  a  quotient  great¬ 
er  than  the  square  root.  For  example, 
consider  the  integer  square  root  of 
24.  [The  first  trial  square  root  would 
be  5  (the  mean  of  4  and  6),  24  divided 


by  5  is  4,  because  the  error  (5—4)  is 
+  1,  4  is  not  the  correct  root.]  The 
next  trial  square  root  would  be  5  plus 
4  divided  by  2,  or  4.  Because  24  divid¬ 
ed  by  4  equals  5,  an  error  of  —  1,  the 
integer  square  root  of  24  is  4. 

Although  you  might  be  suspicious 
of  it,  the  above  description  should 
make  sense,  particularly  if  you  try  it 
out  with  paper  and  pencil.  Though 
the  bit-shifting  routines  are  virtually 
opaque,  this  routine  does  work  accu¬ 
rately  and  fast. 

Test  runs  computing  the  square 
root  of  integers  from  0  to  60,000,  as 
shown  in  Listing  Three,  page  106,  in¬ 
dicate  that  on  the  average  7.0  shifts 
(excluding  the  test)  and  1.8  divisions 
per  square  root  were  carried  out;  25 
percent  of  the  times  only  one  divi¬ 
sion  was  required,  and  the  maxi¬ 
mum  was  four.  Running  the  full 
60,000  square  root  program  on  a  6- 
MHz  NS16032  CPU  took  27  seconds  and 
17  seconds  without  printing  or 
counting  shifts  and  divisions.  The 
program  only  prints  the  square  root 
when  it  changes  from  the  previously 
calculated  one. 

Running  the  program  without 
printing,  counting,  or  square  root 
calculations  took  6  seconds;  there¬ 
fore,  the  60,000  square  roots  took  11 
seconds  (17—6)  to  calculate.  Thus,  the 
average  time  per  square  root  is  a 
rather  respectable  183  microseconds. 
The  assembly-language  routine  was 
compiled  and  could  be  hand  opti¬ 
mized.  A  couple  of  branches  could  be 
eliminated  and  the  error  term  would 
not  have  to  be  stored.  Is  it  worth  the 
programming  time?  Not  to  me. 

Listing  Four,  page  106,  shows  Cath¬ 
ey's  bit-shifting  version  as  coded  for 
the  NS320XX.  Although  it  contains 
fewer  instructions,  it  actually  is  con¬ 
siderably  slower  than  the  dividing 
routine.  When  timed  in  the  same 
fashion  as  the  shift  and  divide  rou¬ 
tine,  it  takes  an  average  of  413 
microseconds. 

I  believe  that  the  NS320XX  is  the 
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most  powerful  microprocessor 
around.  Its  generally  symmetrical  in¬ 
struction  set  and  many  addressing 
modes  make  it  relatively  easy  to 
write  systems  software  for.  After  all, 
there  is  more  to  programming  than 
calculating  square  roots!  But  its  ap¬ 
parently  poor  showing  for  the  bit- 
shifting  routine,  relative  to  the 
M68000  (413  vs.  200  to  250  microsec¬ 
onds),  deserves  some  comments.  If 
my  two-year-old  NS16032  were  run¬ 
ning  8  MHz,  then  the  difference 
would  be  somewhat  less  (310  vs.  200 
to  250  microseconds).  Also,  the 
M68000  times  were  estimated  from  in¬ 
struction-execution  clock  cycles,  not 
with  an  actual  test  program;  calculat¬ 
ing  instruction-execution  times  "in 
vivo"  for  sophisticated  microproces¬ 
sors  such  as  the  NS320XX  or  the  M68000 
is  not  an  easy  task. 

In  any  event,  this  short  test  and  bit- 
shifting  algorithm  does  hit  the 
NS320XX  below  the  belt  in  two  ways. 
First,  the  NS320XX  has  a  single  look¬ 
ahead  instruction  queue  that  may  ac¬ 
tually  cost  time  when  executing 
short  loops  or  frequent  branches; 
this  short,  14-instruction  routine  has 
to  loop  16  times  and  may  branch  up 
to  16  times.  Second,  it  does  not  have  a 
simple  bit-setting  instruction  for  the 
efficient  movement  of  single  bits 
from  a  data  or  flag  register  to  anoth¬ 
er  register.  The  first  problem  is  prob¬ 
ably  inherent  in  its  design,  but  the 
second  is  a  less  serious  design  or  doc¬ 
umentation  oversight. 

This  little  exercise  has  further  con¬ 
vinced  me  that  you  are  better  off  pro¬ 
gramming  at  a  level  where  the  logic 
of  a  program  is  evident.  This  is  partic¬ 
ularly  true  with  a  modern  micropro¬ 
cessor  such  as  the  NS320XX.  I  would 
urge  anyone  working  with  such  a  mi¬ 
croprocessor  to  forget  about  the  bit- 
level  tricks  necessary  with  8-bit  pro¬ 
cessors  and  take  a  fresh  and  rational 
approach  to  programming. 


DDJ 


(Listings  begin  on  page  106.) 
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OF  INTEREST 


To  write  a  program  of 
moderate  size  that  works  as 
soon  as  it's  compiled  is  a 
programming  feat.  Pro¬ 
grammers  understand  the 
need  for  debugging  tools  in 
the  same  way  that  an  engi¬ 
neer  understands  the  need 
for  an  oscilloscope.  Unfor¬ 
tunately,  programmers 
generally  have  available 
only  the  most  rudimentary 
debugging  facilities. 

To  help  programmers 
out  of  the  morass  of  loads, 
stores,  jumps,  and  bit-fon¬ 
dling,  Meridian  Software 
Systems  has  developed  an 
interactive  system-inde¬ 
pendent  source-level  de¬ 
bugger  for  use  with  its  Pas¬ 
cal  compiler.  It  supports 
conditional  breakpoints, 
subprogram  traces,  single¬ 
stepping,  and  full  Pascal 
variable  reference  syntax. 

TurboRef,  a  software 
tool  package  for  Pascal  us¬ 
ers,  is  available  from  Gra- 
con  Services.  TurboRef  lists 
each  variable  and  constant 
reference  in  a  user's  pro¬ 
gram.  The  list  includes  the 
line  number  and  type  of 
use  for  each  reference.  It 
can  read  multiple  source 
files  and  process  "include” 
files.  A  program  listing  can 
also  be  created.  The  prod¬ 
uct  runs  on  an  IBM  PC  with 
128K  memory  and  re¬ 
quires  PC  DOS  2.00.  The 
price  is  $49.95. 

The  SPS  C/Atlas  compila¬ 
tion  system  from  Software 
Products  &  Services  is 
modularized  to  enable  the 
installation  of  a  total  sys¬ 
tem  or  only  those  elements 
that  are  needed  to  round 


out  or  upgrade  an  existing 
capability.  The  system  con¬ 
sists  of  a  front-end  compil¬ 
er,  syntax-oriented  editor, 
code-generator  compiler, 
TDL  processor,  adaptation 
list  generator,  device  and 
switch  allocation  system, 
test  and  debug  package, 
and  consistency  checker. 

ProMod,  an  integrated 
systems  engineering  envi¬ 
ronment  from  Promod 
Inc.,  supports  the  complete 
software  life  cycle  on  PCs 
as  well  as  minicomputer 
systems.  Versions  are  avail¬ 
able  for  IBM  PCs  having 
512K  of  memory  and  10- 
Mb  hard-disk  storage  and 
DEC  VAX  systems  operating 
under  VMS. 

Version  1.0  of  P-TRAL  is  a 
language  translator  that 
enables  programmers  to 
convert  Applesoft  BASIC 
programs  to  Pascal.  It  reads 
the  BASIC  source  program 
from  disk  and  generates 
the  equivalent  Pascal 
source  code.  System  re¬ 
quirements  include:  64K  to 
128K  memory,  80-column 
display,  two  disk  drives, 
and  Apple  DOS  3.3/Apple 
Pascal  1.1, 1.2, 1.3.  P-TRAL  is 
available  from  Woodchuck 
Industries. 

Cipherlink  Corp.  has  in¬ 
troduced  Calculations  Pe¬ 
ripheral,  a  software  pack¬ 
age  that,  when  used  with 
Any  bridge  software, 
translates  data  between  in¬ 
compatible  computers. 
The  Any  data  bridge  re¬ 
sides  on  an  independent 
computer  connected  to  the 
source  and  target  comput¬ 
ers  through  a  terminal 
port.  It  acts  as  a  bridge  be¬ 
tween  applications,  ex¬ 
tracting  a  desired  data  field 
from  a  source  application, 
transferring  it  to  an  inter¬ 
mediate  database,  and 
then  automatically  rekey¬ 
ing  the  data  into  the  appro¬ 
priate  field  in  the  target  ap¬ 


plications.  Calculations 
Peripheral  will  run  on  any 
PC  DOS  or  Unix-based 
computer. 

A  three-part  software 
package  for  analyzing  and 
managing  the  IBM  PC  Net¬ 
work  is  available  from 
Bickley  Utilities.  Net  Set 
prompts  the  user  interac¬ 
tively  for  information  con¬ 
cerning  the  network  and 
generates  definitions  for 
the  complex  parameters 
involved  in  the  Net  Start 
command.  Net  Stat  is  the 
on-line  network  statistics- 
gathering  module. 

The  Omni  64  from  Oliver 
Advanced  Engineering  is 
plug-compatible  with  over 
300  computers  and  operat¬ 
ing  systems.  It  has  65,536 
bytes  of  RAM,  expandable 
to  262,144  bytes,  and  an  un¬ 
limited  firmware  data¬ 
base.  The  product  comes 
with  eight  logical  buffers 
that  can  be  configured  to  a 
different  depth  (to  256K 
words)  and  width  (to  64 
bits)  to  correspond  with  up 
to  eight  different  program¬ 
mable  devices.  The  Omni 
64  uses  a  6-MHz  280B  pro¬ 
cessor  to  synchronize  the 
processor  to  the  wave¬ 
forms  being  produced. 

The  Local  Applications 
Bus,  LAB  40,  is  a  microcom- 
puter-to-peripheral  inter¬ 
face  and  a  hardware  devel¬ 
opment  system  available 
from  Computer  Continu¬ 
um.  LAB  40  is  a  structured 
parallel  port  that  takes  16K 
memory  or  I/O  locations  in 
the  host  computer.  It  can 
drive  up  to  64  8-bit  input 
ports  and  64  8-bit  output 
ports. 

AT  SpeedFixer  is  a  soft¬ 
ware  utility  package,  avail¬ 
able  from  Dynamical  Sys¬ 
tems.  It  features  a 
memory-resident  disk  util¬ 
ity  designed  to  prevent 
floppy  disk  drive  errors 
and  a  keyboard  utility  that 


increases  the  speed.  The 
price  is  $24.95. 

C.  Itoh  Products  has  in¬ 
troduced  two  high-resolu¬ 
tion  RGB  monitors.  The 
CM1000  features  both  com¬ 
posite  and  RGB  capability 
and  a  full-range  audio 
speaker.  In  composite 
mode,  it  provides  a  320  X 
240  resolution  with  a  4- 
MHz  bandwidth;  in  RGB, 
the  resolution  jumps  to  640 
X  240  with  a  15-MHz  band¬ 
width.  The  CM2000  fea¬ 
tures  a  nonglare  black 
screen  and  is  designed  to 
be  plug-compatible  with 
the  IBM  PC,  XT,  and  AT  as 
well  as  the  Apple  He  series. 

A  four-channel  Multibus 
single-board  computer  de¬ 
signed  for  sophisticated 
data  communication  pro¬ 
cessing  is  available  from 
SBE  Inc.  The  COM-4  has  two 
10-MHz  user-programma¬ 
ble  DMA  controllers  that 
provide  each  of  the  four 
on-board  serial  ports  with 
two  channels  of  DMA. 
These  channels  transmit 
and  receive  blocks  of  data 
to  and  from  on-board  RAM 
memory.  The  on-board 
memory  is  dual-ported,  al¬ 
lowing  data  to  be  accessed 
from  either  the  local  bus  or 
Multibus. 

Communication  Machin¬ 
ery  Corp.  has  announced 
the  ENP-60,  a  high-perfor¬ 
mance  intelligent  front-end 
processor  on  a  single  board. 
The  board  runs  the  com¬ 
munication  protocols  re¬ 
quired  for  the  IBM  PC/AT  to 
communicate  to  other  de¬ 
vices  on  Ethernet.  The  ENP- 
60  also  runs  TCP/IP  soft¬ 
ware  as  well  as  the  Fusion 
higher-level  protocol  soft¬ 
ware  for  XNS.  MS  DOS  and 
Xenix  are  also  supported. 

A  Virtual  RAM  (VRAM) 
card,  designed  to  increase 
the  capabilities  and  perfor¬ 
mance  of  the  Waterloo  Port 
Network  Operating  Sys- 
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tern,  is  available  from  Wa¬ 
terloo  Microsystems. 
Equipped  with  a  VRAM 
card,  a  port  workstation 
can  run  640K  DOS  applica¬ 
tions,  concurrently  access 
network  services,  send 
mail,  and  perform  terminal 
emulation  and  other  multi¬ 
tasking  applications.  The 
VRAM  card  is  a  full-length 
board  with  512K  of  RAM, 
expandable  to  1  Mb.  It  oper¬ 
ates  with  the  IBM  PC,  XT,  AT, 
and  compatibles  at  speeds 
up  to  8  MHz.  The  price  is 
$695  ($995  in  Canada). 

The  GL  Serial  Card  from 
Microtek  provides  a  two- 
way  serial  interface  to  al¬ 
low  the  IBM  PC/XT  to  com¬ 
municate  with  a  variety  of 
serial  peripheral  devices.  It 
is  functionally  equivalent 
to  the  IBM  asynchronous 
communication  adapter 
and  supports  all  software 
designed  to  run  with  this 


card  on  the  IBM  PC/XT. 

Quepro*  Version  1.5,  en¬ 
ables  managers  to  analyze 
data  files  using  programs 
such  as  Lotus  1-2-3,  dBASE 
III,  and  MailMerge.  Avail¬ 
able  from  Bytel  Corp.,  the 
new  version  permits  users 
to  generate  gd  hoc  queries 
and  reports  without  the 
need  for  programmer  as¬ 
sistance.  It  can  be  used  as  is 
with  files  generated  using 
the  Cogen  COBOL  program 
generator  or  customized 
by  the  developer  of  any 
COBOL  program.  Version 
1.5  is  priced  at  $595  for  MS 
DOS  systems,  $785  to  $1,550 
for  most  Unix-based  sys¬ 
tems,  and  $1,550  to  $9,500 
for  NCR  and  large  Unix 
systems. 

Ampere  has  developed  a 
68000-based  portable  com¬ 
puter  called  the  WS-1.  It  in¬ 
cludes  up  to  512K  of  RAM, 
an  80-character-25-line  LCD 


(200  X  480= dot  bit-mapped 
graphics  also  supported), 
built-in  speaker  phone, 
auto-dial  300-baud  modem, 
programmable  voice/data 
microcassette,  two  RS-232 
ports,  and  disk  I/O  exten¬ 
sion  bus.  WS-1  also  uses  a 
multitasking  operating  sys¬ 
tem  called  BIG 

.DOX.  WS-1  is  available  from 
Workspace  Computer. 

Boston  Business  Comput¬ 
ing  has  introduced  the  PC/ 
EDT,  a  PC  implementation 
of  BAX  EDT,  the  de  facto 
Digital  mainframe  editor.  It 
features  multiple  buffers, 
undelete,  keyboard  redefi¬ 
nition,  command  macros, 
multiple  file  access,  cut 
and  paste,  screen  and/or 
keyboard  command 
modes,  command  files, 
and  environmental  vari¬ 
ables.  It  supports  DOS  2.0 
and  above  as  well  as  the 
full  DOS  directory  struc¬ 


ture.  The  program,  priced 
at  $220,  requires  a  single 
disk  drive  and  128K 
memory. 

A  down-size  201C  mo¬ 
dem  that  fits  under  a  stan¬ 
dard  telephone  is  available 
from  Emerald  Technology 
Group.  The  201C  features 
digital  signal  processing 
under  microprocessor  con¬ 
trol.  It  is  designed  for  use 
on  switched  lines  and  in¬ 
cludes  circuitry  for  auto¬ 
answer  operation.  The  mo¬ 
dem,  priced  at  $685,  also 
incorporates  several  diag¬ 
nostic  test  functions  in¬ 
cluding  loopback,  random- 
bit  test  patterns,  and 
self-test. 

Turn-On  is  an  intelligent 
power  controller  from 
Dynatech  that  provides  un¬ 
attended  remote  access 
plus  power  protection.  It 
features  automatic  log-on 
three-phase  security:  user 
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ID,  password  protection, 
and  optional  dial-back  con¬ 
firmation. 

IBM  PC 

The  ConCur  400,  an  ad¬ 
vanced  adapter  board  that 
transforms  single-user  pro¬ 
grams  into  multiterminal 
programs,  is  available 
from  Vaxon.  The  board 
provides  noninterlaced 
video  for  flicker-free  dis¬ 
play  and  720  X  348  mono¬ 
chrome  high-resolution 
graphics  with  an  IBM  mon¬ 
itor  or  640  X  400  with  a 
Princeton  SR-12  or  compat¬ 
ible  monitor.  It  runs  on  the 
IBM  PC,  XT,  AT,  and 
compatibles. 

Expert  Edge  is  an  expert 
system  builder  that  can  be 
used  to  develop  interactive 
knowledge-based  pro¬ 
grams  for  the  IBM  PC.  It  uses 
a  deductive  reasoning 
(backward  chaining)  infer¬ 
ence  engine  to  generate  ex¬ 
pert  advice  or  to  solve  a 
problem  requiring  expert 
knowledge.  Starting  from 
rules  entered  by  the  expert, 
Expert  Edge  builds  an  inter¬ 
active  program,  called  an 
advisor,  that  can  then  be  re¬ 
ferred  to  by  any  PC  user. 
These  rules  can  incorpo¬ 
rate  calculations,  equations, 
logical  reasoning,  judg¬ 
ment,  facts,  and  uncertain¬ 
ties.  Features  such  as 
"True”  and  "Why"  can  fol¬ 
low  the  chain  of  logic  being 
used  forward  or  backward 
as  well  as  show  the  builder 
exactly  how  any  conclu¬ 
sion  has  been  reached.  The 
package  is  available  from 
Human  Edge  Software  and 
sells  for  $795. 

A  software  library  of 
more  than  8,800  IBM  PC 
programs  on  a  single  CD- 
ROM  disk  is  available  from 
Reference  Technology.  It 
includes  a  selection  of 
word  processors,  editors, 
database  management  sys¬ 


tems,  spreadsheets,  finan¬ 
cial  and  business  applica¬ 
tions,  communication 
programs,  math/statistical 
packages,  education  and 
music  programs,  and 
games.  The  price  is  $850. 

The  Coretape  system,  a 
tape  backup  for  the  IBM  PC, 
XT,  AT,  and  compatibles, 
comes  in  both  external  and 
internal  versions.  Each  of¬ 
fers  60  Mb  of  data  storage. 
Coretape's  data  transfer 
rate  is  90,000  bytes  per  sec¬ 
ond  with  the  tape  stream¬ 
ing  at  90  inches  per  second. 
The  system  is  available 
from  CORE  International. 

UX  Software  created  UX- 
Basic  to  service  the  IBM  PC 
and  compatibles  running 
either  the  PC  DOS  or  MS  DOS 
operating  systems.  UX-Ba- 
sic  is  compatible  with  the 
earlier  model,  Version  2.0. 
Among  its  features  are 
structured  code;  modular 
programming;  and  sequen¬ 
tial,  direct,  and  ISAM  files. 

LDR  Systems  ISONET 
package  provides  indepen¬ 
dent  implementation  of 
ISO  standards  for  open  sys¬ 
tems  interconnection.  The 
package  can  interconnect 
local  area  networks  using 
X.25  protocols.  It  is  avail¬ 
able  for  the  IBM  PC  and  a 
number  of  compatibles  in¬ 
cluding  the  Olivetti  M24 
and  the  Ericsson  PC.  It  also 
runs  on  the  Burroughs  B20 
range,  the  DEC  VAX-II,  the 
ACT  Apricot,  and  Sirvius. 

The  Capture  image  digi¬ 
tizer  board  for  IBM  PC,  XT, 
AT,  and  compatibles  is 
available  from  Genoa  Sys¬ 
tems  Corp.  The  board  al¬ 
lows  users  to  capture  an 
image  from  a  standard  RS- 
170  video  input,  such  as  a 
camera.  The  captured  im¬ 
age  frame  is  then  stored  in 
on-board  memory.  The  ac¬ 
quired  image  can  also  be  si¬ 
multaneously  displayed  on 
any  composite  graphics  or 
TV  monitor  or  printed  on  a 
standard  graphics  printer. 
The  bit-mapped  display 


supports  high-screen  reso¬ 
lution  of  512  X  512  pixels. 
A  frame  memory  of  256K 
X  8  bits  allows  graphics 
overlay  requiring  an  ad¬ 
dress  space  of  only  64K. 

C,  Unix,  and  Xenix 

Computer  Innovations  an¬ 
nounced  a  C  compiler  for 
use  with  Digital  Equipment 
Corp.’s  VAX  systems  (run¬ 
ning  under  VMS)  to  develop 
ROM  code  for  the  Intel  fam¬ 
ily  of  microprocessors.  The 
C86  ROM-C  compiler  con¬ 
sists  of  a  four-pass  C  com¬ 
piler  that  emits  Intel-8086 
family  object  or  assembler 
code,  with  code-genera¬ 
tion  options  for  80186  and 

80286  processors  and  8087- 

80287  math  coprocessors. 
Full  library  source  code 
and  an  object  module 
translator  program  are 
also  included. 

Information  Processing 
Techniques  Corp.  an¬ 
nounced  revisions  of  two  C 
language  development 
tools:  Tracer  for  C  debug¬ 
ging  and  C68K  C  Cross 
Compiler  for  the  Motorola 
68000  environment.  Revi¬ 
sion  3.0  of  Tracer  features 
interactive  run-time  de¬ 
bugging.  Revision  2.0  of 
C68K  includes  the  68010 
and  68020  as  target 
processors. 

Unibol  from  Software 
Ireland  Ltd.  is  a  commer¬ 
cial  programming  lan¬ 
guage  for  Unix  operating 
systems.  It  allows  existing 
DIBOL-83  programs  to  run 
under  Unix  System  III,  Sys¬ 
tem  V,  and  those  look- 
alikes  supporting  the  full 
range  of  system  calls  and 
providing  the  C  standard 
I/O  library.  The  package 
consists  of  a  compiler,  a 
run-time  interpreter,  a 
symbolic  debugger,  and  a 
library  of  exterhal  utility 
subroutines. 

UniPress  Software  an¬ 
nounced  software  prod¬ 
ucts  for  the  IBM  PC/AT  run¬ 
ning  the  Xenix  operating 


system.  Uniplex  II's  inte¬ 
grated  office  automation 
package  offers  word  pro¬ 
cessing,  spreadsheet,  and 
relational  database  facili¬ 
ties.  Softkeys  display  avail¬ 
able  editing  options  in  all 
the  components.  UniPress 
EMACS  is  a  multiwindow 
full-screen  editor  that  in¬ 
cludes  high-level  program¬ 
ming  aids  and  is  extensible 
by  user-defined  macros 
and  the  built-in  compiler 
MLISP  programming  lan¬ 
guage.  Q-Calc  interfaces 
with  the  Unix  environ¬ 
ment  through  pipes  and 
filters  and  allows  users  to 
create  command  scripts 
for  spreadsheet  routines. 

Reference  Map 

Bickley  Utilities  (The),  101 
Tyler  Ct.,  Ambler,  PA 
19002;  (215)  628-3750.  Read¬ 
er  Service  Number  16. 
Boston  Business  Comput¬ 
ing,  360  Merrimack  St., 
Lawrence,  MA  01843;  (617) 
683-7920.  Reader  Service 
Number  17. 

Bytel  Corp.,  1029  Solano 
Ave.,  Berkeley  CA  94706; 
(415)  527-1157.  Reader  Ser¬ 
vice  Number  18. 

Cipherlink  Corp.,  3807  Wil- 
shire  Blvd.,  7th  Floor,  Los 
Angeles,  CA  90010;  (213) 
387-5371.  Reader  Service 
Number  19. 

C.  Itoh  Digital  Products, 
19750  S.  Vermont  Ave.,  Ste. 
220,  Torrance,  CA  90502; 
(213)  327-2110.  Reader  Ser¬ 
vice  Number  20. 
Communication  Machin¬ 
ery  Corp.,  1421  State  St., 
Santa  Barbara,  CA  93101; 
(805)  963-9471.  Reader  Ser¬ 
vice  Number  21. 

Computer  Continuum,  75 
Southgate  Ave.,  Ste.  6,  Daly 
City,  CA  94015;  (415)  755- 
1978.  Reader  Service  Num¬ 
ber  22. 

Computer  Innovations,  980 
Shrewsbury  Ave.,  Tinton 
Falls,  NJ  07724;  (800)  922- 
0169.  Reader  Service  Num¬ 
ber  23. 

CORE  International,  7171  N. 


Dr.  Dobb's  Journal,  March  1986 


126 

228 


Federal  Hwy.,  Boca  Raton, 
FL  33431;  (305)  997-6044. 
Reader  Service  Number  24. 
Dynamical  Systems,  2511 
Fulton  St.,  Berkeley,  CA 
94704;  (800)  227-2400.  Read¬ 
er  Service  Number  25. 
Dynatech  Computer 
Power,  4744  Scotts  Valley 
Dr.,  Scotts  Valley,  CA  95066; 
(408)  438-5760.  Reader  Ser¬ 
vice  Number  26. 

Emerald  Technology 

Group,  16701  116th  NE, 
Bellevue,  WA  98004;  (206) 
462-8200.  Reader  Service 
Number  27. 

Genoa  Systems,  73  E.  Trim¬ 
ble  Rd.,  San  Jose,  CA  95131; 
(408)  945-9720.  Reader  Ser¬ 
vice  Number  28. 

Gracon  Services,  4632  Oke- 
mos  Rd.,  Okemos,  MI 
48864;  (517)  349-4900.  Read¬ 
er  Service  Number  29. 
Human  Edge  Software, 
2445  Faber  PL,  Palo  Alto, 
CA  94303;  (415)  493-1593. 


Reader  Service  Number  30. 
Information  Processing 
Techniques,  1096  E.  Mead¬ 
ow  Circle,  Palo  Alto,  CA 
94303;  (415)  494-7500.  Read¬ 
er  Service  Number  31. 

LDR  Systems  (British  Infor¬ 
mation  Systems),  845  Third 
Ave.,  New  York,  NY  10022; 
(212)  752-8400.  Reader  Ser¬ 
vice  Number  32. 

Meridian  Software  Sys¬ 
tems,  130  McCormick  Ave., 
Ste.  102,  Costa  Mesa,  CA 
92626;  (714)  754-6631.  Read¬ 
er  Service  Number  33. 
Microtek,  5555  Magnation, 
Ste.  H,  San  Diego,  CA  92111; 
(619)  569-0900.  Reader  Ser¬ 
vice  Number  34. 

Oliver  Advanced  Engineer¬ 
ing,  676  W.  Wilson  Ave., 
Glendale,  CA  91203;  (213) 
240-0080.  Reader  Service 
Number  35. 

Promod  Inc.,  22981  Alcalde 
Dr.,  Laguna  Hills,  CA  92653; 
(714)  855-3046.  Reader  Ser¬ 


vice  Number  36. 
Reference  Technology, 
1832  N.  55th  St.,  Boulder, 
CO  80301;  (800)  225-2749. 
Reader  Service  Number  37. 
SBE  Inc.,  2400  Bisso  Ln., 
Concord,  CA  94520;  (800) 
221-6458.  Reader  Service 
Number  38. 

Software  Ireland  Ltd., 
27665  Forbes  Rd.,  Laguna 
Niguel,  CA  92677;  (714)  582- 
0233.  Reader  Service  Num¬ 
ber  39. 

Software  Products  &  Ser¬ 
vices,  14  E.  38th  St.,  14th 
Floor,  New  York,  NY  10016; 
(212)  686-3790.  Reader  Ser¬ 
vice  Number  40. 

UniPress  Software,  2025 
Lincoln  Hwy.,  Edison,  NJ 
08817;  (201)  985-8000.  Read¬ 
er  Service  Number  41. 

UX  Software  Inc.,  10  St. 
Mary  St.,  Toronto,  Ont. 
M44  1P9;  (416)  964-6909. 
Reader  Service  Number  42. 
Vaxon  Inc.,  6363  Wilshire 


Blvd.,  Ste.  127,  Los  Angeles, 
CA  90048;  (213)  655-6914. 
Reader  Service  Number  43. 
Waterloo  Microsystems, 
175  W.  Columbia  St.,  Wa¬ 
terloo,  Ont.  N2L  525;  (519) 
884-3141.  Reader  Service 
Number  44. 

Woodchuck  Industries,  340 
W.  17th  St.,  #2B,  New  York, 
NY  10011;  (212)  924-0576. 
Reader  Service  Number  45. 
Workspace  Computer, 
3848  Carson  St.,  Ste.  301, 
Torrance,  CA  90503;  (213) 
540-1553.  Reader  Service 
Number  46. 


DDJ 


127 

229 


Dr.  Dobb's  Journal,  March  1986 


Dr.  Dobb’s  Journal  of 


#114  AFW  1986 
$2.95  (3.95  CANADA) 


Ibols 


Programming  in 
LISP  and  PROLOG 

An  Expert  at  Life 

The  Perils  of 
Protected  Mode 

I/O  Redirection 
for  the  Shell 


ANNUAL 


A  /  ISSUE 


j,  sonnet  uii-i 

aa^'  would  nnt  i.  " lc *  "SJisii  < 

u  a  spring  day"  j.  *  C0*»Fare 

4  scan,  »  40  **  ueil? 


W4nts  ie  cm.. 

c  co*ipare 


would 
d  to 


SCdB  *n  wsht. 


■"»*•*<***,  • 

‘d  tei  I  d 

"  Ue  an,i  1  4o  *Dt  think  Hr. 

:r%  4“  Pe  sWious.  »„ 

not  a  a  winter’ .  j 

P  c,al  one  like  (V^  0l>e  »«ns  a 

*e  Ckristaas. 


APRIL  1986 


CONTENTS 


VOLUME  11,  ISSUE  4 


Pr.Oobb's  journal  of 

Software  Tools 


ARTICLES 


Programming 
in  LISP  and 
PROLOG 

An  Expert  at  ► 

Life 


Al:  Him: — The  Bora  Kalon  Inference  Engine 

bv  Robert  Jay  Brown  III 

An  exploration  of  artificial  intelligence  techniques,  using 
USP,  PRC )!,()(.,  and  Kxpert-2. 

Al:  A  Cellular  Automation  in  E.xpert-2 

by  Jack  Park 

Jack  v  isited  our  pages  two  years  ago  with  an  expert  system 
for  predicting  the  weather.  This  little  game  could  teach 
even  more  about  A I  tools. 

Al:  Modeling  a  System  in  PHOLOti 

by  Sheldon  IX  Soflkv 

PROLOG  may  be  the  language  of  choice  for  some  very 
practical  tasks  says  the  author. 

MODIEA-2:  A  68000  Cross  Assembler — Part  I 

by  Brian  H.  Anderson 

The  first  installment  of  this  Modula-2  source  code 
assembler  for  the  68000  supplies  the  definition  modules 
and  data-flow  diagrams.  The  implementation  modules  will 
follow. 

MATH:  A  Variable  Metric  Minimizer 

by  Joe  Marasco 

The  source  code  listing  for  Marasco's  arbitrary-function 
minimizer  continued  from  last  month. 


24 


42 


46 


52 


84 


I/O  redirection  ► 
for  the  Shell 


Report  on  ^ 
Microsoft 's 
Macro 
Assembler  4.0 


COLUMNS 


C  CHEST:  Redirection — The  /dev  Directory, 
SU'ITCHAII,  and  Touch 

by  Allen  llolub 

Our  C  expert  tackles  I/O  redirection  for  his  shell  program, 
switching  the  switch  character  under  ixk  3.x.  and  a  bug  in 
mk,  and  adds  a  nice  touch  to  the  make  utility. 

16-BIT  SOFTWARE  TOOLBOX:  The  Perils  of 
Protected  Mode 

by  Ray  Duncan 

With  thousands  of  disks  in  his  customers  hands,  Ka  v 
learns  to  his  dismay  that  IBM  didn't  really  mean  it  about 
interrupt  OFF  tl  being  available.  Also:  how  to  use  the 
LaserJet  with  WordStar,  Ray  s  opinion  of  Microsoft's 
Macro  Assembler  4.0,  68000  and  8086  tricks,  and  an  MS  WXS 
tail  routine. 


18 


16 


How  to 
navigate  the 
DDJ  Forum 


FORUM 


EDITORIAL:  Charm 
by  Michael  Swaine 
LETTERS:  Parity 
by  our  readers 
CARTOON:  Strangeness 
by  Rand  Renfroe 
DDJ  ON  LINE:  What  s  up 
and  how  to  get  it 


14 


PROGRAMMERS' 

SERVICES 


OF  INTEREST:  New  I  20 
products  of  interest 
to  programmers 
ADVERTISER  INDEX:  I  ZH 
Where  to  find 
that  ad 


About  the  Cover 

t  he  l  uring  test  is  Alan  Turing's 
mythical  experiment  in  which  i 
the  interrogator  tries  to  deter 
mine  whether  the  respondent  is 
human  or  machine  strictly  on 
the  basis  of  the  respondent  s  an-  j 
svvers  to  questions  Paul  Am¬ 
brose.  who  created  the  robot 
hands  and  did  the  cover  photog¬ 
raphy,  relaxed  the  restriction  j 
that  the  interrogator  be  human. 
The  dialogue  is  Turing's. 

Tills  Issue 

Last  year's  Al  issue  which  fo- 
cused  on  brqux;  was  so  popular 
that  we  decided  to  make  il  an  an¬ 
nual  thing.  I  his  year  wo  v  e  vvid-  j 
cited  the  scope  to  include  USP 
and  Kxpert-2.  I  he  locus  is,  as  al 
ways,  on  providing  useful  tech¬ 
niques  and  code. 

\e\l  Issue 

Some  of  the  best  programming 
acts  play  to  an  audience  of  one  j 
Ijeeause  the  programmer  never  j 
learned  the  difference  between 
.1  nifty  Ixjx  of  tricks  and  a  useful 
tool  that  others  can  understand 
and  use  In  our  user  interface  de¬ 
sign  issue  we  II  talk  to  Jef  Baskin, 
the  originator  of  the  Macintosh 
project  about  designing  soft¬ 
ware  for  people  We  II  also  turn 
Jim  Edlin  ltxj.se  on  a  well-known 
software  product;  Jim  says  he's 
going  to  use  Dan  Bricklin  s  Demo 
Program  to  redesign  this  prod¬ 
uct  s  user  interface 
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EDITORIAL 


Charles  Dick¬ 
ens  printed  on 
the  front  page 
of  his  magazine, 

Household  Words,  a 
public  explanation  of 
the  breakup  of  his 
marriage.  He  told  his 
proper  Victorian 
readers  that  he  and 
Catherine  Dickens 
were  "wonderfully 
unsuited  to  one  another"  and  that  "it 
would  be  better  for  her  to  go  awav 
and  live  apart."  Magazinesare  differ¬ 
ent  now.  Living  with  someone  else  is, 
in  some  ways,  no  different:  Now,  as 
then,  the  bedrock  on  which  lives  are 
built  is  occasionally  faulty.  Like 
plates  of  the  earth's  crust,  cohabi¬ 
tants  sometimes  rub  each  other  the 
wrong  way  until  something  cracks, 
erupts,  falls  away. 

Memory-resident  utilities  under 
MS  DOS  are  also  subject  to  the  tecton¬ 
ics  of  cohabitation,  one  moment  dis¬ 
playing  a  surface  of  smoothly  over¬ 
lapping  plates  or  proper  Victorian 
tilings,  the  next  moment  falling  apart 
at  the  fault  lines.  The  DOS  terrain 
needs  a  seismologist,  or  the  DOS 
household  needs  a  marriage  counsel¬ 
or,  depending  on  where  in  these 
shifting  metaphors  you  come  to  rest. 

Remember  integrated  software? 
(There  is  a  connection  here,  1  assure 
you. I  Recent  trends  (evidenced  at  a 
utility  fair  in  San  Francisco  spon¬ 
sored  by  800  Software  and  Computer 
Currents  magazine)  suggest  that  users 
soon  may  he  offered  "integrated  soft¬ 
ware"  in  a  new  form:  bundled  mem¬ 
ory-resident  utilities.  Traditional  in¬ 
tegrated  packages  no  longer  enjoy 
the  vogue  they  once  did,  in  part  be¬ 
cause  they  forced  consumers  and  de¬ 
velopers  either  to  accept  inadequate 
tools  because  they  were  inextricably 
bound  to  better  tools  or  to  reject 
whole  packages. 

Small  utility  programs,  as  contrast¬ 
ed  with  monolithic  integrated  pack¬ 
ages,  have  many  virtues:  They  give 
the  user  a  choice,  they  provide  a 


chance  for  smaller 
companies  to  start 
and  succeed,  and 
they  encourage  a 
healthier  and  more 
competitive  market 
with  more  differen¬ 
tiable  products. 
Memory-resident 
programs  put  a  pre¬ 
mium  once  again  on 
memory-efficient  de¬ 
sign,  that  is,  skillful  programming. 
Bundled  memory-resident  utilities 
may  or  may  not  limit  users’  choices, 
but  they  still  leave  it  to  consumers  to 
choose  what  products  to  ust;.  That 
freedom  is  beneficial  to  everyone. 

We  applaud  efforts  at  agreement 
on  an  open  TSR  (Terminate  and  Stay 
Resident,  that  is,  memory-resident) 
environment  and  the  concept  of 
user-integrable  software.  As  would, 
we  have  no  doubt,  Catherine 
Dickens. 


Michael  Svvaine 
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Columns 

Dear  DDJ, 

Hal  Hardenbergh’s  View¬ 
point  column  "Inefficient 
C”  (DDJ,  January  1986)  cor¬ 
rectly  points  out  the  obvi¬ 
ous — that  regardless  of  the 
arguments  high-level  lan¬ 
guage  (HLL)  advocates 
bring  to  bear,  HLL  software 
for  microcomputers  does 
not  perform  as  well  as 
good  assembly-language 
software  and  is  conse¬ 
quently  less  popular  with 
the  buying  public.  His  rea¬ 
soning  as  to  why  this  is  so  is 
valid  in  my  experience  (ex¬ 
tensive  808x  and  Z80  pro¬ 
gramming  in  both  assem¬ 
bly  and  HLL);  however,  I 
think  that  the  ongoing  de¬ 
bate  about  the  efficiency  of 
assembly  versus  HLL  is 
only  the  focal  point  of  a 
larger  issue,  which  con¬ 
cerns  the  attempt  to  man¬ 
age  the  creative  process  of 
software  development.  Af¬ 
ter  all,  why  has  such  an  ac¬ 
rid  debate  arisen  on  a  topic 
about  which,  as  Mr.  Har- 
denbergh  has  pointed  out 
in  DTACK  Grounded,  there 
can  be  little  doubt  (for  mi¬ 
crocomputers,  at  least)?  Be¬ 
cause  standard  manage¬ 
ment  practices  and  corpo¬ 
rate  dynamics  make  it  very 
difficult  to  follow  the  soft¬ 
ware  development  ap¬ 
proach  required  to  pro¬ 
duce  good  assembly 
programs. 

From  a  management 
perspective,  software  de¬ 
velopment  falls  into  an  odd 
area  somewhere  between 
creative  and  technical 
writing.  Technical  writing 


can  be  outlined,  broken 
into  blocks,  and  imple¬ 
mented  by  many  writers 
because  it  is  a  description 
of  something  that  already 
exists  in  finished  form. 
However,  it  would  be  fool¬ 
ish  to  attempt  to  do  the 
same  with  a  novel  because 
writing  a  novel  is  a  cre¬ 
ative  act.  Even  if  the  au¬ 
thor  could  fully  outline  the 
novel,  no  team  of  writers 
could  make  it  come  togeth¬ 
er;  no  matter  how  well 
each  wrote  his  or  her  indi¬ 
vidual  sections,  the  parts 
would  not  cohere.  Soft¬ 
ware  development  has  ele¬ 
ments  of  both  sorts  of  writ¬ 
ing  in  that  it  requires 
careful  organization  yet  is 
essentially  a  creative 
process. 

It  is  easy  to  fall  into  the 
trap  of  viewing  software 
development  as  only  a 
kind  of  technical  writing. 
After  all,  if  you  ask  a  nov¬ 
ice  programmer  to  write  a 
program  that  prints  out 


the  squares  of  the  integers 
less  than  ten,  he  will  deliv¬ 
er  a  working  program 
much  like  the  ones  written 
by  any  other  programmer. 
By  extension,  program¬ 
ming  becomes  a  basically 
mechanical  task  of  imple¬ 
menting  an  already-deter¬ 
mined  solution,  with  the 
creative  work  completed 
when  the  program  specifi¬ 
cation  is  finished.  All  too 
often  the  specification  is 
developed  by  people  who 
are  not  even  expert  pro¬ 
grammers,  the  perception 
being  that  creation  and  im¬ 
plementation  are  separate 
parts  of  software 
development. 

This  is  a  critical  misper¬ 
ception.  Good  microcom¬ 
puter  software  results 
from  a  development  pro¬ 
cess  in  which  the  creative 
element,  the  implementa¬ 
tion,  and  the  underlying 
hardware  must  work  to¬ 
gether  throughout  the  de¬ 
velopment  process. 


The  best  microcomputer 
software  is  written  in  as¬ 
sembly  language  under  a 
single  unifying  vision.  Both 
the  vision  and  assembly 
language  are  essential  to  al¬ 
low  the  best  matching  of 
the  application,  via  the 
code  and  data  structures, 
to  the  underlying  architec¬ 
ture  of  the  computer.  As 
Mr.  Hardenbergh  indi¬ 
cates,  it  is  this  marriage  of 
software  and  hardware 
that  makes  assembly  pro¬ 
grams  superior.  Good  as¬ 
sembly  software  can  only 
be  implemented  so  long  as 
the  vision  can  be  shared 
and  common  elements 
fully  communicated 
among  the  entire  team.  Be¬ 
cause  communications 
breakdown  is  the  bottle¬ 
neck,  ideally  one  and  nev¬ 
er  more  than  an  absolute 
minimum  number  of  pro¬ 
grammers  should  be  in¬ 
volved  in  any  one  project. 

Given  that  the  best  soft¬ 
ware  is  written  in  assembly 
by  a  very  few  program¬ 
mers,  why  do  so  many 
companies  end  up  using 
HLL?  A  number  of  factors 
force  large  and  growing 
software  companies  into 
using  HLL  (and  in  this  indus¬ 
try,  there  are  generally 
only  large,  growing,  and 
dying  software  companies): 

1.  The  need  to  deal  with 
the  inevitable  turnover  of 
employees.  This  virtually 
mandates  HLL  because  it  is 
difficult  to  maintain  some¬ 
one  else’s  assembly  code. 
Exacerbating  this  is  the 
tendency  of  good  software 
developers  to  move  on  to 
more  interesting  projects 
(and  companies). 

2.  The  preference  for 
cheap  labor.  In  rapidly 
growing  companies,  the 
tendency  is  to  add  a  second 
tier  of  programmers — of¬ 
ten  right  out  of  school — 
who  are  paid  much  less 
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than  the  original  group. 
These  people  are  truly  pro¬ 
grammers  rather  than  soft¬ 
ware  developers,  rarely 
have  any  experience  with 
assembly  language  (or 
even  with  micros),  and  are 
often  brainwashed  with 
the  doctrine  of  HLL  superi¬ 
ority.  It  takes  considerable 
experience  to  become  an 
expert  assembly  program¬ 
mer,  and  companies  be¬ 
lieve  they  can't  afford  to 
let  their  employees  learn 
on  the  job. 

3.  The  need  to  control 
employees.  The  same 
mindset  that  makes  good 
programmers  work  all 
night  when  the  company 
is  developing  that  first  ex¬ 
citing  product  leads  them 
to  follow  their  own  star 
when  they’re  bored  with 
maintaining  that  code.  Er¬ 
ratic  hours  and  behavior 
may  be  fine  when  the 
company  consists  of  a  pro¬ 
grammer  and  a  president 
in  a  single  room,  but  they 
do  not  sit  well  with  a  new¬ 
ly  minted  department 
head  who’s  trying  to  orga¬ 
nize  his  programming 
staff — and  good  program¬ 
mers  are  a  notoriously  ec¬ 
centric  bunch. 

4.  The  need  to  manage 
projects.  As  a  company 
grows,  it  accumulates  per¬ 
sonnel,  even  if  it  is  not  al¬ 
ways  clear  what  these  peo¬ 
ple  are  hired  to  do.  There 
is  the  natural  desire  of 
managers  to  exert  more  in¬ 
fluence  by  having  a  larger 
staff  and  budget,  and  there 
is  the  equally  natural  de¬ 
sire  to  hire  more  program¬ 
mers  to  produce  more 
products  and  so  cause  the 
company  to  grow  faster. 
Once  you  have  many  pro¬ 
grammers,  you  must  use 
them.  Consequently  ten  or 
more  programmers  may 
end  up  working  on  a  pro¬ 
ject  that  would  have  been 


handled  by  one  or  two  a 
year  earlier.  It  is  difficult  to 
manage  so  large  a  staff 
when  coding  in  assembly 
language.  (As  Mr.  Harden- 
bergh  pointed  out,  howev¬ 
er,  HLLs  make  it  easier  to 
manage  large  staffs  by  ob¬ 
scuring  the  architecture  of 
the  computer  and  by  limit¬ 
ing  the  tools  available  to 
the  programmer.)  Indeed, 
if  the  staff  gets  much  larg¬ 
er,  a  Unix-based  mini  and 
SCCS  will  be  required  just  to 
keep  chaos  at  bay.  To 
many  this  may  sound  fine, 
but  remember  that  I  am 
talking  only  about  a  single 
microcomputer  product 
that  could  likely  have  been 
developed  by  just  one  or 
two  talented  and  experi¬ 
enced  assembly 

programmers! 

Note  that  all  these  factors 
treat  software  developers 
as  technical  writers — cogs 
in  the  machinery  that  pro¬ 
duces  a  product — rather 
than  as  novelists — the 
source  of  the  product,  and 
the  resource  around 
which  the  company  is 
built.  Marketing,  finance, 
management,  and  so  on, 
certainly  must  also  be 
good,  but  they  are  there  to 
support  the  product,  and  it 
is  the  quality  of  the  prod¬ 
uct  that  will  define  the 
company's  long-term 
success. 

One  example  in  an  arti¬ 
cle  discussing  the  virtues  of 
Modula-2  (PC  Week,  Sep¬ 
tember  24,  1985),  MicroPro 
explained  that  it  was 
pleased  with  Modula-2  be¬ 
cause  it  had  enabled  50  peo¬ 
ple  to  write  Easy  its  new 
low-end  word  processor,  in 
only  nine  months.  Every¬ 
one  in  the  audience  who 
thinks  that  they  and  the  ex¬ 
perienced  programmer  of 
their  choice  could  develop 
that  software  (apart  from  a 
full  set  of  printer  drivers, 
perhaps)  in  assembly  in 
nine  months,  raise  their 
hand.  (This  being  DDJ,  I  ex¬ 


pect  a  lot  of  hands.)  And 
would  anyone  care  to  bet 
which  version  would  run 
faster? 

The  point  is  not  to  slight 
either  Modula-2  or  Micro¬ 
Pro,  but  rather  to  indicate 
that  conventional  manage¬ 
ment  inexorably  drives 
corporate  software  devel¬ 
opment  in  such  a  way  that 
a  company  can  be  pleased 
by  the  somewhat  absurd 
outcome  of  getting  a  low- 
end  product  from  dozens 
of  highly  paid  people  in 
nine  months.  The  need  for 
HLLs  is  merely  one  result  of 
this  process. 

In  short,  the  develop¬ 
ment  of  good  microcom¬ 
puter  software  is  not  ame¬ 
nable  to  standard 
management  practices. 
Good  software  developers 
are  not  just  implementers, 
and  likewise,  good  soft¬ 
ware  is  not  just  the  imple¬ 
mentation  of  a  concept — 
the  concept,  the  software, 
and  the  hardware  together 
form  a  whole.  The  current 
debate  about  C  versus  as¬ 
sembly  is  primarily  a  re¬ 
flection  of  that  reality.  If 
software  written  in  C  were 
really  as  efficient  as  that 
written  in  assembly  then 
management  would  have 
their  way,  and  the  issue 
would  be  moot.  Because 
managers  must  manage 
and  because  HLLs  lend 
themselves  to  standard 
management,  a  great  deal 
of  effort  has  gone  into  be¬ 
lieving  that  this  is  true.  Be¬ 
cause  it  isn’t,  management 
often  ends  up  wondering 
why  superbly  managed 
projects  produce  mediocre 
software.  It's  not  that  man¬ 
agement  techniques  aren’t 
applied  thoroughly 
enough — it’s  a  fundamen¬ 
tal  clash  between  those 
techniques  and  the  nature 
of  computers  and  creativ¬ 
ity.  This  does  not  mean 
that  the  development  of 
good  software  cannot  be 
managed,  scheduled,  and 


otherwise  integrated  into 
the  corporate  structure;  it 
does  mean  that  innovative 
management  is  required  to 
support  the  special  nature 
of  software  development. 

Michael  Abrash 

6  Remy  PI. 

Newtown,  PA  18940 

Dear  DDJ, 

In  his  January  column, 
Ray  Duncan  states: 

"I  put  the  people  who 
upload  such  programs  to 
public  BBSs  in  the  same  cat¬ 
egory  as  terrorists.” 

I,  too,  deplore  this  con¬ 
duct.  Nonetheless,  to  com¬ 
pare  the  loss  of  a  disk  of 
data  to  the  murder  of  19 
humans  is  inappropriate. 

By  the  way,  in  your 
search  for  good  colum¬ 
nists,  may  I  suggest  Hal 
Hardenbergh?  Even 
though  he  does  not  have 
the  time  to  write  DTACK 
Grounded  any  longer,  he 
may  have  time  to  do  a  col¬ 
umn.  His  opinions  are  al¬ 
ways  interesting,  even  if 
misguided.  (I  have  the  sys¬ 
tem  he  most  maligns- — I 
program  in  C  on  a  Berke¬ 
ley  4.2  Unix  system  with  a 
National  Semi  16032  CPU — 
and  I  still  like  to  read  Hal!) 

Ivan  Strand 

145  Del  Mar  Ave. 

Berkeley  CA  94708 

We've  been  hounding  Hal 
Hardenbergh  for  two  years 
to  write  for  us.  Maybe  your 
letter  will  help.  Maybe  spell¬ 
ing  his  name  correctly 
(which  we  failed  to  do  in 
January)  will  help. — ed. 

BANKSWAP 

Dear  DDJ, 

Albert  Woodhull’s  article, 
"BANKSWAP”  (December 
1985),  illustrating  the  use  of 
the  CP/M  3  RSX  procedure 
for  extending  the  DRI  DDT 
and  SID  utilities  so  they  can 
be  used  to  explore  banks 
other  than  Bank  1,  prom¬ 
ises  to  be  useful.  I'd  like  to 
comment  on  a  few  points 
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made  by  Mr.  Woodhull  in 
the  article. 

First,  user  programs  can 
indeed  access  memory  in 
alternate  banks.  Advanced 
Logic  Systems,  in  BIOS  ver¬ 
sion  3.01B1  and  later  (also 
older  ones?),  provided  two 
new  BIOS  functions  to  al¬ 
low  reading  and  writing  to 
the  regular  Apple  memo¬ 
ry.  Regular  Apple  memory 
is  Bank  0  in  the  CP/M  3  im¬ 
plementation  that  ALS  and 
DRI  came  out  with  for  the 
ALS  CP/M  Card.  These  new 
BIOS  functions  are  num¬ 
bers  33  (APREAD)  and  34 
(APWRITE).  In  the  ALS 
3.01B2  upgrade  and  the 
public  domain  CP-PLUG 
3.02B  BIOS  derived  from 
the  ALS  3.01B2  version,  a 
third  additional  BIOS  func¬ 
tion,  number  35  (CAPPLE) 
that  allows  calls  to  be  made 
to  a  Bank  0  (Apple  memo¬ 
ry)  address,  was  added. 

The  routine  in  Table  1, 
below,  can  be  inserted 
early  in  a  program  to  set 
local  jumps  to  the  BIOS  for 
interbank  read,  write,  and 
(if  implemented)  call  oper¬ 
ations.  I  first  saw  the  rou¬ 
tine  published  by  the 
short-lived  and  now  de¬ 
funct  CP/M  Plus  Users 
Group  (CP-PLUG).  You  will 
find  it  used  in,  for  exam¬ 
ple,  code  for  MDM7xx  and 
IMP  overlays  for  the  ALS 
CP/M  Card.  To  use  these 
the  Apple  Bank  0  address 
being  read,  written  to,  or 
called  to,  must  be  in  HL 
and  no  remapping  is  nec¬ 
essary.  The  byte  written  to 
or  read  from  this  Apple  ad¬ 
dress  must  be  in  (APWRITE) 
or  is  returned  to  (APREAD) 
the  Accumulator. 

As  an  example,  to  ring 
Apple's  bell  one  needs  to 
call  to  Apple  II  location 
FF3A.  Thus,  to  do  that  from 
CP/M: 

ORG  0100H 


CALL  APINIT 
LXI  H,OFF3AH 
CALL  CAPPL 
RET 

APINIT:  (etc.) 


You  can  also  do  this  us¬ 
ing  the  direct  BIOS  call  con¬ 
vention,  which  makes  use 
of  BDOS  function  number 
50.  Use  BIOS  function  num¬ 
bers  33,  34,  and  35  for 
reads,  writes,  and  calls, 
respectively. 

The  second  point  to  be 
made  is  illustrated  by  the 
simple  bell-ringer  pro¬ 
gram.  It  is  under  some  cir¬ 
cumstances  possible  to  exe¬ 
cute  programs  in  which 
code  is  in  a  different  bank 
from  Bank  1,  and  in  the  ex¬ 
ample  shown,  the  execu¬ 
tion  happens  also  to  be  via 
6502  code  executed  by  the 
Apple  6502  CPU.  I've 
uploaded  to  a  few  RCP/M's 
a  library  file  called  AP- 
+  BRUN.LBR,  which  in¬ 
cludes  a  program  that  al¬ 
lows  some  Apple  II  binary 
executable  programs  to  be 
converted  into  a  CP/M  pro¬ 
gram  that,  when  the  CP/M 
program  is  run,  loads  the 
binary  into  Bank  0  and 
then  calls  to  it  to  execute  it. 


In  this  way  for  example, 
disk  macros  that  the  Videx 
Keyboard  Enhancer  pro¬ 
duces  on  an  Apple  II  DOS 
3.3  disk  can  be  trans¬ 
formed  into  a  CP/M-execut- 
able  file  on  an  Apple  II  CP/ 
M  disk.  Thus  they  can  be 
downloaded  while  in  the 
CP/M  environment. 

Finally,  the  bank-switch¬ 
ing  BIOS  function  (SELMEM) 
is  accessible  but  one  must 
call  it  from  common  mem¬ 
ory.  The  RSX  approach  to 
scaling  the  heights  to  com¬ 
mon  memory  is  one  way 
of  doing  it;  another  way  is 
simply  to  have  the  pro¬ 
gram  relocate  bank¬ 
switching  code  there  that 
maintains  relations  with 
the  program  that  is  operat¬ 
ing  in  Bank  1. 

For  those  who  have  the 
ALS  CP/M  Card,  revision  B, 
the  "B"  and  "C”  BIOS  revi¬ 
sions  all  seem  to  put  the 
start  of  common  memory 
at  6000H. 

The  points  I  raise  are  rel¬ 
atively  minor.  I  think  read¬ 
ers  who  may  have  the  ALS 
CP/M  Card  and  have  won¬ 
dered  how  to  do  interbank 
accesses  may  be  interested 
in  the  APINIT:  routine. 

My  appreciation  to  Al¬ 
bert  Woodhull  and  to  DDJ 
for  the  "BANKSWAP” 


APINIT: 

LHLD 

0001 

;get  bios  pointer  to  warm  boot 

LXI 

D,20H*3 

; offset  32  more  jumps  to  APREAD 

jump 

DAD 

D 

;add  them 

SHLD 

APRD+1 

;store  APREAD  jump  address 

locally 

INX 

H 

;next  jump  is  APWRITE 

INX 

H 

INX 

H 

SHLD 

APWRT+1 

;  store  that  locally 

INX 

H 

;  bump  to  CAPPLE  bios  jump  (if 

implemented) 

INX 

H 

INX 

H 

SHLD 

RET 

CAPPL +1 

;store  locally 

APRD: 

JMP 

0000 

;these  are  filled  in  by  APINIT 

APWRT: 

JMP 

0000 

;other  bank  will  RET 

CAPPL: 

JMP 

0000 

Table  1 


article. 

Jerry  Levy 
1129  Dundee  Dr. 

Dresher,  PA  19025 

Help! 

Dear  DDJ, 

I  have  been  a  subscriber  to 
Dr.  Dobb  s  Journal  for 
quite  a  while  and  find  it  a 
very  useful  tool  for  my  To¬ 
shiba  T100  CP/M  system. 
However,  I  am  having 
some  difficulty  finding 
software  to  run  a  Black 
Box  model  1200H  modem 
(300/1200  bps).  Any  infor¬ 
mation  or  direction  I 
should  pursue  would  be 
most  appreciated.  Thank 
you. 

Edward  Starke 
27  Kerwick  Ct. 

North  Wales,  PA  19454 

Donations? 

Dear  DDJ, 

I  represent  a  nonprofit, 
charitable  organization 
that  uses  microcomputer 
equipment  in  virtually  ev¬ 
ery  aspect  of  its  affairs.  We 
would  be  grateful  if  your 
readers  would  consider 
contributing  additional 
equipment.  Donations  of 
this  sort  can  have  substan¬ 
tial  financial  benefits.  If 
you  are  in  a  position  to 
contribute  or  would  like 
more  information,  please 
write  or  call  (collect  if  you 
like)  (617)  495-9020. 

Robert  Epstein 
Cambridge  Center  for 
Behavioral  Studies 
11  Ware  St. 

Cambridge,  MA  02138 

Corrections 

There  were  two  errors  in 
the  diagrams  for  Alan  D. 
Wilcox  s  article,  " Bringing 
Up  the  68000 — A  First  Step  " 
(DDJ,  January  1986).  In  Fig¬ 
ure  4  on  page  66,  the  68000 
bus  request  (BR)  should  be 
pin  13.  In  Figure  5  on  page 
68,  the  lower  trace  should 
be  BEST. — ed. 
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This  month  I  would  like  to 
describe  in  greater  detail 
the  purpose  of  the  DDJ  Fo¬ 
rum  on  CompuServe,  out¬ 
line  its  structure,  and  give 
a  brief  description  of  the 
Forum  Data  Libraries. 

The  Forum  can  be 
reached  by  typing  GO 
DDJFORUM  from  any  Com¬ 
puServe  system  !  prompt. 
The  Forum,  along  with  the 
Display  Area  (GO  DDJ)  serves 
as  an  electronic  extension 
of  the  magazine.  Our  pri¬ 
mary  aim  is  to  make  avail¬ 
able  in  electronic  form 
most  of  the  programming 
code  published  in  the  mag¬ 
azine.  Other  goals  are  to 
stimulate  discussion  be¬ 
tween  our  readers  and  edi- 
tors/authors/columnists 
and  to  serve  as  a  general 
clearinghouse  for  informa¬ 
tion  of  interest  to  profes¬ 
sional  programmers. 

Forum  Architecture 
and  Features 

You  enter  the  Forum  at  the 
Function  Menu.  From  here 
you  can  access  the  Forum 
Message  Boards,  Confer¬ 
ence  Channels,  Data  Li¬ 
braries,  and  Bulletins.  In 
order  to  make  use  of  these 
features,  you  should  first 
learn  a  bit  about  the  struc¬ 
ture  of  the  Forum. 

The  Forum  is  divided 
into  seven  Sub-Topics  that 
roughly  correspond  to  ar¬ 
eas  regularly  covered  in 
the  magazine.  Associated 
with  every  Sub-Topic  are  a 
Data  Library,  a  Message 
Board,  and  a  real-time  Con¬ 
ference  Channel.  The  Data 
Library  (DL)  is  where  files 
that  come  under  the  Sub- 
Topic  are  stored.  The  user 
may  download  files  from 
the  DL  and  may  also 
upload  files  to  a  temporary 
holding  area  within  the 
DL.  These  files  are  re¬ 
viewed  by  the  sysop  and  if 
found  suitable  are  merged 


into  the  DL  itself.  We  invite 
your  contributions.  The 
Message  Board  allows  mes¬ 
sages  relating  to  the  Sub- 
Topic  to  be  exchanged. 
The  Conference  Channel  is 
where  formal  or  informal 
conferences  focusing  on 
the  Sub-Topic  are  staged. 

Here's  a  concrete  exam¬ 
ple.  In  the  Forum,  Sub- 
Topic  2  is  called  16-Bit  Tool¬ 
box.  This  Sub-Topic 
corresponds  roughly  to 
Ray  Duncan's  16-Bit  Soft¬ 
ware  Toolbox  column.  As¬ 
sociated  with  this  Sub-Top¬ 
ic  is  Data  Library  2  (DL2),  in 
which  you  can  find  the 
listings  from  Ray’s  column 
(along  with  listings  from 
similar  articles.  If  you 
want  to  leave  a  message  re¬ 
lated  to  Sub-Topic/DL2, 
you  store  that  message  un¬ 
der  Sub-Topic  2.  You  can 
also  read  threads  of  mes¬ 
sages  under  Sub-Topic  2 
for  discussion  of  issues 
raised  by  Ray’s  column.  If 
we  have  a  conference  with 
Ray  it  will  be  staged  on  the 
Conference  Channel  asso¬ 
ciated  with  Sub-Topic  2. 

The  subjects  of  the  Sub- 
Topics/DLs  are  as  follows: 

0)  General — General  dis¬ 
cussion,  questions  and 
help  files. 

1)  C  Chest — C  programs 
from  articles  in  DDJ;  list¬ 
ings  from  Allen  Holub's  C 
Chest  and  Axel  Schreiner's 
Unix  Exchange  columns. 

2)  16-Bit  Toolbox — 8088/ 
8086/80286  assembly  lan¬ 
guage;  PC/MS  DOS  and  IBM 
PC  related  material;  listings 
from  Ray  Duncan’s  16-Bit 
Software  Toolbox  column. 

3)  68K  Toolbox — 68000  as¬ 
sembly  language;  pro¬ 
grams  for  the  popular  68K 
micros  (the  Mac,  Amiga, 
and  ST). 

4)  CP/M  Exchange — Z80  or 
8080  assembly  language; 
CP/M  related  material. 


5)  Pascal,  Ada,  M2 — Pro¬ 
grams  written  in  the  most 
popular  structured  lan¬ 
guages  (Pascal,  Ada,  and 
Modula-2). 

6)  Forth — Programs  writ¬ 
ten  in  Forth. 

The  files  in  the  Data  Li¬ 
braries  are  only  program 
listings,  that  is,  source  code 
listed  as  ASCII  text.  We  have 
decided  to  keep  executable 
files  in  the  DLs  to  a  mini¬ 
mum.  Our  thinking  is  that 
it  is  primarily  an  educa¬ 
tional  resource  and  that 
the  value  of  our  code  rests 
in  the  fact  that  people  can 
read  it  and  learn  from  it. 
Although  executable  files 
are  useful,  they  do  not 
teach  the  programmer 
anything. 

Starting  with  the  Janu¬ 
ary  1986  issue,  almost  all 
listings  from  each  new  is¬ 
sue  have  been  uploaded  to 
the  Forum.  We  also  have 
been  uploading  code  from 
back  issues.  The  following 
is  a  partial  list  of  these  back 
issue  listings  along  with 
other  files  contributed  by 
Forum  members.  This  list 
will  have  been  substantial¬ 
ly  expanded  by  the  time 
you  read  it. 

XFR.C — A  Christensen  pro¬ 
tocol  file  transfer  pro¬ 
gram.  Designed  for 
19. 2K  baud  "nose-to- 
nose"  transfers  be¬ 
tween  computers,  but 
also  works  very  well  in 
modem  use  at  low 
speeds.  XFR  is  compati¬ 
ble  with  most  versions 
of  Modem7.  Written  in 
Eco  C  for  a  Zorba  CP/M 
machine,  but  can  be  eas¬ 
ily  modified.  I/O  primi¬ 
tives  set  up  for  I/O 
mapped  Intel  8251A 
UART.  By  Donald 
Krantz.  From  #104  (June 
1985). 

BITMAP.C — A  package  of 


general  purpose  bitmap 
management  routines. 
Includes  makebitmap(  ), 
setbitf  ),  and  testbitf  ). 
By  Allen  Holub.  From  C 
Chest,  #104. 

CROOT.C — A  modified  ver¬ 
sion  of  the  Aztec  CII  (CP/ 
M  version)  root  module 
that  allows  that  compil¬ 
er  to  support  pipes,  re¬ 
direction,  quoted  argu¬ 
ments,  and  command- 
-line  wildcard 

expansion.  By  Allen  Ho¬ 
lub.  From  C  Chest,  #101 
(March  1985). 

ECHO.C — A  program  that 
echoes  its  arguments  to 
standard  output.  Useful 
for  testing  the  croot 
modifications  in 

CROOT.C  and  LOADER- 
.ASM.  By  Allen  Holub. 
Front  C  Chest,  #101 
(March  1985). 

GETARG.C — A  general  pur¬ 
pose  command  line 
parser.  See  also  GE- 
TARG.H  and  STOI  C.  By 
Allen  Holub.  From  C 
Chest,  #103  (May  1985). 

GETARG.H — A  header  file 
needed  to  use  the  rou¬ 
tines  in  GETARG.C.  By  Al¬ 
len  Holub.  From  C 
Chest,  #103  (May  1985). 

LOADER.  ASM— Assembly 
language  support  for 
CROOT.C.  This  routine  al¬ 
lows  you  to  chain  to  an¬ 
other  program  under 
CP/M  (to  do  an  eyed  ) 
call).  By  Allen  Holub. 
From  C  Chest,  #101 
(March  1985). 

QSORT.C — A  general  pur¬ 
pose  quicksort  routine 
modeled  after  the  Unix 
qsorti )  routine.  See  also 
SSORT.C.  By  Allen  Holub. 
From  C  Chest,  #102 
(April  1985). 

QUEUE. C — A  package  of 
general  purpose  queue 
management  routines. 
Includes  makequeue(  ), 
del-.queue( ),  enqueue!  ), 
and  dequeue! ).  By  Allen 
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Holub.  From  C  Chest, 
#104  (June  1985). 

RK4.C — Fourth  order 

Runge-Kutta  integration 
of  a  single  differential 
equation.  This  program 
along  with  RKTSTl.C, 
RK4N.C,  RKST1.C,  and 
RKST2.C  (also  in  the  DLs) 
forms  a  system  for  RK4 
integration  of  single  or 
multiple  differential 
equations.  An  excellent 
example  of  a  scientific/ 
engineering  algorithm 
for  numerical  analysis 
implemented  in  C.  By 
M.  Roberts  and  A.  Skjel- 
lum.  From  Toolbook  of 
C. 

SSORT.C  - — A  version  of 
qsort(  )  that  does  a  Shell 
Sort.  This  routine  has 
been  improved  some¬ 
what  over  the  version 


in  K  &  R  by  using  a  gap 
size  that  isn't  a  power  of 
two,  as  per  Knuth.  See 
also  QSORT.C  (in  this 
same  DL).  By  Allen  Ho¬ 
lub.  See  C  Chest,  #102 
(April  1985). 

STOI.C — A  string  to  integer 
conversion  routine  used 
by  GETARG.C  (in  this 
same  DL).  Accepts  hex, 
octal,  and  decimal  rep¬ 
resentations  and  up¬ 
dates  its  argument  to 
point  past  any  parsed 
digits.  By  Allen  Holub. 
From  C  Chest,  (May 
1985). 

DUMPF.ASM— Filter  to  pro¬ 
duce  a  formatted  dump 
in  Hex  and  ASCII.  By 
Richard  Markley.  See 
also  DUMP.C  and 
DUMP. ASM.  From  #109 
(November  '85)  16-Bit 
Software  Toolbox. 

FSTCLN.ASM — Converts  a 
word  processor  docu¬ 


ment  file  into  a  stan¬ 
dard  ASCII  text  file.  Simi¬ 
lar  to  CLEAN. ASM  and 
CLEAN.C  but  much  fast¬ 
er.  By  Ray  Duncan. 

LJ.C — Utility  to  print  a  file 
on  the  Hewlett-Packard 
LaserJet.  Prints  pages 
"2-up"  in  Landscape 
Mode.  Compatible  with 
Microsoft  C  3.0.  By  Joe 
Barnhart  and  Ray  Dun¬ 
can.  Improved  version 
of  LJ.C  from  #107  (Sep¬ 
tember  ’85)  16-Bit  Soft¬ 
ware  Toolbox. 

ASCBIN.ASM  — Subroutine 
to  convert  decimal  or 
hexadecimal  ASCII 
strings  into  their  binary 
equivalents.  By  Ray 
Duncan. 

BINASC.ASM — Subroutine  to 
convert  32-bit  binary 
number  into  an  ASCII 
decimal  string.  Includes 
a  general  purpose  32-bit 
divide  routine.  By  Ray 


Duncan.  From  #101 
(March  1985)  16-Bit  Soft¬ 
ware  Toolbox. 

BREAK. ASM  — Control- 
Break  interrupt  handler 
for  Microsoft  C  pro¬ 
grams.  By  Ray  Duncan. 
From  #107  (September 
1985)  16-Bit  Software 
Toolbox. 

BREAK. C — Demonstration 
of  the  use  of  the  Con¬ 
trol-Break  handler  in 
BREAK.ASM.  By  Ray  Dun¬ 
can.  From  #107  (Septem¬ 
ber  1985)  16-Bit  Soft¬ 
ware  Toolbox. 

CLEAN. ASM— Filter  to 
transform  a  word  pro¬ 
cessor  document  file 
into  a  normal  ASCII  text 
file.  Assembly  language 
version.  From  #108  (Oc¬ 
tober  1984)  16-Bit  Soft¬ 
ware  Toolbox.  By  Ray 
Duncan. 
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Redirection — The  /dev  Directory,  SWITCHAR,  and  Touch 


I/O  Redirection  and  /dev 

’d  been  avoiding  adding  redirec¬ 
tion  to  the  shell  ever  since  I  first 
wrote  it.  I  thought  it  was  just  too  hard 
to  do.  It  turns  out  that  I  was  wrong. 
So,  I’m  starting  out  this  month  by 
talking  about  how  redirection 
works.  I’ve  already  added  this  code 
to  the  version  of  the  shell  that  DDJ  is 
distributing. 

Let's  start  with  a  little  background. 
In  Unix  and  in  DOS,  there’s  no  differ¬ 
ence  between  a  file  and  a  device 
from  the  point  of  view  of  the  I/O  rou¬ 
tines.  That  is,  all  the  DOS  function 
calls  that  can  talk  to  a  file  can  also 
communicate  with  any  DOS  device, 
including  the  console  and  the  print¬ 
er.  Unix  supports  a  special  directory 
called  /dev  for  this  purpose.  All  de¬ 
vices  are  treated  as  files  in  the  /dev 
directory — for  example,  you  can 
send  output  directly  to  a  terminal  by 
writing  to  that  terminal  as  if  it  were  a 
file.  Each  terminal  has  a  unique 
name  associated  with  it,  such  as 
/dev/ttyOl. 

To  my  pleasant  surprise  I  discov¬ 
ered  quite  by  accident  that  DOS  sup¬ 
ports  this  same  mechanism,  though 
it  uses  its  own  device  names.  (I  wish 
they’d  document  some  of  this  stuff.) 
For  example,  you  can  tell  DOS: 

A>  type  foo  >  \devprn\ 

and  it  will  send  the  output  to  the 
printer.  Try  it.  The  mechanism  is  sup¬ 
ported  even  at  the  programming  lev¬ 
el.  You  can  go  ahead  and  open  the 


by  Allen  Holub 

printer  for  output,  and  then  write  to 
it,  by  saying: 

FILE  ’Ipr; 

Ipr  =  fopen(  "/dev/prn”,  ”w”  ); 
fprintfl  Ipr, 

'Quo  usque  tandem  abutere”  ); 
fprintfl  Ipr,  “. .  .  patientia  nostra. \n”  ); 


All  the  normal  DOS  devices  are  sup¬ 
ported — /dev/con,  /dev/coml,  and 
so  on.  Your  C  I/O  library  actually 
doesn’t  know  that  it's  writing  to  a  de¬ 
vice — it  thinks  it’s  accessing  a  file. 

The  console  I/O  functions  take  ad¬ 
vantage  of  this  mechanism.  All  the 
low-level  I/O  functions  use  a  set  of 
"file  handles”  that  are  maintained  by 
DOS.  A  file  handle  is  an  integer  value 
that's  returned  from  DOS  when  a  file 
or  device  is  opened.  This  handle  is 
then  passed  back  to  DOS  every  time 
you  want  to  communicate  with  the 
associated  file  or  device.  In  fact,  three 
file  handles  (0,  1,  and  2)  are  opened 
for  you  by  DOS  when  it  executes  your 
program.  Output  sent  to  handles  1 
and  2  goes  to  the  screen,  and  input 
from  handle  0  comes  from  the  key¬ 
board.  The  three  I/O  streams  stdin, 
stdout,  and  stderr  use  handles  0,  1, 
and  2,  respectively. 

Handles  0,  1,  and  2  aren’t  special. 
You  can  close  them  with  a  normal 
closet  )  subroutine  call.  You  can  also 
reassign  them  to  another  file  or  de¬ 
vice  by  opening  them  again.  There 
are  three  ways  to  do  this  reassign¬ 
ment.  First,  when  you  close  a  file 
with  closet  ),  it  frees  up  the  associated 
handle.  The  next  opent  )  call  will  just 
grab  the  first  available  handle — if  you 
close  handle  0,  the  next  opent  )  call 
will  use  handle  0  for  the  newly 
opened  file.  For  example,  standard  in¬ 
put  can  be  reassigned  with: 

closel  0  ); 

iflopenCElizabeth”,  0_RD0NLY)  !=  0  ) 

printfr'Couldn’t  reassign 

standard  input”); 

Here,  standard  input  is  closed.  The 


subsequent  open  call  then  uses  the 
next  available  handle,  which  will  be 
handle  0.  You  can  make  sure  the  re¬ 
assignment  worked  as  expected  by 
testing  the  return  value  from  open 
(the  new  handle)  to  make  sure  it’s  0 
(standard  input).  Though  this  method 
works  if  your  I/O  library  is  really 
Unix  compatible,  your  compiler  may 
not  duplicate  Unix  exactly. 

Another  way  of  reassigning  han¬ 
dles  is  to  use  the  dup2( )  system  call. 
The  following  example  opens  an  ex¬ 
isting  file  for  appending  and  then 
changes  standard  error  to  write  to 
that  file  rather  than  to  the  screen. 

if(  (fd  =  open(”Bennet”, 

O—WRONLY  !  0_APPEND1)  =  =  - 1  ) 

printfC'Can’t  open  Bennet\n”); 
else 

dup2(  fd,  2  ); 

The  file  Bennet  is  opened  for  write, 
and  then  file  handle  2  (standard  er¬ 
ror)  is  forced  to  reference  Bennet 
rather  than  standard  error  (with  the 
dup2( )  call).  The  file  name  can  be 
any  device,  so  if  you  had  said  /dev/ 
prn  instead  of  Bennet  then  standard 
output  would  be  sent  to  the  printer 
instead  of  to  the  screen. 

The  third  mechanism,  and  the  eas¬ 
iest  to  use,  is  the  freopent )  system 
call: 

freopen(  filename,  mode,  stream  ) 
char  ’filename,  ’mode; 

FILE  ’stream; 

The  first  two  arguments  are  the 
same  name  and  mode  that  you’d  use 
with  a  normal  fopent )  call.  Freopen 
will  change  the  indicated  stream,  as 
well  as  the  associated  file  handle,  so 
that  it  now  references  the  newly 
opened  file  instead  of  the  original 
one.  You  can  change  stderr  so  that 
the  error  output  is  sent  to  the  printer 
with  the  following: 

if(  !freopen(  "/dev/prn",  ”w”,  stderr) ) 
printfC’Can’t  reopen  stderr\n’’); 
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All  this  is  well  and  good,  but  how 
does  it  apply  to  redirection?  In  DOS, 
when  a  program  spawns  a  child  pro¬ 
cess  (that  is,  when  one  program  exe¬ 
cutes  a  second  program  with  an 
eyecf ),  fork( ),  or  spawnf )  system 
call),  the  child  process  (the  second 
program)  inherits  all  the  file  descrip¬ 
tors  (file  handles)  of  the  parent  pro¬ 
cess.  That  is,  if  you  are  writing  to  a 
file  and  you  spawn  a  child  process, 
that  child  can  continue  writing  to  the 
same  file  without  reopening  it.  This 
was  causing  problems  in  batch  file 
processing  because  it  turns  out  that 
the  child  can  also  close  files  that  be¬ 
long  to  the  parent  as  an  unwanted 
side  effect  of  a  normal  eyz'ff  )  call. 

Anyway  for  some  reason  it  had 
never  occurred  to  me  that  stdin, 
stdout,  and  stderr  (or  more  accurate¬ 
ly  the  file  handles  0,  1,  and  2)  aren’t 
special.  If  they've  been  modified 
(with  any  of  the  mechanisms  that 
I've  just  described)  to  talk  to  a  file 
rather  than  to  the  console,  they’ll  still 
be  referencing  that  new  file  when 
the  child  inherits  them.  If  the  child 
tries  to  write  to  standard  output,  the 
child  will  actually  write  to  the  file. 
So,  if  you  redirect  standard  input, 
output,  or  error  in  the  parent  process 
(in  this  case  the  shell),  the  child  pro¬ 
cess  will  have  its  equivalent  I/O 
streams  redirected  to  the  same  place. 

To  my  amazement  all  the  forego¬ 
ing  actually  works  correctly  in  DOS. 
The  code  to  implement  redirection  is 
in  Listing  One,  page  58.  Note  that  I've, 
supported  the  following  five  Unix  re¬ 
direction  modes  (DOS  supports  only 
the  first  three  of  these): 

<  file — Input  is  taken  from  the  file 
rather  than  from  standard  input. 
>  file — Standard  output  is  put  into 
the  file  rather  than  being  printed 
on  the  screen.  The  previous  con¬ 
tents,  if  any  of  the  file  are  de¬ 
stroyed. 

»  file — Same  as  >  except  that  out¬ 
put  is  appended  to  the  end  of  the 
file  if  the  file  exists. 

>&  file — Same  as  J>  except  both 
standard  output  and  standard  er¬ 
ror  are  redirected. 

>>&file — Same  as  >  >  except  both 
standard  output  and  standard  er¬ 
ror  are  redirected. 


SWITCHAR/or  DOS  3.* 

A  few  months  back  I  mentioned  the 
SW1TCHAR=  —  function.  Putting  the 
above  in  your  config.sys  file  would 
cause  the  —  to  be  used  for  command 
line  switches  rather  than  /.  The  / 
could  then  be  used  as  a  directory  sep¬ 
arator.  Unfortunately  this  feature, 
undocumented  in  DOS  Version  2.x, 
was  removed  entirely  from  Version 
3.x. 

To  some  extent,  writing  the  shell 
was  my  solution  to  this  problem,  but 
for  those  of  you  who  prefer  com¬ 
mand. com,  Tony  LiCausi  writes: 
‘Commuters  between  DOS  and  Unix, 
take  heart.  Function  call  0*37  of  INT 
0y21  still  supports  'switch  the  switch 
character.'  If  the  AL  register  is  set  to 
0,  the  function  will  return  the  cur¬ 
rent  switch  character  in  DL.  If  the  AL 
register  is  set  to  1,  the  switch  charac¬ 
ter  will  be  set  to  the  character  found 
in  DL. 

"There  have  been,  and  still  are, 
drawbacks  to  setting  the  switch  char¬ 
acter  to  something  other  than  /.  Not 
all  programs  support  the  new  char¬ 
acter.  Command.com  and  all  its  in¬ 
ternal  routines  do  accept  it,  howev¬ 
er,  as  do  Join,  Subst,  and  Format.  On 
the  other  hand,  Backup  and  Restore 
do  not  (so  be  sure  the  switch  charac¬ 
ter  is  set  to  /  when  you  run  these). 
New  versions  of  the  linker  and  so  on 
don't  support  the  switch  character 
mechanism.  Many  of  these  pro¬ 
grams,  however,  will  accept  both  / 
and  —  as  switch  characters  (for  ex¬ 
ample,  the  C  compiler  driver,  CL,  ac¬ 
cepts  both).” 

Listing  Two,  page  59,  is  a  program 
of  Tony's  that  sets  or  examines  the 
switch  character,  depending  on 
whether  a  new  character  is  specified 
on  the  command  line: 

switch — Prints  the  current  switch 
character. 

switch  c — Sets  the  switch  character 
to  c. 

I  moved  Tony’s  program  over  to 
the  Lattice  compiler  so  that  I  could 
test  it.  If  you’re  working  with  the  CI- 
C86  compiler,  you’ll  want  to  use 
sysint21(  )  rather  than  intdosl  /Func¬ 
tion  0/t37  is  still  an  undocumented 
function  so  you  can  expect  it  to  disap¬ 
pear  at  the  whim  of  Microsoft,  but  for 
now  the  program  should  be  useful. 


C  CHEST 


A  Bug  in  ink  and  a 
Touch  Utility 

A  make  utility  (called  mk )  was  printed 
in  this  column  in  August  1985.  Allen 
Orcutt  writes:  "I  discovered  that  mk 
made  an  unnecessary  null  system  call 
as  the  last  action  of  every  make.  The 
problem  is  the  for  loop  on  line  364, 
which  terminates  on  finding  a  null 
pointer  at  "'linev.  I  changed  it  to  termi¬ 
nate  on  finding  a  null  string  at  *  *  linev. 

for(  linev  = 

snode  do  —  >  this;  “linev;  linev +  +  ) 

is  the  new  line  364.” 

Michael  Yam  sent  in  a  useful  ad¬ 
junct  to  the  make  utility  a  version  of 
the  Unix  utility  touch  (Listing  Three, 
page  59).  Touch  changes  the  last-mod¬ 
ified  date  and  time  fields  to  the  cur¬ 
rent  date  and  time.  It’s  useful  for  forc¬ 
ing  make  to  behave  in  certain  ways. 
For  example,  if  you  change  nothing 
but  comments  in  a  group  of  .c  files, 
you  can  touch  all  the  .obj  files  to  stop 
make  from  remaking  the  entire  pro¬ 
gram.  If  you  touch  a  nonexistent  file, 
the  file  is  created  with  zero  length. 

Michael  writes:  "Add  a  nice  touch 
to  your  make  utility.  Note  that  in¬ 
stead  of  calling  DOS  functions  to  actu¬ 
ally  modify  a  file’s  date  and  time 
stamp,  I  indirectly  let  MS  DOS  do  the 
job  by  opening,  modifying,  and  clos¬ 
ing  the  file.” 

The  "modification”  is  really  a  NOP. 
Michael  reads  the  first  byte  from  the 
file  and  then  writes  it  back  to  the 
same  place. 

Availability 

The  redirection  routines  are  part  of 
the  shell  that  DDJ  is  currently  ship¬ 
ping  (see  advertisement,  page  122). 
All  other  code  is  available  on  Compu¬ 
Serve  (type:  go  DDJ).  DDJ 

(Listings  begin  on  page  58.) 
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BRIE 

The  Boca  Raton 
Inference  Engine 


PROLOG  has  been 
gaining  in  pop¬ 
ularity  recent¬ 
ly  partly  because  of 
the  Japanese  fifth  gen¬ 
eration  project,  in 
which  PROLOG  has 
been  chosen  as  the  pri¬ 
mary  development  language.  It's  quite  different  from 
LISP,  the  other  language  frequently  used  in  artificial  intel¬ 
ligence  research,  because  it  is  knowledge-oriented  rather 
than  procedure-oriented.  LISP  and  PROLOG  each  have  cer¬ 
tain  advantages  for  knowledge  processing  applications. 
In  this  article,  I  introduce  you  to  PROLOG  programming, 
LISP  programming,  and  the  underlying  mechanisms  in¬ 
volved  in  a  PROLOG  interpreter.  A  working  micro-PROLOG 
program  demonstrates  how  logic  programming  can  be 
used  for  database  applications.  (Micro-PROLOG  is  a  prod¬ 
uct  of  Logic  Programming  Associates,  London.)  A  work¬ 
ing  muLISP  program  is  used  to  explain  the  factoring,  reso¬ 
lution,  and  paramodulation  rules  of  inference.  (MuLISP  is 
a  trademark  of  The  Soft  Warehouse,  Honolulu.)  I  also  de¬ 
scribe  a  refinement  of  the  resolution  algorithm  that 
could  form  the  basis  for  a  viable  PROLOG  interpreter.  I 
explain  the  PROLOG  deduction  cycle  and  backtracking 
and  the  concept  of  a  programming  environment. 

What  Are  Rules  of  Inference ? 

In  the  process  of  proving  a  thing  to  be  correct  or  incor¬ 
rect,  we  normally  use  what  is  popularly  called  logic.  In 
everyday  parlance,  the  argument  used  to  prove  a  point  is 
not  always  a  valid  argument:  sometimes  incorrect  rea¬ 
soning  is  employed.  If  the  reasoning  is  incorrect,  then  the 
conclusion  could  be  incorrect.  It  is  the  goal  of  mathemati¬ 
cal  proofs  and  computer  programs  to  produce  correct 
results. 

Aristotle  was  the  first  person  to  attempt  a  formaliza¬ 
tion  of  logic,  giving  a  set  of  19  rules  that  could  be  used  to 
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formulate  a  correct,  or 
proper,  argument. 
These  rules  are  called 
syllogisms.  The  fol¬ 
lowing  example  is  tak¬ 
en  from  A.  Bundy's 
The  Computer  Model¬ 
ling  of  Mathematical 

Reasoning J 

Consider  the  argument: 

All  Ancient  Greeks  were  perfect. 

Aristotle  was  an  Ancient  Greek. 

Therefore,  Aristotle  was  perfect. 

This  is  an  instance  of  the  argument: 

All  Ps  were  Q. 

X  was  a  P. 

Therefore,  X  was  Q. 

The  above  syllogism  using  P,  Q,  and  X  is  the  Darii 
syllogism.  When  we  substitute  "Ancient  Greeks”  for 
the  variable  P,  "perfect”  for  the  variable  Q,  and  "Ar¬ 
istotle”  for  the  variable  X,  we  arrive  at  the  first 
argument. 

It  is  important  to  note  that  the  validity  of  the  syllogism 
alone  is  insufficient  to  guarantee  the  truth  of  the  conclu¬ 
sion:  the  hypotheses  must  also  be  true.  A  syllogism,  such 
as  one  of  the  19  Aristotelian  syllogisms,  is  said  to  be  a  rule 
of  inference.  In  this  article  I  concentrate  on  the  rules  of 
inference  rather  than  on  the  assumptions  about  which 
the  inferences  will  be  made. 

Aristotle's  19  syllogisms  do  not  exhaust  all  possible  ar¬ 
gument  forms,  although  until  George  Boole  invented 
propositional  logic  in  the  nineteenth  century  it  was  be¬ 
lieved  that  they  did.  Propositional  logic  allows  for  the 
construction  of  complex  hypotheses  by  using  the  connec¬ 
tives  AND,  OR,  and  NOT.  But  propositional  logic  does  not 
allow  for  the  kinds  of  substitution  that  Aristotelian  logic 
permits.  It  took  Gottlieb  Frege  to  invent  predicate  logic, 
which  combines  the  best  of  both  worlds. 


by  Robert  Jay  Brown  III 


A  rule  of  inference  is  a  procedure 
that ,  when  applied  to  a  set  of 
hypotheses ,  produces  a 
conclusion  that  logically  follows. 
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Thus,  when  we  take  the  two  statements  "All  Ancient 
Greeks  were  perfect”  and  "Aristotle  was  an  Ancient 
Greek,”  we  see  that  they  can  fit  the  form  of  the  Darii 
syllogism  if  we  set  P="Ancient  Greeks,”  Q=“perfect,” 
and  X  =  'Aristotle.”  The  conclusion,  "Therefore,  Aristotle 
was  perfect”  follows  by  substitution  into  "Therefore,  X 
was  Q.”  Thus  we  can  arrive  at  a  working  definition  of  a 
rule  of  inference:  a  rule  of  inference  is  a  procedure  that, 
when  applied  to  a  set  of  hypotheses,  produces  a  conclu¬ 
sion  that  logically  follows  from  them. 

The  process  of  finding  substitutions  like  the  above  is 
called  unification,  and  the  unification  algorithm  is  at  the 
heart  of  all  mechanized  rules  of  inference.  Given  an  algo¬ 
rithm  for  unification,  the  implementation  of  a  mecha¬ 
nized  rule  of  inference  is  mainly  a  problem  of  control. 

The  implementation  of  an  inference  engine  is  the  auto¬ 
matic  application  of  a  set  of  inference  rules  to  prove  a 
theorem.  The  purpose  of  such  an  inference  engine  may 
not  be  readily  apparent,  but  because  it  will  find  substitu¬ 
tions  for  the  variables,  finding  a  proof  can  find  the  substi¬ 
tutions  that  make  a  statement  true,  and  these  substitu¬ 
tions  can  be  the  real  answers  we  are  looking  for. 

Predicate  Logic 

A  logic  programming  system  is  the  conventional  way  to 
use  an  inference  engine.  The  PROLOG  language  is  another 
way.  (See  page  36.)  In  both  cases,  the  input  to  the  pro¬ 
gramming  system  is  expressed  in  clauses.  In  the  case  of 
PROLOG,  the  clauses  are  of  a  special  form:  Horn  clauses, 
which  are  clauses  in  disjunctive  normal  form  that  have 
only  one  positive  literal.  They  are  the  basic  statements  of 
PROLOG. 

The  example  on  page  36  and  Listing  One  (page  62)  uses 
the  Simple  syntax  option  for  micro-PROLOG.  Listing 
Three  (page  66)  shows  the  same  family  tree  example  as 
Listing  One  (the  order  is  different,  but  the  clauses  are  the 
same),  but  it  is  in  the  standard  micro-PROLOG  syntax, 
which  is  very  much  the  same  as  the  syntax  of  LISP.  (See 
page  37.)  Each  predicate  is  represented  as  a  set  of  LlSP-like 
lists,  one  for  each  Horn  clause.  The  form  for  a  predicate 
reference  (called  an  atom)  is: 

(  <predicate-name>  <parameter-l> 

. . .  <parameter-n>  ) 

where  each  of  the  parameters  are  constants,  variables,  or 
Skolem  functions.  Skolem  functions  are  devices  used  to 
express  the  idea  of  an  existentially  quantified  variable. 
This  is  a  case  in  which  we  are  trying  to  express  the  idea 
that  there  is  at  least  one  instance  that  satisfies  the  clause. 
Normally  in  logic  programming  or  PROLOG,  the  variables 
are  universally  quantified,  which  means  that  the  clause 
must  be  true  for  all  possible  instances  of  the  variable. 

The  form  of  a  Horn  clause  is: 

((<  head-literal  >)  (<  literal-1  >) .  . .  (<literal-n>» 

where  each  of  the  literals  is  a  predicate  reference.  The 
head-literal  is  the  part  that  was  to  the  left  of  the  if  in  the 
simple  syntax,  and  the  other  literals  were  to  the  right, 
joined  by  and. 

The  clause: 


x  child-of  y  if  y  father-of  x 

would  be  written  in  the  normal  syntax  as: 

((child-of  x  y)  (*-  father-of  y  x)) 

Some  other  PROLOGS  (such  as  Waterloo  PROLOG)2  use  a 
syntax  like: 

child-of(x,y)  *-  father-of(yx) 

where  the  *—  is  supposed  to  look  like  the  arrow  that 
mathematicians  use  for  implication.  It  is  pronounced 
"if,"  just  like  the  simple  syntax  version. 

Standard  first-order  predicate  calculus  uses  several  dif¬ 
ferent  forms,  but  the  one  I  use  here  is  disjunctive  normal 
form.  In  this  form  of  predicate  logic,  all  the  predicates  in 
a  clause  are  connected  by  the  OR  operator  I,  and  all  the 
clauses  are  implicitly  ANDed  together.  Each  predicate  to¬ 
gether  with  its  arguments  is  an  atom,  and  an  atom  togeth¬ 
er  with  an  optional  logical  negation,  or  NOT  operator',  is 
called  a  literal.  Writing  the  above  example  in  disjunctive 
normal  form,  we  get: 

child-of(x,y)  I  'father-of(yx) 

This  clause  must  be  true,  so  if  it  is  true  that  y  is  the  father 
of  y,  then  father-of y,y)  is  true,  making  ' father-of y,y) 
false.  The  only  way  that  the  clause  can  be  true  if  all  its 
literals  except  one  are  false  is  for  the  remaining  one  to  be 
true.  Thus,  child-of  y,y)  is  forced  to  be  true. 

In  clausal  form  logic,  the  literals  of  a  clause  are  ORed 
together  and  the  clauses  are  ANDed  together.  The  result 
must  be  true  for  the  clauses  to  be  consistent.  If  we  take  a 
set  of  clauses  known  to  be  consistent  and  add  one  more 
clause  and  the  inference  engine  finds  the  resultant  set  of 
clauses  to  be  inconsistent,  then  we  have  refuted  that  last 
clause.  Thus,  to  prove  something,  we  add  its  denial  to  the 
set  of  clauses  and  turn  the  inference  engine  loose  on  it.  If 
the  inference  engine  finds  the  augmented  clause  set  to  be 
inconsistent,  then  we  have  refuted  the  denial  of  the  test 
clause,  thereby  proving  it. 

In  micro-PROLOG,  the  first  literal,  or  head-literal,  is  the 
only  positive  literal  in  the  clause,  and  the  remaining  liter¬ 
als  all  have  negative  signs.  In  generalized  clause  form  log¬ 
ic,  clauses  can  have  all  positive  literals,  all  negative  liter¬ 
als,  or  any  mix  of  the  two.  Because  (y  ly)=(y  ly),  order  is 
not  important  to  the  logic.  Likewise,  because  a&b=b&a, 
the  ordering  of  clauses  is  not  important  either.  In  PRO¬ 
LOG,  however,  the  ordering  of  the  clauses  can  have  a  pro¬ 
found  effect  on  the  execution  time  of  a  problem  and  in 
some  cases  can  cause  the  program  to  fail  to  terminate 
altogether.  Furthermore,  some  of  the  nonlogical,  proce¬ 
dural  aspects  of  practical  PROLOGS  force  an  explicit  de¬ 
pendence  on  clause  order. 

The  Unification  Algorithm 

The  process  of  finding  a  substitution  that  will  make  two 
clauses  the  same  is  called  unification.  The  result  of  a  uni¬ 
fication  is  a  substitution  or  binding  environment  such 
that  when  each  clause  is  realized  in  that  environment, 
the  two  clauses  will  be  the  same.  I  stated  earlier  that  uni- 
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fication  is  at  the  heart  of  all  of  the  inference  rules.  I  will 
now  describe  how  unification  works. 

A  binding  environment  is  a  list  of  pairs,  where  the  first 
element  in  each  pair  is  changed  to  the  second  element  in 
its  pair  wherever  it  occurs  in  the  two  expressions  being 
unified.  For  example,  take  the  substitution,  or  binding 
environment  change  y  into  y,  and  realize  the  expression 
fly)  I  ~g(y,y)  in  this  environment.  This  gives  the  expres¬ 
sion  fly)  I  'g(yy)  as  the  result.  As  a  more  difficult  exam¬ 
ple,  take  the  substitution  change  y  into  fly,  z)  and  change  z 
into  p(a,g(b)),  then  realize  the  expression  g(y)  lq(y,yz)  in 
this  environment.  This  gives  the  expression: 

g(f(y,z))  I  q(fiyz),y,p(a,g(b))) 

which  further  reduces,  by  applying  the  same  substitu¬ 
tion  again,  to: 

g(f(y,p(a,g(b))»  I  q(f(yp(a,g(b))),yp(a,g(b») 

The  substitution  is  performed  repeatedly  until  no  further 
substitution  can  take  place.  This  is  sometimes  called  the 
recursive  realization  of  an  expression  under  an  environ¬ 
ment.  You  can  see  that  there  are  no  real  limits  on  the 
complexity  of  the  substitutions  that  can  take  place. 

One  situation  that  must  be  prohibited  is  the  case  where 
a  subexpression  of  the  source  term  in  a  substitution  oc¬ 
curs  in  the  substituted  term.  For  instance,  consider  the 
substitution  change  y  into  fly)  when  applied  to  the  ex¬ 
pression  y.  After  the  first  application  of  the  substitution, 
we  get  fly),  but  we  can  apply  the  substitution  again  to 
produce  flfly))  and  again  to  produce  flflfly))).  This  pro¬ 
cess  will  continue  to  produce  a  sequence  of 
flflfl . .  .fly))). . .  )  that  goes  on  forever.  When  this  situa¬ 
tion  arises,  the  realization  process  fails  to  terminate; 
therefore,  we  prohibit  the  application  of  a  substitution  of 
this  sort.  This  occurs  situation  is  not  always  so  easy  to 
detect.  For  instance,  the  substitution: 

change  x  to  y  and  change  y  to  z  and  change  z  to  x 

is  likewise  prohibited.  The  offending  substitution  may  be 
deeply  nested  in  the  expressions  being  substituted  into, 
to,  and  from. 

The  problem  of  unification  is  to  find  a  substitution  that 
makes  two  expressions  the  same  when  they  are  realized 
under  that  substitution.  We  can  only  unify  expressions 
by  substituting  values  for  variables;  we  cannot  substitute 
to  change  the  value  of  something  that  is  not  a  variable. 
For  now,  we  will  use  the  letters  y,  y,  and  z  to  stand  for 
variables.  For  instance,  the  expressions /fa  f  andfla)  may 
be  unified  by  the  substitution  change  y  to  a,  where  y  is  a 
variable  and  a  is  a  constant.  It  is  equally  valid  to  substitute 
one  variable  for  another,  as  fly)  and  fly)  may  be  unified 
by  the  substitution  change  y  to  y. 

Things  can  certainly  get  more  complicated.  Unify: 

f(x,y)  I  g(a,z)  and  g(a,b)  I  f(z,c) 


We  can  do  this  with  the  substitution: 
change  x  to  z,  y  to  c,  and  z  to  b 

Of  course,  not  every  expression  can  be  unified  with  ev¬ 
ery  other  expression.  If  the  numbers  of  terms  in  the  ex¬ 
pression  do  not  match,  no  substitution  in  the  world  can 
unify  them.  For  instance,  it  is  not  possible  to  unify  the 
expressions  fly)  and  fly)  Iflz),  even  though  the  substitu¬ 
tion  change  ytoy  and  change  y  to  z  will  make  them  alge¬ 
braically  equal  because  unification  does  not  know  the 
rule  (y  I y)  =  y.  Likewise,  if  the  predicate  names  do  not 
match,  unification  is  impossible,  as  in/fa  j  and  gfaj.  A  con¬ 
stant  cannot  be  unified  with  anything  except  a  variable 
or  itself,  making  the  unification  of  fla)  and  fib)  impossi¬ 
ble;  however,  a  variable  can  be  unified  with  an  arbitrari¬ 
ly  complex  expression,  as  in: 

fix)  and  fig(a,p(z),y)) 

which  results  in  the  substitution: 

change  x  to  g(a,p(z),y) 

Unification  must  produce  the  binding  environment 
that  defines  the  most  general  substitution,  or  unifier; 
when  the  two  input  expressions  are  realized  under  it,  the 
unifier  will  unify  these  two  expressions,  making  them 
the  same  expression.  The  most  general  unifier,  or  MGU, 
will  not  make  a  substitution  unless  it  needs  to.  For  exam¬ 
ple,  unifying  fly,y)  and  fly, 7)  should  produce  the  substi¬ 
tution  change  y  to  7.  The  two  expressions  could  be  unified 
with  the  substitution: 

change  y  to  7  and  change  x  to  FOO 

but  that  would  not  be  as  general  as  leaving  y  as  a  variable, 
because  the  expressions  will  unify  without  substituting 
any  value  for  y. 

In  the  following  LISP  implementation  of  unification,  I 
represent  a  variable  as  any  LISP-atom  that  begins  with  an 
asterisk.  Thus: 

*X,  *X,  *THIS_IS_A_LONG_VARIABLE_NAME 

and  even  *  alone  constitute  valid  variables. 

A  binding  environment  is  represented  by  a  list  of  dot¬ 
ted  pairs.  The  substitution: 

change  x  to  y  and  change  z  to  fix) 

is  represented  by  the  list  ((y.y)  (z.lf  y))),  which  will  be 
printed  by  the  LISP  interpreter  as  ((y.y)  (zf  y)). 

A  clause  is  likewise  represented  by  a  list.  The  clause: 

fix)  I  ~g(y,p(a,z))  I  q(b,z) 

is  represented  by  the  list: 

<(f  x)  ('  (g  (y  (p  a  z)))  (q  b  z)) 

Listing  Four  (page  66)  defines  a  set  of  muLISP  functions, 
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including  UNIFY,  a  simple  unification  algorithm,  accord¬ 
ing  to  J.  A.  Robinson.3  UNIFY  calls  EQUATE,  which  calls 
UNIFY,  and  so  on,  in  a  sort  of  ping-pong  recursion.  ULT 
finds  the  ultimate  successor  to  a  variable  by  first  check¬ 
ing  if  that  variable  is  defined  in  the  environment.  If  it  is, 
then  its  ultimate  successor  is  the  ultimate  successor  to  its 
immediate  successor,  which  is  computed  by  IMM.  IMM 
checks  to  see  if  the  environment  is  NIL;  if  not,  it  checks  if 
the  variable  is  defined  in  the  first  binding  pair  in  the  en¬ 
vironment.  If  the  variable  is  not  bound  in  the  first  pair  on 
the  environment,  then  IMM  calls  itself  recursively  to  see 
if  the  variable  is  bound  in  any  of  the  rest  of  the  pairs  in 
the  environment. 

EQUATE  extends  the  environment  by  adding  substitu¬ 
tions  to  it  to  make  the  two  expressions  the  same.  If  the 
two  expressions  already  are  the  same,  then  EQUATE  re¬ 
turns  the  present  environment.  If  the  first  expression  is  a 
variable  and  this  variable  does  not  occur  in  the  second 
expression  under  the  present  environment,  then  the  en¬ 
vironment  is  extended  by  CONS ing  a  new  substitution 
pair  to  the  front  of  it.  If  the  variable  does  occur  in  the 
second  expression,  as  indicated  by  OCCURS,  then  the  uni¬ 
fication  is  impossible,  and  the  value  IMPOSSIBLE  is  re¬ 
turned  instead  of  a  binding  environment. 

The  occurs  check  is  not  present  in  PROLOG  because  it 
eats  up  a  lot  of  computer  time,  but  strictly  speaking  it  is 
necessary  to  prevent  the  interpreter  from  getting  caught 
up  in  a  recursive  black  hole  from  which  it  will  never 
return.  In  the  words  of  the  "Adventure”  program, 
".  . .  you  are  likely  to  fall  into  a  pit”  if  the  occurs  check  is 
absent.  In  PROLOG,  the  programmer  must  ensure  that  an 
occurs  situation  never  occurs.  This  is  usually  not  too  diffi¬ 
cult  in  practice,  but  in  order  to  prove  that  an  inference 
rule  works  we  need  to  know  that  the  unification  algo¬ 
rithm  always  works,  and  it  only  works  all  the  time  when 
it  performs  the  occurs  check.  Without  the  check,  the  al¬ 
gorithm  could  fail  to  terminate,  which  would  thereby 
violate  one  of  the  requirements  of  an  algorithm. 

The  RECREAL  (recursive  realization)  function  instanti¬ 
ates  the  variables  in  an  expression  by  performing  the 
substitutions  indicated  by  the  environment.  It  does  this 
by  calling  ULT  for  each  variable  in  the  expression,  tra¬ 
versing  the  expression  by  recursive  calls  to  itself,  and 
building  the  resultant  expression  as  it  goes. 

The  VARIABLEP  function  is  a  predicate  that  returns  T  or 
NIL,  depending  on  whether  its  argument  is  a  variable.  For 
our  sample  program  in  Listing  Four,  a  variable  is  any 
atom  whose  print  name  starts  with  an  asterisk  (*).  This  is 
in  accord  with  Waterloo  PROLOG.4 

In  Listing  Five  (page  68)  we  see  a  sample  run  of  UNIFY 
and  RECREAL.  The  first  example  defines  two  clauses,  Cl 
and  C2,  and  attempts  to  unify  them  by  a  call  to  UNIFY. 
UNIFY  returns  IMPOSSIBLE  to  indicate  that  the  expressions 
cannot  be  unified.  The  recursive  realizations  of  the  two 
expressions  are  then  the  original  expressions  themselves. 
The  second  example  defines  a  new  C2  and  unifies  it  with 
the  old  Cl,  returning  the  environment  ((  .  a )).  This  envi¬ 

ronment  shows  that  the  value  a  should  be  substituted  for 
the  variable  *jc  to  unify  the  two  expressions.  Notice  that 


the  recursive  realization  of  the  two  input  clauses  is  iden¬ 
tical. 

In  the  third  example,  UNIFY  returns  an  environment 
consisting  of  ((*y  g  *y)J,  which  is  the  same  as 
((*?c.(g  *y))).  This  shows  that  the  variable  must  be  in¬ 
stantiated  with  the  value  (g  *y)  to  make  the  two  expres¬ 
sions  the  same.  The  fourth  example  shows  a  case  in 
which  the  occurs  check  saves  us.  The  fifth  example 
shows  a  more  complicated  set  of  expressions.  Note  that 
UNIFY  will  work  on  arbitrarily  complex  expressions,  lim¬ 
ited  only  by  the  amount  of  memory  available. 

The  Resolution  Principle 

Until  recently  all  formal  rules  of  inference  have  been 
oriented  toward  human  beings.  An  argument  needed  to 
be  not  only  logically  correct  but  also  humanly  compre¬ 
hensible,  because  in  a  mathematical  proof  each  step 
needed  to  be  undisputable  even  though  the  conclusion 
might  not  be  expected  at  all  from  the  hypothesis.  Such  a 
proof  might  involve  a  great  many  deductive  steps.  When 
using  a  computer  to  deduce  conclusions,  one  may  be  in¬ 
terested  only  in  the  results,  not  the  details  of  each  step 
along  the  way.  In  a  1965  paper  describing  a  new  rule  of 
inference,  J.  A.  Robinson  called  this  new  rule  the  resolu¬ 
tion  principle.5  Robinson's  resolution  principle  is  unique 
in  that  it  is  a  complete  rule  of  inference:  no  other  rule  is 
needed  to  reach  any  possible  conclusion  from  a  given  set 
of  facts.  In  actuality  an  auxiliary  rule  called  factoring  is 
needed  for  certain  cases,  but  resolution  together  with 
factoring  forms  a  complete  deductive  apparatus. 

The  principle  of  resolution  is  really  quite  simple;  the 
proof  that  it  always  works  is  difficult.  See  Robinson's 
aforementioned  paper  for  a  proof  of  the  soundness  and 
completeness  of  the  resolution  principle.  Referring  to 
Listing  Four,  we  see  the  function  BINRES.  This  function 
performs  binary  resolution  on  its  arguments  CL1  and 
CL2,  resolving  on  the  literals  at  positions  N1  and  N2,  re¬ 
spectively.  Recall  that  a  literal  is  a  predicate  reference 
together  with  an  optional  negation  sign.  If  this  negation  is 
present,  we  say  that  the  sign  of  the  literal  is  negative; 
otherwise,  its  sign  is  positive. 

To  resolve  the  two  clauses  CL1  and  CL2  on  their  literals 
at  positions  N1  and  N2,  perform  the  following. 

1.  Change  the  names  of  all  the  variables  in  one  of  the 
clauses  so  that  the  two  clauses  have  no  variables  in  com¬ 
mon.  This  process  is  called  taking  variants. 

2.  If  the  signs  of  the  two  literals  are  the  same,  then  the 
resolution  cannot  be  performed,  so  return  IMPOSSIBLE. 

3.  Otherwise,  unify  the  two  literals,  without  their  signs.  If 
the  unification  failed  the  resolution  fails,  so  return  IMPOS¬ 
SIBLE. 

4.  Otherwise,  delete  the  two  literals  from  their  respective 
clauses  and  return  the  OR  of  the  resulting  clauses.  This  is 
the  resolvent  of  the  clauses  CL1  and  CL2  about  the  literals 
N1  and  N2. 

You  can  see  that  the  resolvent  contains  two  fewer  clauses 
than  the  total  between  the  two  input  clauses.  If  we  can 
repeatedly  cancel  out  literals  until  one  of  our  resolvents 
is  NIL,  the  empty  clause,  then  we  have  found  a  contradic¬ 
tion.  If  we  have  added  the  denial  of  the  thing  we  wish  to 
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to  get: 

s(u) 

'S(u) 

Because  a  statement  cannot  be  both  true  and  false  at  the 
same  time,  we  have  a  contradiction. 

However,  no  matter  how  many  times  resolution  is 
applied  to  [the  two  original  clauses]  and  their  de¬ 
scendants,  every  resolvent  contains  exactly  two  at¬ 
oms,  and  consequently  no  resolvent  is  the  empty 
clause  (which  contains  no  atoms). 

Factoring  produces  a  new  clause  from  an  old  clause  by 
unifying  two  literals  of  like  sign  from  that  clause  (without 
taking  variants)  and  then  performing  the  substitution 
and  deleting  one  of  the  unified  literals.  See  Listing  Six 
(page  68),  the  first  example,  to  see  our  factoring  algorithm 
at  work. 

PROLOG  does  not  need  factoring  because  resolution  is 
complete  without  factoring  for  sets  of  Horn  clauses.  A 
Horn  clause  is  a  clause  with  only  one  positive  literal.  In 
PROLOG  this  is  the  first  literal, which  is  the  consequent  of 
the  implication.Thus  in  the  PROLOG  clause  y  if  y and  z,  y  is 
the  positive  literal,  and  y  and  z  are  negative  literals.  If  we 
rewrite  the  PROLOG,  clause  in  clause  form  logic,  we  have 
y  l~y  I ~z.  If  y  and  z  are  both  true,  then  ~  y  and  ~  z  are  both 
false,  so  '  y/'z  is  also  false.  The  only  way  the  clause  can 
be  satisfied  is  for  y  to  be  true,  which  is  the  desired  effect. 

One  theorem  states  that  resolution  is  complete  for 
Horn  clauses  without  factoring.  Another  theorem  is  that 
any  problem  that  can  be  expressed  in  clause  form  logic 
can  be  expressed  in  Horn  clauses,7  and  yet  another  theo¬ 
rem  is  that  clause  form  logic  (that  is,  first-order  predicate 
calculus)  is  a  complete  basis  for  computation.  PROLOG 
uses  resolution  on  Horn  clauses,  which  means  that  a  PRO¬ 
LOG  program  is  capable  of  computing  anything  that  any 
j  other  program  is  capable  of  computing. 

The  Inference  Rule  of  Paramodulation 

Even  though  resolution  alone  is  sufficient  to  do  anything 
we  can  do  with  any  other  programming  language,  it  is 
not  always  efficient.  One  area  in  which  efficiency  often 
suffers  is  the  processing  of  equality  relations.  An  equality 
relation  has  a  number  of  properties,  such  as  symmetry 
reflexivity  and  transitivity.  Each  of  these  must  be  ex¬ 
pressed  as  Horn  clauses  in  order  for  a  resolution  infer¬ 
ence  engine  to  process  equality  relations.  An  inference 
rule  known  as  paramodulation  builds  these  properties  of 
equality  directly  into  the  inference  engine.  See  G.  Robin¬ 
son  and  L.  Wos’s  discussion  of  paramodulation.8  The  par¬ 
amodulation  refutation  required  47  steps,  and  the  pure 
resolution  refutation  required  136  steps.  The  process  of 
|  paramodulation  consists  of  the  steps  enumerated  in  the 
following  list: 
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prove  to  a  consistent  knowledge  base  and  we  can  resolve 
to  produce  the  NIL  clause,  then  we  have  proved  what  we 
set  out  to  prove. 

Consider  the  following  two  clauses: 
fix, a)  I  g(x,y)  I  ~fiy,b) 
and: 

p(x)  I  ~g(a,x) 

We  wish  to  form  a  resolvent  between  these  two  clauses. 
We  can  unify  them  about  the  second  literal  in  each 
clause.  Unifying: 

g(x,y)  and  g(a,x) 

gives  the  MGU: 

change  x  to  a  and  change  y  to  x 

Now  we  can  delete  the  two  unified  clauses  from  the 
union  of  the  two  original  clauses  to  form: 

fix, a)  I  'fiyb)lp(x) 

But  we  are  not  finished  yet;  we  must  apply  the  substitu¬ 
tion  to  the  above  clause  to  get  the  resolvent: 

fia,a)  I  ~f(a,b)  I  p(a) 

The  Factoring  Operation 

I  mentioned  earlier  that  resolution  was  only  complete  if 
it  included  factoring.  The  following  example  is  from 
R.  Kowalski  's  Logic  for  Problem  Solving, 6  with  the  nota¬ 
tion  changed  to  fit  our  conventions: 

I 

s(x)  I  sty) 

~s(u)  I  ~s(v) 

The  two  clauses  are  inconsistent  because  they  have 
instances: 

s(x)  I  s(x) 

~s(u)  I  s(u) 

which,  after  removal  of  duplicate  atoms,  are  direct¬ 
ly  contradictory: 

i 

s(x) 

~s(u) 

This  is  true  because  we  can  unify  these  last  two  clauses  \ 
by  the  substitution: 

i 

change  x  to  u 
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1.  Take  two  clauses.  Call  them  FROM  and  INTO. 

2.  Take  variants  so  that  the  clauses  have  no  variables  in 
common. 

3.  Search  the  FROM  clause  to  find  a  positive  equality  rela¬ 
tion. 

4.  Call  one  side  of  the  equality  relation  SEL,  the  selection 
term,  and  call  the  other  side  SUB,  the  substitution  term. 

5.  Unify  SEL  with  a  literal  in  the  INTO  clause.  If  this  cannot 
be  done,  swap  SEL  with  SUB  and  try  this  step  again.  If  it 
still  cannot  be  done,  then  unification  fails,  so  paramodu- 
lation  fails. 

6.  Instantiate  both  the  FROM  and  INTO  clauses  with  the 
substitution  obtained  from  the  above  unification. 

7.  Replace  the  unified  term  in  the  INTO  clause  with  the 
SUB  term. 

8.  Delete  the  equality  literal  from  the  FROM  clause. 

9.  OR  the  new  FROM  and  INTO  clauses  together.  This  result 
is  the  paramodulant  of  the  original  two  clauses. 

If  the  equality  relation  cannot  be  found  or  if  the  unifica¬ 
tion  cannot  be  performed,  then  no  paramodulant  exists. 
See  Listing  Four  for  a  LISP  implementation  of  paramodu- 
lation;  see  Listing  Six  for  an  example  of  its  use. 

The  Boyer-Moore  Structure-Sharing 
Resolution  Algorithm 

The  resolution  algorithm  given  above  is  operational  and 
could  be  used  as  the  basis  for  an  experimental  version  of 
PROLOG,  but  it  is  terribly  inefficient.  J.  A.  Robinson  de¬ 
scribed  the  resolution  principle  in  1965,  but  the  first  PRO¬ 
LOG  interpreter  did  not  appear  until  1973.  This  was  pri¬ 
marily  because  in  1972,  R.  S.  Royer  and  J.  S.  Moore 
published  the  first  efficient  implementation  of  a  resolu¬ 
tion  algorithm.9  Their  algorithm  streamlines  the  process 
of  taking  variants  and  eliminates  the  copying  of  each 
clause  every  time  it  is  resolved  upon. 

Whereas  our  earlier  resolution  algorithm  used  a  vari¬ 
ant-taking  process  that  prefixed  asterisks  onto  the  name 
of  a  variable  until  it  was  unique,  copying  the  clause  as  it 
did  so,  the  Boyer-Moore  algorithm  uses  a  method  known 
as  indexing,  which  totally  eliminates  all  the  copying  and 
uses  simple  arithmetic  to  form  an  index  that  is  associated 
with  each  variable.  In  this  implementation,  variables 
start  with  a  lowercase  letter.  Appending  a  prime  is  a  con¬ 
ventional  way  of  differentiating  two  variables  of  like 
name,  such  as  y  and  y '.  The  Boyer-Moore  index  can  be 
thought  of  as  a  count  of  the  primes  appended  to  a  name 
to  make  it  unique. 

The  advantage  of  the  indexing  system  is  that  the  new 
index  needed  to  make  a  variable  unique  can  be  formed 
by  a  simple  addition  operation.  Each  variable  is  com¬ 
posed  of  a  name  and  a  corresponding  index.  The  index  is 
a  positive  integer.  Instead  of  copying  a  variant  clause 
while  substituting  the  new  variables,  the  structure-shar¬ 
ing  algorithm  extends  the  binding  environment  to  keep 
track  of  the  variants. 

Listing  Seven,  (page  69)  gives  a  muLlSP  implementation 
of  the  Boyer-Moore  structure-sharing  resolution  algo¬ 
rithm.  Listing  8  (page  70)  gives  a  sample  run  of  the  algo¬ 


rithm. 

The  algorithm  uses  a  septuple,  or  data  structure  com¬ 
posed  of  seven  elements.  They  are: 


1.  LPAR: 

2.  LLIT#: 

3.  RPAR: 

4.  RLIT#: 

5.  NLITS: 

6.  MAXNDX: 

7.  BINDINGS: 


The  left  parent. 

The  left  literal  number. 

The  right  parent. 

The  right  literal  number. 

The  number  of  literals. 

The  maximum  index. 

The  extension  to  the  binding  environment 
added  at  this  level. 


This  septuple  represents  a  clause,  either  as  a  clause  origi¬ 
nally  in  the  knowledge  base  or  produced  as  a  resolvent 
by  the  algorithm.  The  function  MAKECL  takes  a  clause  as 
we  would  type  at  the  keyboard  and  generates  a  septuple 
that  is  a  list  composed  of  the  seven  elements  in  order.  The 
clause  is  pointed  to  by  LPAR ;  LLIT*  is  zero;  RPAR  is  ML; 
RLIT #  is  zero;  NLITS  is  the  number  of  members  (returned 
by  the  function  NMEMS )  in  the  clause;  MAXNDX  is  one; 
and  BINDINGS  is  NIL.  This  is  the  form  of  an  input  record. 
An  input  record  is  recognized  by  the  predicate  function 
INRECP. 

When  we  form  a  resolvent,  we  generate  a  new  septu¬ 
ple,  where  RPAR  and  LPAR  point  to  old  septuples.  LLIT# 
and  RLIT *  are  the  numbers  of  the  literals  resolved  upon  in 
the  septuples  pointed  to  by  RPAR  and  LPAR.  NLITS  is  the 
number  of  literals  in  this  clause,  which  is  two  less  than 
the  sum  of  the  NLITS  cells  in  the  septuples  pointed  to  by 
LPAR  and  RPAR.  MAXNDX  is  the  sum  of  the  MAXNDX  cells 
in  each  of  the  parent  clauses  pointed  to  by  LPAR  and 
RPAR. 

If  we  associate  MAXNDX  with  each  of  the  variables  in 
the  right  parent  of  this  new  clause,  we  are  guaranteed 
that  all  of  its  variables  are  unique  as  compared  to  the  left 
parent.  The  function  GETLIT retrieves  a  literal  from  a  tree 
of  these  septuples  and  keeps  track  of  the  index  and  sign 
of  the  literal,  returning  them  in  the  free  variables  SIGNG 
and  INDEXG  along  with  the  literal  itself  in  the  free  vari¬ 
able  LITG.  (A  free  variable  is  a  variable  that  is  not  local  to 
the  function  in  which  it  is  used.  It  is  somewhat  analogous 
to  a  global  variable  in  conventional  programming  lan¬ 
guages.) 

The  Boyer-Moore  structure-sharing  unification  algo¬ 
rithm  works  by  returning  T  or  NIL  to  indicate  whether 
the  unification  was  possible  and  extending  the  binding 
environment  in  the  free  variable  BN  DEV.  BN  DEV  is  the 
septuple  in  which  the  resolvent  will  eventually  be 
stored.  The  algorithm  is  as  follows. 

1.  If  the  two  terms  and  the  two  indexes  are  equal,  then 
return  T  without  extending  the  environment. 

2.  If  TERMi  is  a  variable  bound  in  the  current  environ¬ 
ment,  then  substitute  what  it  is  bound  to  and  try  to  unify 
the  result  with  TERM2. 

3.  If  the  occurs  check  finds  a  bottomless  pit,  then  return 
NIL. 

4.  Otherwise,  force  a  unification  by  extending  the  envi¬ 
ronment  and  return  T. 

5.  If  TERM2  is  a  variable,  then  swap  TERMi, INDEX  1  with 
TERM2,INDEX2  and  try  to  unify  that. 
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6.  Otherwise,  try  to  unify  the  CAR  of  TERM1,INDEX1  with 
the  CAR  of  TERMZ,  INDEX2.  If  the  unification  fails,  return 
NIL. 

7.  Otherwise,  return  the  result  of  unifying  the  CDRs  of 
TERM1,INDEX1  and  TERM2,INDEX2. 

The  comments  in  Listing  Seven  should  make  the  code 
fairly  easy  to  follow,  although  this  is  not  a  simple  algo¬ 
rithm.  The  occurs  check  would  be  eliminated  in  a  PRO¬ 
LOG  implementation. 

The  Boyer-Moore  algorithm  could  be  the  basis  for  a 
PROLOG  implementation,  but  a  viable  PROLOG  interpreter 
should  not  be  written  in  a  language  such  as  LISP,  which  is 
interpretive  itself.  The  structure-sharing  resolution  algo¬ 
rithm,  rewritten  in  a  portable,  compiled,  higher-level 
language  such  as  C  or  Pascal,  could  form  the  basis  for  a 
practical  inference  engine  in  a  Prolog  i  interpreter. 

There  is  also  an  alternative  to  structure  sharing:  struc¬ 
ture  copying,  also  called  non-structure  sharing.10  Micro- 
PROLOG  uses  this  method,  which  uses  an  indexing 
scheme  for  the  taking  of  variants  but  does  not  share 
structure  as  does  the  Boyer-Moore  algorithm.11  Some 
claim  that  the  structure-copying  method  can  be  superior 
to  structure  sharing  on  machines  with  a  short  word 
length,  such  as  microcomputers.  It  remains  to  be  seen 
which  of  these  two  methods  is  best  for  larger  micros  ad¬ 


dress  spaces  of  a  megabyte  and  more. 

Some  PROLOGS,  including  micro-PROLOG,  use  special 
techniques  to  allow  recursion  to  be  as  efficient  as  itera¬ 
tion,  which  is  not  available  in  PROLOG.  These  techniques 
are  applicable  in  deterministic  cases  of  recursion,  such  as 
was  encountered  in  our  first  factorial  algorithm,  and  are 
called  tail  recursion  optimization.  M.  Bruynooghe  dis¬ 
cusses  the  implementation  of  these  methods  in  Logic  Pro¬ 
gramming.12  Another  related  technique,  success  pop¬ 
ping,  is  discussed  in  T.  Bruynooghe 's  essay  and  in  F.  G. 
McCabe  and  K.  L.  Clark’s  Micro-PROLOG  3.0  Programmer's 
Reference  Manual.13 

To  make  a  complete  PROLOG  system,  however,  re¬ 
quires  a  great  deal  more.  First,  resolution  alone  does  not 
make  an  inference  engine.  A  strategy  is  needed  to  deter¬ 
mine  what  to  resolve  next.  This  strategy  called  the 
search  strategy  can  be  a  breadth-first,  depth-first,  or  heu- 
ristically  guided  search;  the  depth-first  method  is  em¬ 
ployed  in  PROLOG.  The  inference  engine  of  PROLOG  takes 
the  query  clause  and  resolves  it  with  the  first  clause  in 
the  knowledge  base  that  matches  it  in  its  head  literal. 
Remember  that  the  head  literal  is  the  only  literal  of  posi¬ 
tive  sign.  The  query  clause  is  the  only  clause  with  no 
positive  literals.  Therefore,  PROLOG  only  needs  to  look  at 
the  head  literals  to  try  a  resolution. 

A  practical  PROLOG  will  have  an  efficient  database  re¬ 
trieval  system  that  allows  it  to  quickly  find  candidate 
clauses  that  match  a  given  literal  with  their  head  literal. 
Some  PROLOGS  even  go  so  far  as  to  index  the  knowledge 
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base  to  the  first  two  terms  of  the  head  literal,  which 
greatly  reduces  the  time  to  find  a  matching  clause  or  de¬ 
termine  that  no  match  is  possible.  When  a  potential 
match  is  found,  the  two  literals  are  unified,  but  the  resol¬ 
vent  is  not  placed  into  the  knowledge  base  yet.  PROLOG 
then  steps  through  the  negative  literals  in  the  clause  just 
resolved  with,  resolving  each  of  them  in  turn  with  other 
clauses  in  the  knowledge  base.  Each  of  these  clauses  is 
stepped  through  in  similar  fashion  until  the  NIL  resolvent 
is  produced.  Then  execution  continues  at  the  previous 
level. 

If  a  resolvent  fails,  PROLOG  backtracks  to  the  nearest 
choice  point  where  it  could  have  chosen  a  different  Horn 
clause  to  resolve  with  and  takes  that  branch  of  the  search 
tree  instead.  Only  after  exploring  the  entire  search  tree 
and  failing  everywhere  does  PROLOG  report  failure.  If 
PROLOG  can  deduce  the  NIL  clause  from  the  query  clause 
and  the  knowledge  base  and  if  the  knowledge  base  is 
consistent,  the  query  clause  is  false.  But  the  query  clause 
is  a  negative  clause,  so  the  query  condition  is  true. 

When  the  NIL  clause  is  deduced,  the  binding  environ¬ 
ment  that  produced  it  is  available,  and  the  substitutions 
provide  additional  information.  In  the  family  tree  exam¬ 
ple,  these  substitutions  are  the  answers  we  were  looking 
for.  The  "which”  predicate  of  the  simple  extension  to 
micro-PROLOG  continues  after  NIL  is  deduced  to  find  all 
the  answers  rather  than  stopping  on  the  first  one. 

Even  after  the  search  strategy  and  the  database  retriev¬ 
al  mechanisms  are  provided  for,  we  would  have  a  PRO¬ 
LOG  interpreter,  but  we  would  not  have  a  complete  PRO¬ 
LOG  system.  A  complete  artificial  intelligence  program 
development  system  needs,  as  a  bare  minimum,  a  good 
interactive  program  editor  and  debugger,  including  a 
trace  facility.  These  functions  taken  collectively  form  the 
programming  environment.  Also,  built-in  functions  must 
be  provided  to  perform  arithmetic,  input-output  opera¬ 
tions,  list  construction  and  decomposition,  control,  addi¬ 
tions  to  and  deletions  from  the  knowledge  base,  and  so 
on.  The  micro-PROLOG  system  provides  all  of  these,  and 
the  programming  environment  is  written  in  micro-PRO¬ 
LOG  itself. 
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What  Is  an  Inference  Engine? 

An  Example  Using  micro-PROLOG 

Consider  the  micro-PROLOG  program  given  in  Listing 
One.  This  is  a  simple  relational  (pun  intended!)  database 
system  to  keep  track  of  all  of  my  daughter's  relations  in 
the  form  of  a  family  tree.  Examination  of  the  code  reveals 
that  the  first  section  is  a  series  of  statements  of  the  form 
ic  father-of y .  This  section  is  followed  by  a  similar  series  of 
statements  of  the  form  y  mother-of  y. 

Together  these  two  sections  constitute  the  knowledge 
base  for  the  family  tree.  Statements  of  this  form  are 
called  assertions  or  facts.  Most  of  the  father-of  and  moth- 
erof  relations  are  free  of  any  variables;  these  are  called 
ground  clauses;  however,  a  few  of  these  relations  are  of 
the  form  <statement-l>  if  <statement-2>  and  typically 
contain  variables.  These  are  the  conditional  statements  of 
PROLOG.  The  general  form  of  a  PROLOG  statement,  or 
clause,  is: 

<statement-l>  if  <statement-2>  and  ...  <statement-n> 

The  procedures  of  PROLOG  are  called  predicates,  just 
like  the  procedures  of  FORTH  are  called  words.  A  PROLOG 
clause  is  then  more  properly  defined  as: 

<predicate-l>  if  <predicate-2>  and  ...  <predicate-n> 

The  definition  of  a  PROLOG  predicate  is  either  built  into 
the  interpreter  or  is  defined  by  the  applications  logic  pro¬ 
grammer  as  a  set  of  clauses,  all  having  the  same  relation 
name,  or  predicate  name.  Thus,  in  the  definition  of  moth- 
er-of  we  find: 

lilian-givens  mother-of  x  if 

paul-sewall-jr  father-of  x 

This  clause,  together  with  all  the  ground  assertations  for 
mother-of  comprises  the  definition  of  the  mother-of 
predicate.  It  is  an  interesting  characteristic  of  logic  pro¬ 
gramming  in  general,  and  PROLOG  in  particular,  that  the 
distinction  between  program  and  data  becomes  very 
fuzzy.  In  our  family  tree,  were  it  to  be  written  using  a 
conventional  database  package,  we  would  have  to  repre¬ 
sent  all  father-of  and  mother-of  relations  as  records  in  a 
father-of  file  and  a  mother-of  file.  These  records  would 
be  data.  If  we  wanted  to  write  a  procedure  to  handle  the 
case  of  lilian-givens,  we  would  probably  discard  the  idea 
as  impractical:  the  mother-of  file  contains  pure  data;  if 
we  needed  to  write  a  routine  to  compute  something,  the 
routine  would  be  pure  code.  Never  the  twain  shall  meet! 
But  in  PROLOG,  we  can  easily  intermix  data  and  program 
to  do  the  job.  We  can  use  whichever  approach  seems 
most  natural.  In  PROLOG,  data  are  retrieved  by  unifica¬ 
tion;  hence,  we  execute  the  data  (or  perhaps  search  the 
code)  to  find  a  match  with  the  search  pattern,  and  it  mat¬ 
ters  not  whether  the  data  is  pure  data,  pure  code,  or  a 
mixture  of  both. 

Looking  at  Listing  Two  (page  62),  which  shows  a  series 


of  query  operations  performed  against  the  family  tree, 
notice  the  form  of  the  query: 

which!  <answer-pattern>  <query-pattern>  ) 

This  is  micro-PROLOG’s  query  format.  (Other  interpret¬ 
ers  differ  in  external  details.)  In  the  example,  the  answer 
pattern  is  always  a  single  variable,  but  micro-PROLOG  al¬ 
lows  for  arbitrarily  complex  answer  patterns.  For  the  first 
query,  the  inference  engine  attempts  to  find  a  value  for  y 
that  will  make  the  relation  y  father-of  robert-brown-iii 
true.  It  finds  when  y  =  robert-brown-jr,  the  query  pattern 
is  true,  so  it  displays  this  value  as  an  answer.  As  it  happens, 
I  have  only  one  father,  so  there  are  no  more  answers. 

The  next  query  illustrates  another  beautiful  aspect  of 
PROLOG:  a  procedure  can  be  run  in  reverse,  so  to  speak! 
The  first  example  used  a  variable  for  the  father,  but  this 
example  uses  a  variable  for  the  child.  Again,  because  I 
have  only  one  child,  PROLOG  displays  my  daughter's 
name  and  then  says,  "no  more  answers.” 

The  next  query  uses  an  additional  relation,  parent-of 
which  is  defined  by  the  following  two  clauses: 

x  parent-of  y  if 

x  father-of  y 
x  parent-of  y  if 

x  mother-of  y 

This  says  that  y  is  a  parent  of  y  if  y  is  either  the  father  or 
the  mother  of  y.  We  have  defined  a  new  relation  in  terms 
of  two  other  relations.  In  a  conventional  database  envi¬ 
ronment,  this  would  either  require  creating  a  parent-of 
file  or  a  parent-of  subroutine,  but  in  PROLOG  we  needn’t 
distinguish  between  the  two  cases.  When  we  ask  PROLOG: 

which  (x  x  parent-of  krystl-raquelle-brown) 

PROLOG  responds  with: 

Answer  is  robert-brown-iii 
Answer  is  darlene-breeden 
No  (more)  answers 

In  this  case,  there  was  more  than  one  instance  of  y  such 
that  y  parent-of  krystl-raquelle-brown  was  true,  so  more 
than  one  answer  was  returned. 

The  descendant-of  relation  illustrates  a  simple  case 
of  recursion,  where  a  predicate  is  defined  in  terms  of 
itself: 

x  descendant-of  y  if 
x  child-of  y 
x  descendant-of  y  if 

z  child-of  y  and 
x  descendant-of  z 

This  relation  will  thread  its  way  through  the  family 
tree  and  report  all  persons  who  are  descendants  of  a  giv¬ 
en  person.  Notice  how  the  first  clause  does  not  call  de¬ 
scendant-of  recursively.  This  clause  provides  the  termi¬ 
nation  condition  for  the  relation.  If  the  first  clause  is  not 
satisfied,  the  second  clause  will  get  us  one  step  closer  to 
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the  case  where  it  will  be.  Repeating  via  recursion  will 
give  us  all  the  desired  descendants.  An  ancestor-af  rela¬ 
tion  is  similarly  defined  in  the  listing. 

Also  in  Listing  Two  are  queries  using  the  aunt-or-uncle- 
of  and  cousin-of  relations  that  are  defined  in  Listing  One. 
Notice  the  simplicity  of  the  definitions  for  these  concepts, 
and  compare  the  Prolog  versions  with  the  best  you  can 
do  using  a  language  such  as  BASIC,  Pascal,  or  C.  These 
languages  are  called  procedural  languages  because  they 
are  used  to  describe  a  procedure  to  achieve  a  certain  re¬ 
sult  as  a  sequence  of  steps  such  as:  open  files;  read  data; 
compute  a  lot;  print  answer.  Prolog,  on  the  other  hand,  is 
a  nondeterministic  language.  It  does  not  describe  the  se¬ 
quence  of  steps  needed  to  find  an  answer  but  merely 
describes  the  pattern  that  an  answer  must  fit  and  lets  the 
inference  engine  find  one  or  more  instantiations  of  the 
variables  that  satisfies  the  query  pattern. 


LISP,  the  Language  of  Artificial 
Intelligence 

LISP  is  one  of  the  oldest  viable  higher-level  programming 
languages.  It  was  revealed  to  the  world  by  John  McCar¬ 
thy  in  1960.  It  was  at  that  time  a  totally  new  way  to  look  at 
programming.  Even  today  it  is  still  very  different  from 
conventional  programming  languages  such  as  BASIC,  Pas¬ 
cal,  C,  FORTRAN,  COBOL,  or  even  assembler.  Only  other  AI 
languages  such  as  POPLER  and  PROLOG  have  similar  prop¬ 
erties.  LISP  is  a  functional  language.  A  program  consists  of 
a  set  of  function  definitions,  and  the  execution  of  a  LISP 
program  is  the  evaluation  of  a  function.  This  is  called  the 
application  of  the  function  to  its  arguments,  so  LISP  is 
called  an  applicative  language. 

In  LISP  notation,  which  has  been  called  Cambridge  Pol¬ 
ish  by  some  (distinct  from  the  Reverse  Polish  of  FORTH), 
the  function  F(y,y,z)  is  written  as  (Fyy  z). 

LISP  is  an  interpretive  language,  and  the  following  dia¬ 
log  might  occur  between  the  interpreter  and  a  program¬ 
mer  just  starting  to  experiment  with  it  (The  .$  is  the  LISP 
prompt): 

$1 

1 

The  programmer  types  1.  LISP  responds  that  the  evalua¬ 
tion  of  1  is  1. 

$(PLUS  2  3) 

5 

Adding  2  and  3  to  the  function  PLUS.  LISP  responds  that 
the  evaluation  of  the  PLUS  function  with  arguments  of  2 
and  3  is  5. 

$(TIMES  4  7) 

28 

Multiply  4  and  7.  LISP  evaluates  the  expression  and  re¬ 
turns  28. 

$(PLUS  4  (TIMES  5  9)) 
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Getting  a  little  braver,  we  try  a  nested  expression, 
4+ (5*9).  LISP  returns  the  expected  result. 

$A 

A 

We  see  what  the  value  of  A  is.  muLISP's  auto-quoting 
gives  an  unassigned  variable  the  value  of  its  name. 

$(SETQ  A  2) 

2 

SETQ  is  the  assignment  function.  It  returns  the  value  of 
the  second  argument  but  has  the  side-effect  of  making 
the  first  argument  take  on  that  value  also.  LISP  returns  the 
value  of  2. 

$A 

2 

Now  we  see  what  the  value  of  A  is.  The  SETQ  worked. 

$(SETQ  A  (PLUS  3  4)) 

7 

Perform  A =3 +4.  LISP  returns  a  value  of  7. 

$A 

7 

What  is  the  value  of  A?  Just  as  expected. 

In  LISP,  the  evaluation  process  can  be  inhibited  by  the 
use  of  the  quote  (’)  macro,  which  expands  as  follows: 

'x  expands  as  (QUOTE  x) 

The  ’  is  just  a  shorthand  because  QUOTE  is  used  so  much. 
The  QUOTE  function  inhibits  evaluation.  Let's  try  it  out: 

$(SETQ  A  '(PLUS  3  4)) 

(PLUS  3  4) 

Same  as  before  but  with  the  quote.  LISP  returns  the 
quoted  expression  verbatim,  with  no  evaluation. 

$A 

(PLUS  3  4) 

What  is  the  value  of  A?  It  has  the  value  of  the  quoted 
expression. 

We  can  force  evaluation  by  the  EVAL  function: 

$(EVAL  A) 

7 

Evaluate  the  value  of  the  variable  A.  The  evaluation  of 
(PLUS  3  4)  is  7. 


Notice  how  LISP  does  not  care  whether  a  variable  has 
numeric  or  alphabetic  information  in  it.  In  fact,  the  type 
of  a  variable  can  change  during  the  course  of  execution 
of  a  program.  LISP,  and  AI  languages  in  general,  are  dy¬ 
namically  typed  languages,  which  adds  to  both  the 
power  and  beauty  of  LISP  and  a  good  many  bugs  in  LISP 
programs.  It  is  the  responsibility  of  the  programmer  to  be 
aware  of  what  is  in  a  variable  when  he  or  she  uses  it. 

Until  now,  we  have  been  talking  about  variables  in  a 
rather  loose  sense.  In  LISP,  everything  is  either  an  atom  or 
a  list.  An  atom  is  a  thing  such  as  A  in  the  above  examples. 
Atoms  have  several  characteristics  that  are  maintained 
by  the  LISP  system.  An  atom  has  a  print  name,  which  is 
the  character  string  that  we  use  to  refer  to  the  atom.  The 
print  name  for  A  is  A.  An  atom  also  has  a  value.  The  value 
of  A  above  is  changed  several  times  by  the  use  of  SETQ 
and  is  displayed  when  we  type  the  print  name  A  at  the 
interpreter  prompt.  The  value  of  an  atom  may  be  anoth¬ 
er  atom  or  a  number,  which  is  a  special  kind  of  atom,  or  a 
list.  The  muLlSP  interpreter  assigns  the  print  name  of  an 
atom  to  its  value  when  the  atom  is  created.  To  create  an 
atom,  you  simply  use  it;  it  will  be  created  automatically  if 
it  is  not  already  present. 

When  we  assigned  (PLUS  3  4)  to  A,  we  assigned  a  list  to 
A.  This  list  is  composed  of  the  three  atoms  PLUS,  3,  and  4. 
The  last  two  atoms  are  numbers,  the  first  one  is  not  a 
number.  The  expression  (PLUS  4  (TIMES  5  9))  is  also  a  list. 
It  has  three  members;  they  are  the  atoms  PLUS  and  4  and 
the  list  ( TIMES  5  9),  which  is  itself  composed  of  the  three 
atoms  TIMES,  5,  and  9.  Thus  we  arrive  at  the  following 
recursive  definition  for  a  list: 

A  list  is  an  ordered  sequence  of  zero  or  more  atoms  or 
lists. 

This  is  fine,  but  what  do  we  have  when  we  have  zero 
rather  than  more  atoms  or  lists  in  our  list?  We  have  the 
empty  list  ( ).  This  list  occurs  so  often  that  it  has  been 
given  a  name.  The  empty  list  is  the  value  of  the  atom  NIL. 

Given  a  list  such  as: 

(ABIC  D)  (E  (F  G))H(I)) 

we  need  the  ability  to  take  it  apart  and  get  at  its  compo¬ 
nents.  The  principal  functions  for  decomposing  a  list  are 
CAR  and  CDR.  These  rather  cryptic  names  were  once 
mnemonic  in  a  machine-dependent  way.  CAR  stands  for 
contents  of  the  address  register,  and  CDR  stands  for  con¬ 
tents  of  the  decrement  register.  These  were  where  the 
address  pointers  to  the  two  halves  of  a  list  were  stored  on 
the  machine  that  ran  the  original  LISP.  Needless  to  say, 
they  have  outlived  their  mnemonic  significance,  but  his¬ 
tory  honors  the  architecture  of  the  IBM  704  anyway. 

To  extract  the  first  component  of  a  list  we  use  the  CAR 
function,  and  to  extract  the  remainder  of  the  list  we  use 
the  CDR  function.  To  make  this  easier  to  remember,  no¬ 
tice  that  the  A  in  CAR  alphabetically  precedes  the  D  in 
CDR.  CAR  gets  the  first  part;  CDR  gets  the  last  part.  Inciden¬ 
tally,  CAR  is  pronounced  just  like  the  one  you  drive  to 
work  every  day  and  CDR  is  pronounced  "could-er.”  Let’s 
try  some  examples. 
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INFERENCE  ENGINE 

(DEFUN  FACT  (LAMBDA  (N) 

(Continued  from  page  38) 

((ZEROP  N)  1) 

(TIMES  N  (FACT  (SUB1  N)»  )) 

$<SETQ  L  ’(A  B  C  D)) 

The  LAMBDA  expression  above  is  actually  used  to  de- 

(A  B  C  D) 

fine  the  function,  and  DEFUN  assigns  this  function  the 

$L 

name  FACT.  LAMBDA  can  also  be  used  to  define  a  function 

(A  B  C  D) 

that  is  used  only  once  and  not  give  that  function  a  name. 

$(CAR  L) 

Refer  to  any  good  text  on  LISP  for  more  information  about 

A 

this  strange  phenomenon. 

$(CDR  L) 

The  second  line  of  FACT  introduces  us  to  a  new  con- 

(BCD) 

struct.  The  double  nesting  of  parentheses  means  that  the 
CAR  of  that  line  is  a  predicate,  or  expression  that  evalu- 

$(SETQQ’«ABC)  D)) 

ates  to  true  or  false.  False  is  NIL,  and  true  is  anything  that 

((A  B  C)  D) 

is  not -ML.  There  is  a  special  atom  for  the  name  of  true, 

$Q 

just  like  NIL  is  the  name  for  ( ).  The  name  for  true  is  the 

((A  B  C)  D) 

atom  T.  ZEROP  is  a  predicate  that  tests  for  a  value  of  zero. 

$(CAR  Q) 

If  in  the  second  line  N=0,  then  in  the  third  line  FACT  will 

(ABC) 

return  a  value  of  2;  otherwise,  FACT  will  return  a  value  of 

$(CDR  Q) 

N  *  FACT(N  —  2  J.  The  SUBi  returns  the  number  that  is  the 

(D) 

decrement  of  its  argument. 

The  definition  for  FACT  is  recursive:  it  is  defined  in 

Now  that  we  can  take  a  list  apart,  how  can  we  put  one 

terms  of  itself.  More  conventional  languages  would  prob- 

together?  The  CONS  function  allows  us  to  build  a  list  out  of 

ably  encourage  the  programmer  to  use  an  iterative  defi- 

its  component  parts.  For  example: 

nition,  such  as  the  BASIC  program: 

$(CONS  'A  B) 

10  INPUT  N 

(A .  B) 

20  FACT  =1 

30  FACT  =  FACT*N 

This  example  is  noteworthy  because  of  the  dot  between 

40  N  =  N  —  1 

the  A  and  the  B.  In  this  case,  the  list  is  terminated  in  a 

50  IF  NOO  THEN  GOTO  30 

strange  way:  a  normal  list  is  terminated  with  NIL  as  the 
last  element,  but  it  doesn’t  print  out  that  way.  Here  the 

60  PRINT  FACT 

last  element  is  B.  The  dot  is  used  to  show  this.  To  build  a 

LISP  allows  for  iterative  constructs  also.  We  could  have 

normal  list,  we  must  terminate  with  NIL.  For  instance: 

written  FACT  as  follows: 

$(CONS  'A  NIL) 

(DEFUN  FACT  (LAMBDA  (N) 

(A) 

(SETQ  F  1) 

(LOOP 

$(CONS  ’A  '(B)) 

(SETQ  F  (TIMES  F  N» 

(A  B) 

(SETQ  N  (SUBI  N)) 

$(CONS  '(A  B)  '(C  D)) 

((A  B)  C  D) 

((ZEROP  N)  F) ) )) 

The  LOOP  function  repeats  the  evaluation  of  each  of  its 

$(SETQ  U  '(X  Y  Z)) 

elements  in  turn,  until  a  conditional  expression  is  satis- 

(XYZ) 

lied,  at  which  time  the  loop  exits.  The  iterative  form  of  a 

$(SETQ  V  ’(A  B  C)) 

simple  loop  such  as  this  will  usually  run  faster  than  its 

(ABC) 

recursive  counterpart,  but  some  problems,  such  as  we 

$(SETQ  W  (CONS  U  V)) 

will  see  in  the  unification  algorithm  later  on,  demand 

((X  Y  Z)  A  B  C) 

recursion.  It  is  hard  to  imagine  anyone  who  would  find 

$(CAR  W) 

the  iterative  definition  easier  to  understand  than  the  re- 

(XYZ) 

cursive  definition;  it  is  very  much  like  the  verbal  defini- 

$(CDR  W) 

tion.  Furthermore,  it  naturally  handles  the  case  for 

(ABC) 

FACT(0),  which  requires  an  extra  IF  in  the  iterative  rou¬ 
tine. 

Thus  we  can  see  that  (CONS  (CAR  L)  (CDR  D)  is  just  L  itself. 

The  muLISP  programming  environment,  muSTAR,  in- 

Let’s  try  writing  a  function  of  our  own.  We  will  take 

eludes  a  built-in  full-screen  editor  and  pretty  printer  and 

the  factorial  function.  Factorial  (n)  is  defined  as  the  prod- 

a  complete  interactive  debugger  and  program-monitor- 

uct  of  all  the  numbers  from  1  to  n,  so  factorial  (1)= 1,  facto- 

ing  package.  I  started  using  muLISP  with  the  muLISP-80 

rial  (2) =2,  factorial  (3) =6,  factorial  (4) =24,  and  so  on. 

version  on  8-bit  CP/M  and  have  used  muLISP-82  on  the  IBM 

DEFUN  is  a  LlSP-supplied  function  that  defines  functions. 
The  following  code  implements  a  factorial  function: 

PC,  and  I  am  now  using  muLISP-83  on  an  IBM  PC. 
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A  Cellular  Automaton 
Written  in  Expert-3 


It's  been  nearly  two  years  since  I 
first  wrote  the  simple  expert  sys¬ 
tem  for  predicting  local  weath¬ 
er.1  Since  then,  many  individuals 
have  taken  to  experimenting  with  Ex¬ 
pert-2,  and  some  interesting  things 
have  happened  along  the  way.  For 
openers,  Expert-2  was  originally  pub¬ 
lished  as  a  learning  tool2  that  would 
be  available  to  users  for  experimenta¬ 
tion  and  perhaps  for  writing  their 
own  versions  implementing  infer¬ 
ence  engines  considerably  improved 
over  the  original  Expert-2. 

But  that  hasn't  stopped  some  from 
doing  important  things  with  the  tool. 
One  group,  for  example,  has  written 
an  expert  system  for  diagnosing  user 
problems  with  a  satellite.  Another  in¬ 
dividual  has  begun  developing  ex¬ 
perimental  medical  diagnostic  tools 
with  Expert-2. 

In  the  meantime,  my  closet  affec¬ 
tion  for  weather  prediction  persists, 
so  I  became  interested  in  systolic  ar¬ 
rays  for  taking  grid  data,  performing 
blazing  calculations,  and  pontificat¬ 
ing  on  future  events.  It  turns  out  that 
such  a  systolic  array  is  easy  to  visual¬ 
ize  as  a  cellular  automaton,  an  array 
of  cells  that  communicate  with  their 
nearest  neighbors. 

Inserting  intelligence  into  each  cell 
seems  a  logical  point  of  departure, 
the  idea  being  that  “smart''  cells 
could  at  first  use  knowledge  provid¬ 
ed  by  outside  experts  to  begin  issuing 
pronouncements.  Later,  such  cells 
could  implement  learning  strategies 
for  improving  their  predictions. 

Imagine  the  earth  as  a  globe  cov¬ 
ered  with  hexagonal-shaped  grid 
lines.  Each  cell  enclosed  by  a  Set  of 
grid  lines  could  be  100  miles  across. 


Jack  Park,  P.O.  Box  326,  Brownsville, 
CA  95919 


by  Jack  Park 


The  ultimate  idea  is 
that  each  cell  could  be 
an  individual 
computer. 


Choose  any  size  and  shape  cell.  If  you 
choose  an  octagon,  the  cell  will  com¬ 
municate  with  eight  neighbors.  The 
octagon  is  the  shape  used  in  the  pro¬ 
gram  presented  here. 

The  ultimate  idea  for  the  systolic 
array  model  is  that  each  cell  could,  in 
theory,  be  an  individual  computer, 
complete  with  its  own  inference  pro¬ 
gram,  database,  and  knowledge  base 
along  with,  say,  nine  communica¬ 
tions  ports.  That’s  eight  ports  for 
nearest-neighbor  linkage  and  one  ex¬ 
tra  to  send  out  the  individualized  re¬ 
sults.  In  a  more  common  systolic  con¬ 
figuration,  the  final  outputs  travel 
across  the  array  in  so-called  systolic 
waves  until  they  reach  an  edge.  In 
the  array  imagined  for  weather  pre¬ 
diction,  there  would  be  no  edge. 
That's  just  one  candidate  architec¬ 
ture  for  the  weather  prediction  task. 

That  architecture,  at  least  for 
weather  prediction,  seems  reason¬ 
able,  especially  when  you  consider 
that  weather  in  any  given  cell  is  af¬ 
fected  by  the  weather  of  the  nearest 
neighbor  cells  as  well  as  the  weather 
within  the  cell  itself.  Knowledge 
about  that  weather  may  be  cell-spe¬ 
cific,  just  as  one  considers  the  differ¬ 
ences  between  polar  and  tropical  en¬ 
vironments. 


In  any  event,  the  program  listed 
with  this  article  (Listing  One,  page  74) 
models  the  action  of  a  cellular  au¬ 
tomaton  as  best  a  lone  Von  Neumann 
computer  chip  can.  It  is  not  modeled 
as  a  systolic  array  but  as  a  do  loop 
that  treats  each  cell  individually  in  a 
fashion  similar  to  the  way  in  which  a 
multiprocessor  systolic  array  would 
treat  each  cell.  It's  only  a  model.  John 
Conway's  game  of  Life  was  chosen 
for  this  test  on  the  basis  that  it  is  well 
documented,  never  ceases  to  please, 
and  is  quite  easy  to  understand. 

The  Game  of  Life 

Because  Life  is  so  well  documented,  I 
won't  go  into  how  it  works  other  than 
to  point  out  that  each  cell  represents 
an  entity  that  is  either  alive  or  not 
alive.  The  state  of  each  entity  is  deter¬ 
mined  by  a  group  of  rules  that  use  the 
states  of  each  individual's  nearest 
neighbors  as  parameters.  Thus,  the 
game  models  an  ecological  system  of 
sorts  and  as  such  is  a  reasonable  trial 
model  along  the  path  of  developing 
more  complex  modeling  systems. 

The  prime  issue  developed  by  the 
program  is  the  interface  between  the 
numeric  aspects  of  the  model — in 
this  case,  the  simple  counting  of  liv¬ 
ing  nearest  neighbors  and  the  knowl¬ 
edge-based  intelligence  that  guides 
the  history  of  a  cell.  This  program  il¬ 
lustrates  the  repetitive  calling  of  the 
inference  system  from  inside  a  do 
loop  that  executes  256  times  per  dis¬ 
play  pass.  With  this  technique  it  is 
possible  to  couple  knowledge  to  pro¬ 
cedural  activities  on  a  repetitive  basis 
and  effectively  watch  what  a  systolic 
array  system  would  otherwise  do 
quite  quickly. 

Life  gives  us  a  chance  to  study  the 
performance  of  an  inference  engine. 
Expert-2  takes  about  28  seconds  to  ex¬ 
ercise  a  single  pass.  The  cell-counting 
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procedure  takes  about  2  seconds, 
leaving  about  26  seconds  for  the  infer¬ 
ence  mechanism  to  run  256  times.  An 
experimental  inference  engine  of  a 
completely  different  design  much 
closer  to  native  Forth  takes  about  4 
seconds  per  pass;  with  the  same  2-sec- 
ond  numeric  part,  that's  about  2  sec¬ 
onds  for  the  inference  part.  This  sta¬ 
tistic  is  interesting  because  it  gives 
some  evidence  of  Expert-2's  absolute 
performance:  the  experimental  infer¬ 
ence  engine  benchmarks  at  about 
2,700  logical  inferences  per  second 
and  runs  Life  about  13  times  as  fast  as 
Expert-2  does.  The  implication  is  that 
Expert-2  runs  about  200  LIPS,  which 
isn't  all  that  fast — so  you  tell  your 
friends  “it's  pensive." 

There's  more  to  the  timing  than 
that;  for  example  the  newer  infer¬ 
ence  engine  has  added  features,  such 
as  disjunctive  clauses  (those  coupled 
with  06  or  ORNOT).  If  users  add  such 
clause  compilers  to  their  Expert-2, 
fewer,  more  powerful  rules  could  be 
written  for  the  cell  knowledge  base, 
and  the  program  would  run  faster. 
So  it  turns  out  that  inference  speed  is 
partly  a  function  of  the  inference  en¬ 
gine  algorithm  and  partly  a  function 
of  the  knowledge  base  itself.  I  leave  it 
as  an  exercise  for  Expert-2  experi¬ 
menters  to  see  just  how  fast  they  can 
get  the  inference  part  of  this  pro¬ 
gram  to  run. 

There's  another  thing  I  leave  to  ex¬ 
perimenters  who  want  to  try  run¬ 
ning  Life  on  their  Expert-2:  it  turns 
out  that  the  inference  engine  will 
happily  write  all  over  the  video  what 
it  deduces  on  each  of  the  256  passes 
per  epoch.  That,  of  course,  is  unac¬ 
ceptable,  especially  because  it  wipes 
out  the  pretty  grid  display.  So  a  fea¬ 
ture  must  be  added  to  Expert-2  that 
suppresses  any  deduction  or  conclu¬ 
sion  printing.  This  feature  is  set  to 
the  suppress  mode  by  the  word  NO- 
SHOW  and  defaults  to  SHOW. 

Perhaps  one  of  the  more  striking 
features  of  the  program  is  the  separa¬ 
tion  of  knowledge  from  all  the  proce¬ 
dural  stuff.  The  rules  listed  between 
the  Forth  words  RULES  and  DONE 
completely  capture  all  the  knowl¬ 
edge  required  for  determination  of 
the  next  state  of  any  cell.  This  separa¬ 
tion  makes  it  a  very  simple  matter  to 
rewrite  the  rules  governing  the  life 
history  of  individual  cells  and  exam¬ 
ine  the  impact  of  those  revised  rules 


on  the  ecology  of  the  small  closed 
world. 

One  other  point  is  worth  consider¬ 
ing:  the  world  this  exercise  models  is 
a  16-by-16  array  with  the  respective 
edges  connected  such  that  the  world 
looks  like  a  torus.  This  shape  makes 
for  some  strange  edge  effects.  What 
you  see  on  the  display  is  just  the  flat 
“apparent”  world.  You  can  easily  in¬ 
crease  the  array  size  and  leave  the 
edges  free  or  otherwise  change  the 
model.  A  24-by-24  array  would  easily 
fit  on  the  display  of  most  computers. 

The  entire  program  compiles  on 
top  of  Expert-2,  which,  of  course,  is 
compiled  on  top  of  Forth.  Expert-2 
will  automatically  separate  the  colon- 
defined  procedural  stuff  from  the 
knowledge  base  at  the  end  of  the  list¬ 
ing. 

A  Single-Hypothesis  Method 

This  implementation  of  a  knowledge 
base  illustrates  a  single-hypothesis 
method  of  forcing  the  inferencing 
process.  In  short,  Expert-2  tries  to 
prove — by  the  backward  chaining 
method — some  goal  hypothesis.  In 
this  case  there  is  only  one  hypothe¬ 
sis,  cell  propagates.  In  order  to  prove 
that  hypothesis,  the  last  rule  shows 
that  the  inference  engine  must  first 
prove  the  cell  does  not  live,  then  that 
it  does  not  die.  If  it  neither  lives  nor 
dies,  then  it  continues  on  (either  liv¬ 
ing  or  not  living).  Suppose,  however, 
that  the  counts  are  such  that  the  cell 
lives  (remember  that  this  whole  in¬ 
ference  procedure  runs  once  for 
each  of  256  individual  cells).  If  the 
cell  lives — as,  for  example,  if  the  first 
rule  happens  to  fire — then  the  com¬ 
puter  deduces  cell  lives  but  neglects 
to  tell  you  it  deduced  that  (remember 
NOSHOW),  thus  firing  the  ANDTHEN- 
RUN  LIVE  consequent  clause  and 
causing  the  hypothesis  rule  to  fail.  At 
that  point,  Expert-2  would  be  happy 
to  tell  you  it  cannot  conclude  any¬ 
thing,  but  amnesia  again  sets  in  be¬ 
cause  of  NOSHOW.  Then  off  to  the 
next  cell. 

A  key  point  to  notice  here  is  that 
Expert-2  wants  a  symbolic  reference 
on  which  to  base  its  inferences.  The 
symbolic  reference  written  into  this 
program  is  the  THEN  clause  that 
states  the  rule's  consequence  (e.g., 
cell  lives,  cell  dies,  etc.).  Such  string 
clauses  make  the  rules  quite  read¬ 
able.  Furthermore,  when  combined 


EXPERT-2 


with  the  numeric  or  procedural 
clauses  (e.g.,  ANDRUN  COUNT  =  2) 
such  symbolic  clauses  create  one 
way  an  inference  engine  can  com¬ 
bine  powerful  symbolic  inferencing 
with  numeric  processing.  Of  course, 
you  could  rewrite  the  rule  compiler 
to  allow  in-line  code — that  is,  to  al¬ 
low  you  to  write  into  the  rule  the 
equation  you  want  solved.  I  have 
chosen  to  separate  numeric  and  sym¬ 
bolic  representations,  suspecting 
there  might  be  some  code  economies 
caused  by  multiple  calls  to  the  same 
(or  similar)  procedures  from  differ¬ 
ent  rules.  Thus,  the  rules  simply 
trade  on  either  symbolic  clauses  or 
name  fields  of  colon-defined  proce¬ 
dures.  This  leads  to  some  wild  specu¬ 
lations  on  potential  nonmonotonic 
reasoning  strategies  where  one  of 
the  callable  procedures  is  none  other 
than  DIAGNOSE,  the  main  inference 
routine — which  is  something  like 
your  mutt  chasing  its  tail. 

Included  is  a  pair  of  pattern  initial¬ 
ization  words:  EATER  and  PENTA ;3 
they  are  supposed  to  act  as  oscilla¬ 
tors.  You  can  also  add  other  initializ¬ 
ing  patterns.  You  must  initialize  an 
array  before  running  it  by  typing 
one  of  the  patterns  and  then  typing 
the  word  RUN  to  start  the  whole 
works  off.  Tap  the  space  bar  to  kill  a 
run — it  will  stop  after  the  next  dis¬ 
play  or  after  32  cycles.  Enjoy. 

Notes 

1.  J.  Park.  "Expert  Systems  and  the 
Weather,”  DDJ  90  (April  1984). 

2.  J.  Park.  Expert  Toolkit  (Mountain 
View,  Calif.:  Mountain  View  Press, 
1984).  Also  available  from  Parsec  Re¬ 
search  and  Miller  Microcomputer 
Service. 

3.  David  Buckingham.  “Some  Facts  of 
Life,”  Byte  (December  1978). 
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Modeling  a  Svste 


in  PROLOG 


This  article  discusses  the  diffi¬ 
culty  of  specifying  large  soft¬ 
ware  systems  and  how  you 
can  model  them  on  a  personal  com¬ 
puter  if  you  use  the  right  language. 
Software  now  costs  much  more  than 
its  hardware  if  the  system  is  really 
large.  The  Department  of  Defense  is 
so  concerned  about  this  problem  that 
it  has  instituted  a  program  to  tackle 
it.1 

The  biggest  difficulty  seems  to  be 
getting  the  specifications  right  for  a 
system  so  that  what  is  built  is  really 
what  is  wanted.  Experience  shows 
that  you  must  first  find  answers  to 
the  following  questions: 

•  What  do  the  users  want  to  input? 

•  How  do  they  want  to  exercise 
control? 

•  What  do  they  want  the  output  to 
look  like? 

•  What  kind  of  logical  relations  are 
needed  to  support  the  above  needs? 

•  Do  the  obvious  processing  goals 
really  satisfy  the  stated  require¬ 
ments? 

What  is  needed  to  answer  the 
above  questions  properly  is  an  exe¬ 
cutable  model  of  the  entire  system. 
This  would  be,  in  the  strictest  sense 
of  the  word,  a  functional  specifica¬ 
tion.  It  would  allow  the  users  to  get  a 
hands-on  feel  of  how  the  system  ser¬ 
viced  them;  even  more  important,  it 
would  be  complete  enough  to  verify 
the  adequacy  of  the  requirements 
and  logical  structure  needed.  Cur¬ 
rent  thought  about  software  devel¬ 
opment  seems  to  be  focusing  on  exe- 
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How  do  you  produce 
a  program  that  runs 
like  the  real  system 
without  being  the  real 
system? 


cutable  specifications  as  necessary 
tools  for  effective  development.2 

How  do  you  produce  a  computer 
program  that  executes  like  the  real 
system  does  without  its  being  the 
real  system?  The  idea  is  to  save  mis¬ 
takes  (and  money)  by  getting  a  trial 
run  of  the  whole  system’s  important 
features,  but  it  must  be  done  cheap¬ 
ly.  Using  rapid  prototyping  has  be¬ 
come  popular  because  some  features 
needed  in  the  final  system  are  not 
needed  in  a  prototype.  For  example, 

•  The  prototype  doesn't  have  to  be  as 
fast  as  the  intended  product. 

•  It  doesn’t  need  to  handle  the  intend¬ 
ed  full-size  database. 

•It  doesn't  need  to  be  in  the  target 
language  or  on  the  target  machine. 

•  It  doesn't  have  to  be  free  from  er¬ 
rors  or  contain  provision  for  error 
management. 

Because  these  features  are  unneces¬ 
sary,  it  is  possible  to  model  a  large 
system  cheaply. 

Modeling  an  entire  system  calls  for 
something  extra  by  way  of  represent¬ 
ing  the  specification — namely,  a 
specification  language  created  ex¬ 
pressly  for  this  purpose.  Several  lan¬ 
guages  are  available,  but  only  very  re¬ 


cent  ones  produce  specifications  that 
can  be  executed.  I  will  show  here 
how  the  well-known  logic  program¬ 
ming  language  PROLOG  has  many  fea¬ 
tures  that  make  it  ideal  for  expressing 
such  executable  specifications. 

Advantages  of  PROLOG 

It's  desirable  that  you  be  able  to  read 
a  specification  without  a  week's 
training  course  to  learn  a  new  lan¬ 
guage.  I  shall  show,  in  an  example, 
how  simple  the  format  is  for  micro- 
PROLOG  from  Logic  Programming  As¬ 
sociates.  Any  engineer  or  program¬ 
mer  should  be  able  to  read  a  modest 
PROLOG  program  after  studying  the 
language  for  an  hour  or  two.  PROLOG 
stands  for  "programming  in  logic," 
and  it's  not  surprising  that  it  shows 
clearly  the  logical  structure  required 
for  a  system. 

PROLOG  also  acts  as  an  aid  to  design. 
This  follows  immediately  from  the 
form  of  its  sentences  (rules  or  facts). 
The  structure  of  the  language  actual¬ 
ly  encourages  the  usual  hierarchical 
decomposition  of  functions  into  sub¬ 
functions.  When  a  specification  be¬ 
comes  unwieldy  to  express  in  PRO¬ 
LOG,  maybe  the  wrong  thing  is  being 
attempted. 

A  third  advantage  of  the  language 
is  that  it  it  helps  to  demonstrate  I/O. 
It  has  features  that  provide  both  out¬ 
put,  as  part  of  language  sentences, 
and  the  ability  to  request  input  as  a 
consequence  of  execution.  The  most 
commonly  used  form  of  output  is  an¬ 
swers  to  queries  about  the  contents 
of  a  database. 

In  terms  of  cost-effectiveness,  PRO¬ 
LOG  couldn't  be  better.  The  edition  I 
am  using  costs  less  than  $300  (on  a 
disk)  and  runs  on  a  computer  that 
costs  less  than  $700  (Osborne  1). 

It  is  important  that  an  executable 
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specification  does  not  tempt  custom-  j 
ers  to  use  it  as  a  cheap  substitute  for  ] 
the  real  software  product.  The  con- 
sequences  of  this  happening  are  di-  ] 
sastrous;  they  frequently  discourage 
any  use  of  prototyping  that  might  be 
mistaken  for  part  of  the  final  prod-  | 
uct.  The  advantage  of  a  cheap  PRO¬ 
LOG  that  runs  on  a  cheap  computer  is 
that  it  is  unlikely  to  support  either 
the  speed  or  the  size  of  a  real-world 
information  system  and  thus  the  re¬ 
sulting  prototype  could  not  be  mis¬ 
taken  for  the  final  product. 

PROLOG'S  weakest  point  is  the  way 
in  which  it  models  the  intended  envi-  j 
ronment.  Any  simulation  of  the  tar¬ 
get  implementation  environment 
would  have  to  be  provided  in  the  log-  | 
ical  structure  of  the  program  (which 
is  quite  possible  but  must  be  done  by  j 
the  designer). 

A  System  Described  in 
PROLOG 

I  have  chosen  to  model  a  hospital  ad¬ 
ministrative  information  system. 
Greenspan,  Mylopoulos,  and  Borr 
gida3  used  such  a  system  to  demon¬ 
strate  their  custom-built  specification 
language,  RMF.  I  am  indebted  to  them 
for  suggesting  this  type  of  system  j 
and  for  the  stimulation  that  led  to 
PROLOG  usage.  The  suggestion  that 
PROLOG  would  be  good  for  stating 
specifications  was  actually  made  by 
Shapiro,4  but  I  haven’t  seen  any  im¬ 
plementation  of  the  suggestion. 

!  Most  information  systems  must 
j  store  a  common  core  of  reference 
j  data  about  their  subjects.  The  prima- 
i  ry  subject  of  the  information  system  ; 

in  this  example  is  the  hospital  pa-  ; 
j  tient;  the  basic  core  of  reference  data  j 
[  for  a  patient  certainly  includes 

•  Last  name,  first  name,  initial 

•  Social  security  number 

•  Address:  street  and  number,  city, 
state,  ZIP 

•  Phone 

Some  basic  ID  number  must  be  cho-  : 
sen  for  a  subject;  I  have  chosen  the 
social  security  number  as  the  prima-  j 
ry  identifier  for  a  hospital  patient.  All 
other  data  items  are  keyed  to  this  one  J 
for  an  individual  patient.  I  make  each  ; 

|  of  the  simplest  items  above  into  a  sin-  J 
gle  fact  about  the  patient  and  give  it  a  J 
PROLOG  name  that  shows  the  func-  j 
i  tion  of  the  data  item.  This  functional  j 


name  is  called  a  predicate.  The  above 
facts  are  represented  in  the  form 

(predicate  data-value  ID-value) 

which  for  a  patient  named  Humpty 
Dumpty  could  be: 

(social-sec-no  S4064) 

(firstname-ini  Humpty  S4064) 
(lastname  Dumpty  S4064) 
(housenumber  H4701  S4064) 

(street  Broadway  S4064) 

(city  Provo-Utah  S4064) 

(zip  P89201  S4064) 

(phone  405  "  —  "  1191  S4064) 

PROLOG  actually  allows  any  num¬ 
ber  of  data  values  or  ID  values  to  be 
contained  in  a  fact,  following  the 
predicate.  You  can  pull  together  sev¬ 
eral  facts  about  the  same  patient  by 
defining  a  rule  that  enumerates 
those  facts,  with  data  items  men¬ 
tioned  as  variables  instead  of  as  con¬ 
stants  in  the  referenced  facts.  A  PRO¬ 
LOG  rule  defines  the  relation 
person-id  as  the  simultaneous  match¬ 
ing  of  facts  about  a  patient:  firstname- 
ini,  lastname,  and  social-sec-no,  as 
shown  in  Table  1,  page  48.  Note  that 
the  common  variable  name  in  all  the 
facts  is  social-sec-no.  Note  also  that  I 
have  used  imitation  social  security 
numbers  of  only  four  digits  as  a  con¬ 
venience. 

The  only  thing  you  have  to  learn  to 
write  such  PROLOG  sentences  is  the 
meaning  of  the  punctuation.  The 
whole  sentence  must  be  enclosed  in 
outer  parentheses,  the  relation 
clause  being'  defined  by  the  rule 
must  be  the  first  clause  and  be  en¬ 
closed  in  parentheses,  and  each 
other  clause  that  must  be  matched 
for  the  rule  to  be  satisfied  must  also 
be  enclosed  in  parentheses.  The  first 
item  appearing  in  each  clause  is  the 
name  of  that  fact  or  rule,  and  is 
called  a  relation  (or  predicate).  There 
is  an  implied  IF  after  the  relation 
clause  being  defined  and  implied  log¬ 
ical  ANDs  between  all  the  clauses  that 
support  the  relation.  Thus  you 
would  read  the  rule  in  Table  1  as: 
(person-id  X  Y  Z)  IF  (lastname  Y  Z) 
AND  (firstname-ini  X  Z)  AND  (social- 
sec-no  Z). 

The  power  of  PROLOG  rules  is  that  a 
rule  can  reference  other  rules  as  well 


((person-id  X  Y  Z) 

(lastname  Y  Z) 

(firstname-ini  X  Z) 
(social-sec-no  Z)) 

((firstname-ini  B  SI  23)) 
((firstname-ini  Tom-T  S3475)) 
((firstname-ini  Mrs-Jack-S  S4831)) 
((firstname-ini  Humpty  S4064)) 
((firstname-ini  Don  S4776)) 
((firstname-ini  Don  S4895)) 
((lastname  A  SI 23)) 

((lastname  Thumb  S3475)) 
((lastname  Spratt  S4831)) 
((lastname  Dumpty  S4064)) 
((lastname  Giovanni  S4776)) 
((lastname  Quixote  S4895)) 
((social-sec-no  SI  23)) 
((social-sec-no  S3475)) 
((social-sec-no  S4831)) 
((social-sec-no  S4064)) 
((social-sec-no  S4776)) 

|  ((social-sec-no  S4895)) 


Table  1 


((address  X  Y  Z  x  y  z  XI  Y1  Z1) 
(person-id  X  Y  Z) 
(housenumber  x  Z) 

(street  y  Z) 

(city  z  Z) 

(zip  XI  Z) 

(phone  Y1  ”  Z1  Z)) 
((housenumber  C  SI  23)) 
((housenumber  HI 4085  S3475)) 
((housenumber  HI 808  S4831)) 
((housenumber  H4701  S4064)) 
((housenumber  H3851  S4776)) 
((housenumber  H21 105  S4895)) 
((street  D  SI  23)) 

((street  Abelson-St  S3475)) 
((street  Rose-Way  S4831)) 
((street  Broadway  S4064)) 
((street  Alameda  S4776)) 

((street  El-Camino  S4895)) 

((city  E  SI  23)) 

((city  San-Carlos  S3475)) 

((city  Burlingame  S4831)) 

((city  Provo-Utah  S4064)) 

((city  Menlo- Park  S4776)) 

((city  Palo-Alto  S4895)) 

((zip  G  SI  23)) 

((zip  P94065  S3475)) 

((zip  P94072  S4831)) 

((zip  P89201  S4064)) 

((zip  P94025  S4776)) 

((zip  P94043  S4895)) 

((phone  923  1436  SI 23)) 

((phone  364  2915  S3475)) 

((phone  291  1507  S4831)) 

((phone  405  1191  S4064)) 

((phone  329  “-’’51  S4776)) 
((phone  326  8195  S4895)) 

.  Table  2 
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as  facts.  Thus  complex  relationships 
can  be  functionally  decomposed  by 
nesting  rules  within  rules  within 
rules  and  so  on  until,  at  the  bottom 
level,  only  facts  are  referenced.  A 
simple  example  of  this  is  the  defini¬ 
tion  of  the  relation  address  shown  in 
Table  2,  page  48,  in  which  the  relation 
person-id  is  used  and  all  the  rest  of  the 
clauses  are  simply  facts. 

There  are  some  more  complex 
conditions  for  entering  a  patient  into 
a  hospital  database  than  those  I  have 
discussed  so  far.  For  example,  several 
checks  must  be  made  before  admis¬ 
sion  is  complete: 

•  Is  there  room  left  in  the  hospital? 

•  Can  the  patient  pay? 

•  Has  the  patient’s  personal  data  been 
entered? 

•  Has  the  patient  been  assigned  to  a 
ward? 

•  Has  the  patient  been  assigned  both 
an  attending  physician  and  consult¬ 
ing  physician? 

•  Does  the  specialty  of  one  of  these 
physicians  match  the  type  of  ward 
that  was  assigned? 


Although  many  other  conditions 
are  associated  with  entering  a  hospi¬ 
tal,  these  suffice  to  demonstrate  how 
PROLOG  encourages  hierarchical  de¬ 
composition  of  the  functions  of  a  sys¬ 
tem.  A  clear  expression  of  the  above 
conditions  requires  some  deeply 
nested  rules,  which  can  be  arrived  at 
bottom-up  or  top-down,  as  you  wish. 

Table  3,  below,  shows  these  rules 
top-down.  The  relation  in-hospital  is 
true  if  there  is  a  person-id  and  an  ad- 
mit-date  but  not  a  release-date  or  a 
died-on  date.  There  is  an  admit-date 
for  the  patient  if  the  rule  for  admit- 
patient  has  been  satisfied.  (ADDCL  puts 
that  clause  in  the  database;  DELCL  re¬ 
moves  the  clause.)  This  is  a  deeply 
nested  rule  that  uses  a  check  for 
room-is-left-for  and  the  data  provid¬ 
ed  for  submit-patient.  Room-is-left-for 
counts  the  total  patients  if  the  admis¬ 
sion  takes  place  and  verifies  that  the 
person-id  isn't  already  admitted.  Sub¬ 
mit-patient  checks  the  physician  and 
ward  assignments  and  whether  the 
patient  is  financially  responsible  and 
provides  reference  to  current-date.  It 
refers  to  the  specialty-match  relation, 


tions.  When  answers  are  exhausted, 
PROLOG  prints  "No  more  answers.” 

The  type  of  query  that  prints  val¬ 
ues  consists  of  all( Hist  of  some  var¬ 
iables  )( some  fact  or  rulejfsome  other 
fact  or  rulejfetc  .  .  .))  with  each  vari¬ 
able  in  the  list  mentioned  in  at  least 
one  of  the  rules  that  are  referenced. 
The  yes/no  query  is  "ask  (a  rule  with 
values  already  substitutedKanother 
such  ruleMetc  .  .  .).”  Table  5,  page  50, 
shows  some  queries  of  rules  I  have 
described  in  the  hospital  database. 

Using  PROLOG  for  a 
Specification  Tool 

Obviously  the  expression  of  a  specifi¬ 
cation,  such  as  the  one  in  this  exam¬ 
ple,  doesn't  replace  the  document 
you  are  already  familiar  with — it 
complements  it.  Most  customers  for 
large  software  systems  have  their  es¬ 
tablished  requirements  for  an  initial 
specification  that  is  written  in  text. 
The  executable  specification  should 
be  looked  upon  as  a  useful  extension 
to  prototyping  and  a  help  in  experi¬ 
menting  with  designs.  This  tech¬ 
nique  is  so  inexpensive  that  it  should 
be  accessible  to  everyone  who  devel¬ 
ops  software  or  studies  systems. 
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((in-hospital  X  Y  Z  x) 

(person-id  X  Y  Z) 

(admit-date  x  Z) 

(NOT  release-date  y  Z) 

(NOT  died-on  z  Z)) 

((admit-patient  X  Y) 

(/*  admits  patient  after  checking  for  space  and  assignments) 
(room-is-left-for  X  Y  Z) 

(submit-patient  Y  x) 

(DELCL  ((patient-count  Z))) 

(ADDCL  ((patient-count  X))) 

(ADDCL  ((admit-date  x  Y)))) 

((room-is-left-for  X  Y  Z) 

(/*  checks  new  patient-count  against  available  space,  and  whether) 
(/*  person  not  yet  admitted,  but  personal  data  entered) 
(patient-count  Z) 

(SUM  Z  1  X) 

(room  x) 

(OR  ((LESS  X  x))  ((EQ  X  x))) 

(person-id  y  z  Y) 

(NOT  admit-date  XI  Y)) 

((submit-patient  X  Y) 

(/*  checks  ability  to  pay  and  MD,  ward  assignments) 

(can-pay  X) 

(ward-name  Z  X) 

(atten-phys  x  X) 

(cons-phys  y  X) 

(specialty-match  x  y  Z) 

(current-date  Y)) 


Table  3 


Dr.  Dobb's  Journal,  April  1986 


49 

257 


ARTICLES 


A  68000  Cross 
Assembler — Part  1 


I  tend  to  be  obsessive.  For  more 
than  two  years  I  have  been  ad¬ 
miring  the  Motorola  68000  from 
afar,  wanting  to  do  something  with  it 
but  not  knowing  quite  what.  Al¬ 
though  I've  worked  a  bit  with  assem¬ 
bly  language  and  with  microproces¬ 
sor  hardware  (Z80,  Z8000,  and 
M6800),  I  wasn't  really  what  you’d 
call  a  “let's  get  close  to  the  metal" 
type  of  hacker.  What  to  do? 

My  love  affair  with  Modula-2  start¬ 
ed  about  a  year  ago.  After  coming  up 
through  FORTRAN,  Pascal,  and  C 
(with  a  smattering  of  COBOL,  BASIC, 
and  even  LISP  thrown  in),  Modula-2 
seemed  an  ideal  language.  Here  was 
a  high-level  structured  language  that 
you  could  actually  use  to  write  oper¬ 
ating  systems,  and  unlike  C,  even 
make  sense  of  the  code  afterward.  I 
had  it!  I'd  write  a  68000  assembler  in 
Modula-2. 1  was  off  to  the  races. 

Bottoms  Up? 

Modula-2  is  a  great  language  for  both 
top-down  and  bottom-up  design.  The 
top-down  aspect  is  usually  more  high¬ 
ly  touted,  but  often  the  immediate 
need  is  for  some  tool  so  that  you  can 
proceed  with  a  design.  The  first  thing 
I  realized  as  I  started  to  plan  this  pro¬ 
ject  was  that  I  would  need  some  way 
to  handle  32-bit  integers.  The  68000 
uses  operands  that  are  up  to  32  bits 
wide,  whereas  the  implementation  of 
Modula-2  that  I  was  using  (Hoch- 
strasser’s  Modula-2  System  for  Z80  CP/ 
M)  provided  only  16-bit  integers,  as  the 
compiler  was  written  before  Wirth 
amended  the  language  to  include 
LONGINT,  LONGCARD,  and  LONG- 
REAL. 

My  first  task,  then,  was  to  create  a 
bottom-up  module  to  handle  the  32- 
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The  first  thing  I 
realized  is  that  I 
would  need  some  way 
to  handle  32-bit 
integers. 


bit  numbers  I  would  need  through¬ 
out  the  project.  The  LongNumbers 
module  provides  all  the  facilities  to 
input,  manipulate,  and  output  a  new 
data  type  that  I  called  LONG,  which 
acts  essentially  as  an  8-digit  hexadeci¬ 
mal  number.  Although  I  could  have 
used  assembly  language  or  tricky 
machine-dependent  low-level  Mod¬ 
ula-2  code  to  create  a  more  efficient 
implementation,  I  decided  to  forego 
efficiency  for  portability  because  I 
plan  to  transport  the  assembler  to 
other  environments.  (I  have  ported 
the  assembler  to  the  IBM  PC  using  the 
Logitech  compiler.) 

Listing  One,  page  76,  shows  the 
definition  module  for  LongNumbers. 
The  type  LONG  is  simply  an  array  of 
INTEGER.  I  chose  INTEGER  instead  of 
CARDINAL  or  subrange  [0 . .  15]  to 
ease  handling  of  carry /borrow  in 
the  arithmetic  procedures.  Most  of 
the  procedures  are  pretty  straight¬ 
forward,  but  some  may  need  clarifi¬ 
cation.  CardToLong  and  LongToCard 
provide  conversions.  This  allows 
some  flexibility  so  the  assembler  can 
accept  68000  addressing  offsets  (and 
even  constants)  in  either  hexadeci¬ 
mal  or  decimal.  Because  CARDINAL 
has  a  much  smaller  range  than  LONG 
has,  not  all  conversions  are  possi¬ 
ble — LongToCard  returns  FALSE  in 
such  cases.  StringToLong  converts  a 
sequence  of  ASCII  characters  into  a 


LONG,  returning  FALSE  if  any  illegal 
character  is  encountered.  Like  much 
of  the  code  that  I  write  now,  Long- 
Compare  is  patterned  after  a  similar 
C  routine  for  comparing  strings.  The 
two  output  routines,  LongPut  and 
LongWrite,  are  different  from  the 
rest  of  the  routines  in  that  they  don’t 
actually  use  type  LONG ;  instead,  they 
use  open  array  parameters,  which 
allows  them  to  output  an  arbitrary 
sequence  of  hex  digits.  The  last  two 
routines,  AddrBoundW  and  Addr- 
BoundL,  are  needed  because  the 
68000  insists  that  certain  types  of  in¬ 
structions  and  data  begin  at  “even” 
addresses. 

One  other  bit  of  bottom-up  design 
occurred  at  the  beginning  of  this  pro¬ 
ject  and  resulted  in  a  general-pur¬ 
pose  library  routine.  I've  always 
liked  the  way  C  handles  command 
line  arguments  (with  the  standard 
parameters  ArgC  and  ArgV).  For 
those  readers  unfamiliar  with  C, 
ArgC  is  a  count  of  the  number  of 
command  line  arguments  encoun¬ 
tered  by  the  operating  system,  and 
ArgV  is  a  pointer  to  those  arguments. 
My  module  CmdLin2  mimics  this  be¬ 
havior  for  the  Modula-2  environ¬ 
ment.  The  definition  module  (Listing 
Two,  page  76)  shows  ArgV  as  an  AD¬ 
DRESS ;  it  is  used  in  the  main  program 
as  a  POINTER  TO  ARRAY  OF  POINT¬ 
ER  TO  STRING  in  much  the  same 
way  as  C  would  use  it.  (Note:  This  is  a 
machine-dependent  module — CP/M- 
80  only!  It  assumes  that  the  com¬ 
mand  line  will  be  located  at  memory 
location  80H,  with  a  count  in  the  first 
byte.  Programmers  working  in  other 
environments  will  have  to  adapt  at 
least  the  absolute  addressing  used  in 
the  implementation.) 

Design  Phase 

With  a  few  tools  in  hand  and  more 
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confidence  than  any  believer  in  Mur¬ 
phy's  Law  has  a  right  to  have,  I  sat 
down  to  do  a  requirement  analysis.  I 
came  up  with  the  specifications 
!  shown  in  Table  1,  page  54. 

Jumping  ahead  just  a  bit:  You 
might  want  to  ask  how  well  the  final 
program  adhered  to  these  specifica¬ 
tions.  I  fell  short  in  a  couple  of  areas 
and  went  beyond  the  original  speci¬ 
fications  in  others.  I  never  did  imple¬ 
ment  the  ROBG  assembler  directive 
as  a  linker  is  required  for  it  to  be  of 
any  use  and  I  haven't  written  a  link¬ 
er  (yet!).  Also,  the  assembler  does  not 
support  binary  constants.  One  addi¬ 
tional  pseudo-op  (EVEN)  is  support¬ 
ed,  however,  and  limited  ASCII  string 
evaluation  was  added.  The  error 
messages  finally  implemented  are 
somewhat  more  extensive. 

Implementation  of  XGSOOO 

:  The  X68000  Cross  Assembler  is  writ- 
{  ten  in  standard  Modula-2,  as  defined 
|  by  Niklaus  Wirth  in  the  second  edi¬ 
tion  of  Programming  in  Modula-2, 
(Springer-Verlag,  1983).  The  only  pos¬ 
sible  machine  dependency  (aside 
from  the  CmdLin2  module  already 
mentioned)  is  because  of  the  assump¬ 
tion  that  INTEGERS,  CARDINALS,  and 
BITSETs  all  occupy  16  bits  of  memo¬ 
ry.  Most  microcomputer  implemen¬ 
tations  and  even  several  minicom¬ 
puter  implementations  conform  to 
this  standard.  Porting  considerations 
will  be  mainly  in  the  area  of  I/O  li¬ 
brary  routines.  The  Hochstrasser  li¬ 
brary  is  virtually  identical  to  the  Voli¬ 
tion  Systems  library  so  little  more 
than  recompiling  should  be  neces¬ 
sary  for  this  popular  compiler. 

In  the  August  1984  issue  of  Byte, 
Wirth  made  a  few  comments  about 
modules  that  are  appropriate  to  any 
discussion  of  a  major  Modula-2 
project: 

"With  the  module  we  have  added 
another  level  of  granularity  in  pro¬ 
gram  structuring.  The  difficulties  of 
finding  a  good  partitioning — I  care¬ 
fully  avoid  the  word  optimal’ — are 
culminated  at  this  level.  . . .  Lucky 
are  those  who  hit  a  good  solution  at 
the  outset,  for  any  change  affects  all 
participant”  modules. 

Amen  to  that!  My  initial  partition¬ 
ing  had  a  module  that  I  called  Parser 
doing  the  decomposition  of  source 


lines  into  parts  of  speech,  as  well  as  j 
syntax  analysis  and  code  generation. 
After  the  module  had  grown  to  more 
than  a  dozen  large  procedures  and 
more  than  a  thousand  lines  of  code,  I 
conceded  that  this  was  not  the  "opti¬ 
mal”  partitioning.  In  the  end,  I  split 
the  original  module  into  three  small¬ 
er  modules:  Parser,  SyntaxAnalyzer,  j 
and  CodeGenerator.  This  splitting 
made  for  some  rather  awkward  vari¬ 
able  and  type  importations.  With 
that  disclaimer,  we  can  go  on  to  look  j 
at  the  data  flow  diagrams  for  the  fin-  j 
ished  program. 

Assembly— Pass  1 

The  purpose  of  the  first  pass  through 
the  68000  source  code  is  mainly  to 
build  a  symbol  table.  As  each  instruc¬ 
tion  is  scanned,  an  address  counter  is 
advanced  based  on  the  length  of  the 
instruction  (68000  instructions  vary  in 
length  from  2  to  10  bytes).  When  an 
EQ.U  pseudo-op  is  encountered,  its 
value  must  be  entered  in  the  symbol 
table,  and  when  any  other  label  is  en¬ 
countered,  the  value  of  the  current 
address  counter  must  be  entered  into 
the  table.  Because  the  same  syntax 
analysis  routines  are  used  for  both 
passes,  some  errors  are  reported  dur¬ 
ing  this  pass. 

Figure  1,  page  55,  is  a  data  flow  dia¬ 
gram  for  pass  1.  The  68000  source 
code  is  read  one  line  at  a  time  and 
split  into  four  parts  by  the  routines  in 
Parser.  The  definition  module  for  | 
Parser  is  given  in  Listing  Three,  page 
76.  LineParts  is  the  only  procedure  j 
that  is  exported  by  Parser,  but  sever¬ 
al  routines  that  are  hidden  in  the  im¬ 
plementation  module  do  most  of  the 
work.  (The  implementation  modules 
will  be  presented  and  explained  in 
parts  2  and  3  of  this  series  of  articles.) 

Parser  passes  any  labels  on  to  the 
SymbolTable  module  for  entry  in  the 
symbol  table;  the  opcodes  (e.g.,  I 
MOVE )  go  to  the  OperationCodes  ! 
module  where  the  machine  code  is 
extracted  from  a  lookup  table;  and 
the  operands  (e.g.,  R0,(A2))  are  sent, 
via  the  BuildSymTable  procedure  in 
CodeGenerator,  to  the  SyntaxAna¬ 
lyzer  module  where  their  format  is 
checked  and  their  size  determined. 
The  definition  modules  for  Symbol- 
Table,  CodeGenerator,  and  Syntax- 
Analyzer  are  Listings  Four,  Five,  and 
Six  (pages  76  and  78). 

If  a  label  is  present,  BuildSymTable 


passes  a  value  (most  often  the  address 
count)  to  the  SymbolTable  module, 
where  it  is  stored  and  referenced  to 
its  label.  Although  the  SymbolTable 
module  has  four  procedures  for 
managing  the  symbol  table,  it  is 
mostly  the  FillSymTab  routine  that 
finds  work  during  pass  1.  The  defini¬ 
tion  module  for  ErrorX68  is  shown  as 
Listing  7,  page  78  nd  is  responsible 
for  outputting  error  messages  to  the  I 
console  and  then  returning  to  the 
main  flow  when  the  programmer 
acknowledges  the  error  by  pressing 
any  key  on  the  console  keyboard. 

Assembly— Pass  2 

The  major  purpose  of  pass  2  is,  of 
course,  generation  of  machine  code, 
which  is  written  to  an  S-record  file 
on  disk.  In  addition,  a  formatted  pro¬ 
gram  listing  is  created,  also  on  disk. 

Before  pass  2  actually  starts,  the 


Specifications 

Two-pass  assembler  (no  macros) 

Written  entirely  in  high-level  language 

Supports  pseudo-ops 
ORG  &  RORG 
EQU 
DC.B 
DC.W 
DC.L 
DS 
END 

Creates  formatted  listing  file 
Creates  S-record  file 
SO  header  record 
S2  data/code  records 
S8  trailer  record 

Outputs  error  messages  to  console 
Undefined  opcode/pseudo-op 
Label  defined  twice 
Undefined  label 

Operand  inconsistent  with  op-code 
This  addressing  mode  not  allowed 
Phase  error 

Numeric  constants/operations 
HEX 
Decimal 
Binary 

+/- 


Table  1 
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SortSymTab  procedure  in  the  Sym- 
bolTable  module  sorts  all  identifiers 
into  alphabetical  order.  This  allows 
their  values  to  be  found  more  quick¬ 
ly  during  the  code  generation  pass. 
Most  of  the  steps  taken  in  pass  1  are 
repeated  essentially  unchanged  dur¬ 
ing  pass  2.  The  data  flow  diagram  for 
this  pass  is  shown  as  Figure  2,  below. 
Parser  still  performs  the  same  task 
and  passes  labels,  opcodes,  and  oper¬ 
ands  onto  the  same  modules  as  be¬ 
fore.  During  pass  2,  however,  it  is  the 
GetObjectCode  procedure  in  Code- 
Generator  that  works  with  the  vari¬ 
ous  procedures  in  the  SyntaxAna- 
lyzer  module. 

The  two  "busiest”  routines  in  the 
whole  process  are  GetOperand  from 
SyntaxAnalyzer  and  a  routine  called 
MergeModes  hidden  within  the  im¬ 
plementation  module  of  CodeGener- 
ator.  GetOperand  determines  the 
mode  and  values  (if  any)  for  all  oper¬ 
ands;  GetValue,  GetSize,  and  several 
other  procedures  help  with  the 
smaller  jobs.  MergeModes  takes  all 
the  information  from  Operation- 
Codes,  SymbolTable,  and  SyntaxAna¬ 
lyzer  and  combines  it  to  produce 
hexadecimal  machine  code. 

The  Listing  and  Srecord  modules 
use  the  machine  code  from  CodeGen- 
erator  to  create  their  files.  Listing 
also  gets  the  complete  lines  of  source 
code  from  the  Parser  module  to 
merge  it  with  the  object  code  for  that 
line.  The  result  is  a  formatted  listing, 
with  addresses,  object  code,  source 
code,  and  page  numbers.  As  an  aid  to 
debugging,  the  ListSymTab  proce¬ 
dure  in  SymbolTable  provides  a  sort¬ 
ed  list  of  all  identifiers,  along  with 
their  values.  The  definition  modules 
for  Listing  and  Srecord  are  shown  as 
Listings  Eight  and  Nine,  shown  on 
page  78. 

The  Main  Program 

The  main  program  for  X68000  is 
shown  as  Listing  Ten,  page  78.  From 
the  above  description,  it  should  be 
obvious  that  there  is  not  too  much  for 
the  main  module  to  do.  Its  tasks  con¬ 
sist  of  inputting  and  formatting  the 
68000  source  code  file  name;  open¬ 
ing,  resetting,  and  closing  files;  and 
providing  the  two  REPEAT  loops  that 
control  pass  1  and  pass  2. 

The  most  interesting  aspect  of 
these  jobs  is  the  command  line  inter¬ 
face.  Because  I  hacked  at  C  before  I 


Mode 

Information 


Figure  1:  X68000 — Data  Flow  for  Pass  1 
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learned  Modula-2,  I  sometimes  miss 
some  of  the  facilities  provided  by 
that  language.  (My  article  "Bit  Ma¬ 
nipulation  in  Modula-2,''  DDJ,  No¬ 
vember  1985,  sprang  from  a  similar 
hang-up.)  As  mentioned  above,  the 
module  CmdLin2  provides  facilities 
similar  to  C's  via  the  ArgC  and  ArgV 
arguments.  The  declaration  of  ArgV 
lists  it  as  an  ADDRESS ;  in  Modula-2, 
that  makes  it  compatible  with  all 
pointer  types.  What  CmdLin2  does 
internally  is  to  create  an  array  of 
pointers,  with  one  pointing  to  each 
argument.  ArgV  points  to  that  array. 
So,  to  use  the  ReadCmdLin  proce¬ 
dure,  I  declare  ArgV  as: 

POINTER  TO  ARRAY  [1  .  .  n]  OF  POINTER 

TO  STRING; 

And  each  string  becomes: 

ArgV~[i]\ 

Although  this  program  has  only 
one  command  argument  (the  file 
name),  CmdLin2  was  written  as  a 
general-purpose  library  routine.  In¬ 
cidentally  the  2  in  the  name  is  be¬ 
cause  the  compiler  comes  with  a  li¬ 
brary  module  called  CmdLin,  which 
uses  a  more  conventional  (for  Mod¬ 
ula-2)  approach  to  the  problem — you 
bring  in  the  whole  command  line  as 
a  string  and  parse  it  into  arguments 
yourself.  It  is  interesting  that  the  C 
approach  results  in  a  smaller  module 
but  does  more  work  for  you! 

Availability 

The  following  is  available  directly 
from  the  author  for  $20  (U.S.): 

1.  A  25-page  X68000  User's  Manual 
that  includes  operating  instructions 
for  the  program  as  well  as  a  descrip¬ 
tion  and  example  of  a  method  to  use 
the  assembler  to  link  several 
modules. 

2.  An  8-inch  CP/M  SSSD  disk  or  a  514- 

inch  IPM  PC  disk  with  executable  pro¬ 
gram  as  well  as  complete  source 
code  and  several  68000  assembly-lan¬ 
guage  examples.  ddj 

(Listings  begin  on  page  76.) 

Reader  Ballot 

Vote  for  you* favorite  feature/article. 

Circle  Reader  Service  No.  5. 
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LISTING  ONE  (Text  begins  on  page  18.) 

Listing  1  —  redir.c 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 

87 

88 


redir(  cmdline  ) 
register  char  *  cmdline; 


/*  Handles  redirection.  The  command  line  will  be  null 

*  terminated  wherever  the  first  <  or  >  is  found. 

Returns  1  if  any  redirection  happened,  0  if  none. 


*/ 

register  int 

int 

int 

int 

int 

char 


inquote  =0; 

rval  =  0; 

input; 

append; 

erralso; 

*fname; 


while  (  *cmdline  ) 

{ 

/*  Skip  to  a  <  or  >.  Brackets  in  quoted  strings  or 

*  preceeded  by  a  \  are  ignored.  When  the  loop  terminates 

*  cmdline  will  be  pointing  to  end  of  string  or  the 

*  angle  bracket. 

*/ 


for(;  *andline  &&  (inquote  ||  ! ISREDIR (*cmdline) ) ;  cmdline++ 

{ 

if(  *cmdline  ==  ’W  &&  *  (andline+1)  ) 
cmdline++; 


else  if (  ISQUOTE (*cmdline)  ) 
inquote  =  -inquote; 


if (  !*cmdline  ) 
break; 


/*  If  we  get  here  then  we’re  processing  a  <  or  > 

*  Parse  the  corrmand,  and  strip  out  the  file  name. 
*/ 


rval  =  1; 
input  =  (*andline 
*cmdline++  =  ’  \0’; 


if (  append  =  ISREDIR  (*cmdline)  ) 
cmdline++; 

if (  erralso  =  (*cmdline  ==  ’&’)  ) 
cmdline++; 

SKIPWHITE  (cmdline); 
fname  =  cmdline; 


/*  <  or  «  */ 

/*  «  or  »  */ 

/*  >&  or  »&  */ 


/*  skip  to  file  */ 
/*  name.  */ 


while (  *cmdline  &&  ! isspace (*cmdline)  &&  ! ISREDIR (*cmdline) ) 
cmdline++; 

if(  *cmdline  ) 

*cmdline++  =  ■ \0 ’ ; 


/*  Now  actually  do  the  redirection 
*/ 

if  (  input  ) 

freopen(  fname,  ”r”,  stdin  ); 

else 

{ 

f reopen (  fname,  append  ?  "a”  : 
if (  erralso  ) 

dup2 (  1,  2  ) ; 

} 


stdout  ) ; 


return  rval  ; 


unredir  () 

{ 

f reopen (  "/dev/con",  "r", 
f reopen (  "/dev/con",  "w", 
dup2 (  1,  2); 

} 


stdin  ) ; 
stdout  ) ; 


End  Listing  One 
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LISTING  TWO 


Listing  2  —  switch. c 


1  # include  <stdio.h> 

2  finclude  <dos.h> 

3 

4  /*  SWITCHAR.C:  Read  or  set  the  switch  character  depending 

5  *  on  wheter  one  is  present  on  the  command 

6  *  line. 

7  * 

8  *  Author:  Anthony  LiCausi 

9  * 

10  *  Modified  somewhat  by  Allen  Holub. 


11  */ 

12 

13  int  switchar(  c  ) 

14  { 

15  /*  If  c  ==  0,  return  the  current  switch  character,  else 

16  *  change  the  switch  character  to  c  and  return  the  old 

17  *  switch  character.  The  routine  is  mildly  recursive. 

18  */ 

19 

20  union  REGS  regs; 

21  register  int  rval  =  0; 

22 

23  if (  c  ) 

24  rval  =  switchar (0) ; 

25 

26  regs.x.dx  =  c; 

27  regs. x. ax  =  c  ?  0x3701  :  0x3700  ; 

28 

29  intdos  (  &regs,  sregs  ); 

30 

31  return  rval  ?  rval  :  regs.h.dl  ; 

32  } 

33 

35 

36  main(  argc,  argv  ) 

37  char  **argv; 

38  { 

39  argv++; 

40 

41  if  (  argc  >  1  ) 

42  printf ("Changing  switch  character  from  <%c>  to  <%c>\n"/ 

43  switchar (**argv) ,  **argv) ; 

44  else 

45  printf ("Switch  character  is  <%c>\n",  switchar (0)  ); 

46 

47  exit  (0) ; 

48  } 

49 


End  Listing  Two 


LISTING  THREE 

Listing  3  —  touch. c 

1  finclude  <stdio.h> 

2  finclude  <fcntl.h> 

3 

4  /*  TOUCH. C  -  Touches  a  files  date  and  time  so  as  to  make 

5  *  the  file  current.  Usage  is: 

6  *  touch  file  [file  ...] 

7  * 

8  *  Author:  Michael  Yam 

9  *  Public  Domain  (P)  October  1985 

10  * 

11  *  Modified  so  that  a  file  is  created  if  it  doesn't  exist  -  AH 

12  */ 

13 

15 

16  fifdef  LATTICE 

17 

18  f define  EXISTS  0_RAW|0_RDWR 

19  f define  CREATE  0_CREAT | EXISTS 

20 

21  felse 

22 

23  finclude  <types.h> 

24  finclude  <stat.h> 

25  f define  EXISTS  0_BINARY | 0_RDWR 

26  f define  CREATE  0_CREAT | EXISTS,  S_IREAD | S_IWRITE 

27 

28  fendif 

29 

30  /* - */ 

31 

32  main(  argc,  argv  ) 

33  char  **argv; 

34  { 
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LISTING  THREE  (Listing  continued,  text  begins  on  page  18.) 

35 

int  buffer  =  1  \0 ' ; 

36 

int  err  lvl  =  0; 

37 

38 

int  file; 

39 

for(  ++argv;  — argc  >  0;  ++argv  ) 

40 

i 

41 

if (  (file  =  open (*argv,  EXISTS))  !=  -1) 

42 

{ 

43 

44 

/*  File  exists  */ 

45 

read  (  file,  &buffer,  1  ) ;  /*  read  a  char  */ 

46 

lseek (  file,  0L,  0  ) ;  /*  go  back  to  start  */ 

47 

write (  file,  sbuffer,  1  );  /*  write  the  same  char  V 

48 

close (  file  ); 

49 

i 

50 

else  if  (  (file  =  open(*argv,  CREATE))  !=  -1) 

51 

< 

52 

/*  Created  new  file.  Don't  modify  it  so  that 

53 

*  it  will  remain  zero  length. 

54 

55 

*/ 

56 

close  (  file  ) ; 

57 

i 

58 

else 

59 

f 

60 

61 

/*  File  doesn't  exist  and  can't  be  created  */ 

62 

err  lvl  =  1; 

63 

fprTntf (stderr, "Can't  touch  %s\n",  *argv  ); 

64 

65 

66 

i 

67 

exit (  err  lvl  ) ; 

68  } 

End  Listings 
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LISTING  ONE  (Text  begins  on  page  24.) 

elijah-brown  father-of  robert-brown-sr 

robert-brown-sr  father-of  robert-brown-jr 

john-raccollister  father-of  lavenia-mccollister 

isam-mccollister  father-of  john-mccol lister 

mr-holt  father-of  bettie-holt 

elias-presley  father-of  margret-presley 

robert-brown- jr  father-of  robert-brown-iii 

paul-h-sewall  father-of  virginia-sewall 

paul-h-sewall  father-of  paul-sewall- jr 

paul-sewall- jr  father-of  peter-sewall 

paul-sewall-jr  father-of  dee-dee-sewall 

paul-sewall-jr  father-of  mark-sewall 

paul-sewall-jr  father-of  paul-sewall-iii 

robert-brown- jr  father-of  kenneth-brown 

robert-brown-sr  father-of  amos-trice-brown 

robert-brown-sr  father-of  james-elro-brown 

clarence-bailey-compton  father-of  elanor-compon 

george-washington-corapton  father-of  clarence-bailey-compton 

samuel-compton  father-of  george-washington-compton 

henry-sewall  father-of  paul-h-sewall 

dr- james-d-nelson  father-of  rachel-nelson 

robert-sewall  father-of  henry-sewall 

paul-hebert  father-of  evelina-hebert 

harry-breeden  father-of  X  if 

dorothy-wallace  mother-of  X 
berke-breeden  father-of  harry-breeden 
john-wallace  father-of  dorothy-wallace 
robert-brown-iii  father-of  krystl-raquelle-brown 
paul-sewall-jr  father-of  robert-sewall-ii 
danny-crider  father-of  amy-crider 
bill-skirvin  father-of  marty-skirvin 
bill-skirvin  father-of  rodney-skirvin 
tommy-breeden  father-of  thomas-andrew-breeden 
tommy-breeden  father-of  suzanne-breeden 
john-alsop  father-of  joy-alsop 
lester-stevens  father-of  geneva-stevens 
strawder-breeden  father-of  daren-breeden 
daren-breeden  father-of  shaun-breeden 
strawder-breeden  father-of  deidra-breeden 
robert-bishop  father-of  krystal-bishop 
robert-bishop  father-of  tiffany-bishop 
robert-brown-sr  father-of  opal -brown 
strawder-breeden  father-of  deva-breeden 
strawder-breeden  father-of  stephanie-breeden 
johnny-wilson  father-of  jonathan-wilson 
lester-stevens  father-of  geneva-stevens 
bettie-holt  mother-of  lavenia-mccollister 
miss-hornsby  mother-of  robert-brown-sr 
elizabeth-arthur  mother-of  john-mccol lister 
margret-e-presley  mother-of  betty-holt 
virginia-sewall  mother-of  robert-brown-iii 
elanor-compton  mother-of  virginia-sewall 
lilian-givens  mother-of  X  if 

paul-sewall-jr  father-of  X 
virginia-sewall  mother-of  kenneth-brown 
lavenia-mccollister  mother-of  amos-trice-brown 
lavenia-mccollister  mother-of  james-elro-brown 
sarah-virginia-sanford  mother-of  elanor-compton 
mary-eliza-sanford  mother-of  clarence-bailey-compton 
rachel-nelson  mother-of  paul-h-sewall 
jane-kirk  mother-of  rachel-nelson 
evelina-hebert  mother-of  henry-sewall 
eugina-hamilton  mother-of  evelina-hebert 
dorothy-wallace  mother-of  darlene-breeden 
dorothy-wallace  mother-of  willena-breeden 
dorothy-wallace  mother-of  karen-breeden 
dorothy-wallace  mother-of  bonnie-breeden 
dorothy-wallace  mother-of  tommy-breeden 
dorothy-wallace  mother-of  dorothy-breeden 
dorothy-wallace  mother-of  brenda-breeden 
dorothy-wallace  mother-of  betty-breeden 
dorothy-wallace  mother-of  strawder-breeden 
flo-marsh  mother-of  harry-breeden 
christine-xxx  mother-of  dorothy-wallace 
darlene-breeden  mother-of  krystl-raquelle-brown 
dorothy-breeden  mother-of  amy-crider 
brenda-breeden  mother-of  X  if 

bill-skirvin  father-of  X 
joy-alsop  mother-of  suzanne-breeden 
joy-alsop  mother-of  thomas-andrew-breeden 
pauline-davis  mother-of  joy-alsop 
myrtle- jackson  mother-of  geneva-stevens 
tammy -xxx  mother-of  shaun-breeden 
deidra-breeden  mother-of  krystal-bishop 
deidra-breeden  mother-of  tiffany-bishop 
lavenia-mccollister  mother-of  opal-brown 
lavenia-mccollister  mother-of  robert-brown-jr 
elanor-compton  mother-of  paul-sewall-jr 
karen-breeden  mother-of  jonathan-wilson 
geneva-stevens  mother-of  X  if 

strawder-breeden  father-of  X 
myrtle- jackson  mother-of  geneva-stevens 
male  (X)  if 

X  father-of  Y 
male  ( john-viscar) 
male  (shaun-breeden) 
female  (X)  if 

X  mother-of  Y 
female  (willena-breeden) 
female  (bonnie-breeden) 
female  (karen-breeden) 
female  (betty-breeden) 
female  ( judy-tracey) 

X  wife  Y  if 


X  mother-of  Z  and 

Y  father-of  Z 
X  husband  Y  if 

Y  wife  X 
X  parent-of  Y  if 

X  father-of  Y 
X  parent-of  Y  if 

X  mother-of  Y 
X  wife-of  Y  if 

X  wife  Y 

judy-tracy  wife-of  tommy-breeden 
X  husband-of  Y  if 

X  husband  Y 

john-viscar  husband-of  pauline-davis 
X  child-of  Y  if 

Y  parent-of  X 
X  descendant-of  Y  if 

X  child-of  Y 
X  descendant-of  Y  if 

Z  child-of  Y  and 
X  descendant-of  Z 
X  ancestor-of  Y  if 

X  parent-of  Y 
X  ancestor-of  Y  if 

Z  parent-of  Y  and 
X  ancestor-of  Z 

lavenia-mccollister  moher-of  robert-brown-jr 
X  sibling-of  Y  if 

Z  mother-of  X  and 
Z  mother-of  Y  and 
x  father-of  X  and 
x  father-of  Y  and 
Not  (X  EQ  Y) 

X  half-sibling-of  Y  if 

Z  mother-of  X  and 
Z  mother-of  Y  and 
Not  (X  sibling-of  Y)  and 
Not  (X  EQ  Y) 

X  half-sibling-of  Y  if 

Z  father-of  X  and 
Z  father-of  Y  and 
Not  (X  sibling-of  Y)  and 
Not  (X  EQ  Y) 

X  aunt-or-uncle-of  Y  if 

Z  parent-of  Y  and 
X  sibling-of  Z 
X  cousin-of  Y  if 

Z  aunt-or-uncle-of  X  and 

Y  child-of  Z 

End  Listing  One 


LISTING  TWO 


which  (X  X  father-of  robert-brown-iii) 

Answer  is  robert-brown-jr 
No  (more)  answers 

which  (X  robert-brown-iii  father-of  X) 

Answer  is  krystl-raquelle-brown 
No  (more)  answers 

which  (X  X  parent-of  krystl-raquelle-brown) 

Answer  is  robert-brown-iii 
Answer  is  darlene-breeden 
No  (more)  answers 

which  (X  X  descendant-of  robert-brown-sr) 

Answer  is  robert-brown-jr 
Answer  is  amos-trice-brown 
Answer  is  james-elro-brown 
Answer  is  opal-brown 
Answer  is  robert-brown-iii 
Answer  is  kenneth-brown 
Answer  is  krystl-raquelle-brown 
No  (more)  answers 

which  (X  X  aunt-or-uncle-of  robert-brown-iii) 

Answer  is  amos-trice-brown 

Answer  is  james-elro-brown 

Answer  is  opal-brown 

Answer  is  paul-sewall-jr 

No  (more)  answers 

which  (X  X  aunt-or-uncle-of  krystl-raquelle-brown) 

Answer  is  kenneth-brown 

Answer  is  willena-breeden 

Answer  is  karen-breeden 

Answer  is  bonnie-breeden 

Answer  is  tommy-breeden 

Answer  is  dorothy-breeden 

Answer  is  brenda-breeden 

Answer  is  betty-breeden 

Answer  is  strawder-breeden 

No  (more)  answers 

which  (X  robert-brown-iii  cousin-of  X) 

Answer  is  peter-sewall 
Answer  is  dee-dee-sewall 
Answer  is  mark-sewall 
Answer  is  paul-sewall-iii 


(continued  on  page  66) 
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(DEFUN  COMMON  (LAMBDA  (L  M) 

(*  form  the  3et  intersection  of  2  lists  with  possible 
duplicate  entries  *) 

((NULL  L)  NIL) 

((MEMBER  (CAR  L)  M) 

(CONS  (CAR  L)  (COMMON  (CDR  L)  M) )  ) 

(COMMON  (CDR  L)  M)  ) ) 

(DEFUN  DEF  (LAMBDA  (V  E) 

(*  determine  whether  the  variable  V  is  defined  in  the 
environment  E  *) 

((NULL  E)  NIL) 

( (EQUAL  V  (CAAR  E) )  T) 

(DEF  V  (CDR  E))  )) 

(DEFUN  IMM  (LAMBDA  (V  E) 

(*  return  the  immediate  successor  of  the  variable  V  in  the 
environment  E  *) 

((NULL  E)  NIL) 

( (EQUAL  V  (CAAR  E)  ) 

(CDAR  E)  ) 

(IMM  V  (CDR  E) )  )  ) 

(DEFUN  ULT  (LAMBDA  (V  E) 

(*  return  the  ultimate  successor  of  the  variable  V  in  the 
environment  E  *) 

(  (DEF  V  E) 

(ULT  (IMM  V  E)  E)  ) 

V  )) 

(DEFUN  PAIRP  (LAMBDA  (P) 

(*  determine  if  P  is  a  pair  (not  an  atom)  *) 

( (ATOM  P)  NIL) 

T  )) 

(DEFUN  VARIABLEP  (LAMBDA  (V) 

(*  determine  if  V  is  a  variable  *) 

(EQ  (CAR  (UNPACK  V) )  **)  )) 

(DEFUN  RECREAL  (LAMBDA  (F  E) 

(*  return  the  recursive  realization  of  a  formula  F  in  the 

environment  E  which  amounts  to  instantiating  all  variables 
from  the  environment  *) 

(  (PAIRP  F) 

(CONS  (RECREAL  (CAR  F)  E)  (RECREAL  (CDR  F)  E) )  ) 

(  (DEF  F  E) 


(RECREAL  (ULT  F  E)  E)  ) 

F  )) 

(DEFUN  OCCURS  (LAMBDA  (V  X  E) 

(*  see  if  the  variable  V  occurs  in  the  term  X  under  the 
environment  E  *) 

( (VARIABLEP  X) 

( (DEF  X  E) 

(OCCURS  V  (IMM  X  E)  E)  ) 

(  (EQ  V  X)  T)  ) 

( (ATOM  X)  NIL) 

( (OCCURS  V  (CAR  X)  E)  T) 

(OCCURS  V  (CDR  X)  E)  )) 

(PEFUN  UNIFY  (LAMBDA  (A  B  E) 

(*  unify  2  expressions  (A  and  B)  in  the  environment  E  by 
extending  E  to  the  most  general  unifier  of  A  and  B  and 
returning  that  environment  *) 

((EQ  E  'IMPOSSIBLE) 

'IMPOSSIBLE  ) 

(EQUATE  (ULT  A  E)  (ULT  BE)  E)  ) ) 

(DEFUN  EQUATE  (LAMBDA  (ABE) 

(*  auxilliary  routine  to  UNIFY  so  that  the  flow  of  control 
ping-pongs  recursivly  between  UNIFY  and  EQUATE  to 
construct  the  most  general  unifier  of  A  and  B  *) 

( (EQUAL  A  B)  E) 

( (VARIABLEP  A) 

((OCCURS  ABE) 

'IMPOSSIBLE  ) 

(CONS  (CONS  A  B)  E)  ) 

( (VARIABLEP  B) 

((OCCURS  B  A  E) 

'IMPOSSIBLE  ) 

(CONS  (CONS  B  A)  E)  ) 

((ATOM  A) 

'IMPOSSIBLE  ) 

( (ATOM  B) 

'IMPOSSIBLE  ) 

(UNIFY  (CDR  A)  (CDR  B)  (UNIFY  (CAR  A)  (CAR  B)  E))  )) 

(DEFUN  VARS  (LAMBDA  (X) 

(*  return  a  list  of  all  the  variables  found  in  the  expression 
X  *) 

( (NULL  X)  NIL) 

((VARIABLEP  X)  X) 


(continued  on  next  page) 


Dr.  Dobb's  Journal,  April  1986 


67 

265 


_ INFERENCE  ENGINE 

LISTING  FOUR  (Listing  continued;  text  begins  on  page  24.) 


( (ATOM  X)  NIL) 

(CONCAT  (VARS  (CAR  X))  (VARS  (CDR  X)))  )) 

(DEFUN  VARIANT  (LAMBDA  (Q  E  D) 

(*  returns  a  variant  of  D  such  that  all  variables  are  distinct 
from  those  of  Q  in  the  environment  E  *) 

(RECREAL  D  (MAKENV  (VARS  Q)  (VARS  E)  (VARS  D) ) )  ) ) 

(DEFUN  MAKENV  (LAMBDA  (Q  E  D) 

(*  make  an  environment  such  that  the  instantiation  of  D  in 

this  environment  will  have  no  variables  in  common  with  the 
instantiation  of  Q  in  E  *) 

(MAKENV1  (MEET  D  (JOIN  Q  E) )  (JOIN  (JOIN  Q  E)  D)  )  )) 

(DEFUN  MAKENV1  (LAMBDA  (P  Q  V) 

(*  does  the  dirty  work  for  MAKENV  and  VARIANT  by  generating  an 
environment  that  sticks  asterisks  onto  the  front  of  all 
variable  names  in  Q  that  also  occur  in  P  (V  is  a  local 
temporary  variable)  *) 

( (NULL  P)  NIL) 

((ATOM  P) 

(SETQ  V  P) 

(LOOP 

( (NOT  (MEMBER  V  Q) ) ) 

(SETQ  V  (PACK  (CONS  ' *  (UNPACK  V))))  ) 

(CONS  P  V)  ) 

(CONS  (MAKENV1  (CAR  P)  Q)  (MAKENV1  (CDR  P)  Q) )  )) 

(DEFUN  GETLIT  (LAMBDA  (CL  N) 

(*  get  the  Nth  litteral  in  the  clause  CL  and  return  it  both  as 
the  functions  value  and  in  the  free  variable  LITG  along 
with  its  sign  in  the  free  variable  SIGNG  *) 

(SETQ  LITG  (CAR  (NTH  CL  N) ) ) 

(SETQ  SIGNG  (NOT  (EQ  (CAR  LITG)  '-))) 

((NOT  (NULL  SIGNG))  LITG) 

(CADR  LITG)  ) ) 

(DEFUN  FRONT  (LAMBDA  (C  N) 

(*  return  all  elements  in  the  clause  C  in  front  of  element  N 
*) 

(  (NULL  C)  NIL) 

((ZEROP  N)  NIL) 

( (EQ  N  1)  NIL) 

(CONS  (CAR  C)  (FRONT  (CDR  C)  (SUB1  N) ) )  )) 

(DEFUN  BACK  (LAMBDA  (C  N) 

(*  return  all  elements  in  clause  C  in  back  of  element  N  *) 

(NTH  C  (ADD1  N) )  )  ) 

(DEFUN  FACTOR  (LAMBDA  (C  PI  N1  SI  P2  N2  S2  ENV) 

(*  returns  a  factored  version  of  the  clause  C  *) 

(SETQ  ENV  'IMPOSSIBLE) 

(SETQ  N1  0) 

(LOOP 

(SETQ  N1  (ADD1  Nl) ) 

( (GREATERP  Nl  (LENGTH  C) ) 

•IMPOSSIBLE  ) 

(GETLIT  C  Nl) 

(SETQ  PI  LITG) 

(SETQ  SI  SIGNG) 

(SETQ  N2  Nl) 

(  ((LOOP 

(SETQ  N2  (ADD1  N2 ) ) 

((GREATERP  N2  (LENGTH  C) ) ) 

(GETLIT  C  N2 ) 

(SETQ  P2  LITG) 

(SETQ  S2  SIGNG) 

(  ((EQ  SI  S2 ) 

(SETQ  ENV  (UNIFY  PI  P2))  )  ) 

((NOT  (EQ  ENV  'IMPOSSIBLE)) 

(SETQ  C  (RECREAL  C  ENV)) 

(SETQ  C  (APPEND  (FRONT  C  Nl)  (BACK  C  Nl)))  )  ))  ) 
((NOT  (EQ  ENV  'IMPOSSIBLE)))  ) 

((NOT  (EQ  ENV  'IMPOSSIBLE))  C) 

' IMPOSSIBLE  ) ) 

(DEFUN  BINRES  (LAMBDA  (CL1  Nl  CL2  N2  ENV  LIT1  SGN1  LIT2  SGN2  LI 
L2  LITG  SIGNG) 

(*  compute  the  binary  resolvent  of  clause  CL1  litteral  number 
Nl  with  clause  CL2  litteral  number  N2  and  return  the 
instantiated  resolvent  *) 

(SETQ  CL2  (VARIANT  CL1  ENV  CL2 ) ) 

(SETQ  LIT1  (GETLIT  CL1  Nl)) 

(SETQ  LI  LITG) 

(SETQ  SGN1  SIGNG) 

(SETQ  LIT2  (GETLIT  CL2  N2)) 

(SETQ  L2  LITG) 

(SETQ  SGN2  SIGNG) 

( (EQ  SGN1  SGN2)  NIL) 

(SETQ  ENV  (UNIFY  LIT1  LIT2  ENV)) 

((EQ  ENV  'IMPOSSIBLE) 

'IMPOSSIBLE  ) 

(RECREAL  (APPEND  (FRONT  CL1  Nl)  (BACK  CL1  Nl )  (FRONT  CL2  N2) 
(BACK  CL2  N2) )  ENV)  ) ) 

(DEFUN  PARAMOD  (LAMBDA  (FROM  INTO  PF  F  PI  I  SEL  SUB  ENV  SWAP  PM) 
(*  return  the  paramodulant  of  the  FROM  clause  into  the  INTO 
clause  *) 

(SETQ  INTO  (VARIANT  FROM  NIL  INTO) ) 

(SETQ  PM  'IMPOSSIBLE) 

(SETQ  PF  0) 

(LOOP 

(SETQ  PF  (ADD1  PF) ) 

(SETQ  F  (CAR  (NTH  FROM  PF) ) ) 

( (NULL  F) ) 

((EQ  (CAR  F)  '-) 


(SETQ  SEL  (CADR  F) ) 

(SETQ  SUB  (CADDR  F) ) 

(SETQ  PI  0) 

(LOOP 

(SETQ  PI  (ADD1  PI)) 

(SETQ  I  (CAR  (NTH  INTO  PI))) 

((NULL  I)) 

(SETQ  ENV  (UNIFY  SEL  I)) 

(  ( (EQ  ENV  'IMPOSSIBLE) 

(SETQ  ENV  (UNIFY  SUB  I)) 

(SETQ  SUB  SEL)  )  ) 

((NOT  (EQ  ENV  'IMPOSSIBLE)) 

(SETQ  FROM  (RECREAL  FROM  ENV) ) 

(SETQ  INTO  (RECREAL  INTO  ENV) ) 

(  ( (NOT  (NULL  SWAP) ) 

(SETQ  SUB  SEL)  )  ) 

(SETQ  INTO  (APPEND  (FRONT  INTO  PI)  (LIST  SUB)  (BACK 
INTO  PI) ) ) 

(SETQ  FROM  (APPEND  (FRONT  FROM  PF)  (BACK  FROM  PF))) 

(SETQ  PM  (APPEND  FROM  INTO) )  )  )  ) 

((NOT  (EQ  PM  'IMPOSSIBLE)))  ) 

PM  )) 

End  Listing  Pour 

LISTING  FIVE 


(SETQ  Cl  ' ((F  *X))) 

<(F  *X)) 

(SETQ  C2  ' ( (G  *X) ) ) 

((G  *X)) 

(SETQ  E  (UNIFY  Cl  C2)) 

IMPOSSIBLE 
(RECREAL  Cl  E) 

((F  *X)) 

(RECREAL  C2  E) 

((G  *X)) 

(SETQ  C2  '((FA))) 

((FA)) 

(SETQ  E  (UNIFY  Cl  C2 ) ) 

((*X  .  A)) 

(RECREAL  Cl  E) 

((FA)) 

(RECREAL  C2  E) 

((FA)) 

(SETQ  C2  ' ((F  (G  *Y) ) ) ) 

((F  (G  *Y) ) ) 

(SETQ  E  (UNIFY  Cl  C2)) 

((*X  G  *Y) ) 

(RECREAL  Cl  E) 

((F  (G  *Y) ) ) 

(RECREAL  C2  E) 

((F  (G  *Y) ) ) 

(SETQ  C2  ' ( (F  (F  *X) ) ) ) 

((F  (F  *X))) 

(SETQ  E  (UNIFY  Cl  C2)) 

IMPOSSIBLE 
(RECREAL  Cl  E) 

((F  *X)) 

(RECREAL  C2  E) 

((F  (F  *X))) 

(SETQ  Cl  '  (  (F  *X  A)  (G  B  *Y)  )  ) 

((F  *X  A)  (G  B  *Y)  ) 

(SETQ  C2  ' ( (F  B  *Y)  (G  *X  *Z) ) ) 

(  (F  B  *Y)  (G  *X  *Z)  ) 

(SETQ  E  (UNIFY  Cl  C2)) 

((*Z  .  A)  (*Y  .  A)  ( *X  .  B)) 

(RECREAL  Cl  E) 

(  (F  B  A)  (G  B  A)) 

(RECREAL  C2  E) 

( (F  B  A)  (G  B  A)) 

End  Listing  Five 


LISTING  SIX 


(SETQ  CL1  '((F  *X)  (-  (G  *Y  A))  (F  B) ) ) 

((F  *X)  (~  (G  * Y  A))  (F  B)) 

(FACTOR  CL1) 

(  (~  (G  *Y  A)  )  (F  B)) 

(SETQ  CL2  '((G  B  *X)  (F  *Y) ) ) 

((G  B  *X)  (F  *Y)  ) 

(BINRES  CL1  2  CL2  1) 

( (F  *X)  (F  B)  (F  *  *Y)  ) 

(SETQ  FROM  ' ( (F  *X)  (-  (G  *Y  A)  (F  *Y) )  (F  B) ) ) 
((F  *X)  (-  (G  *Y  A)  (F  *Y) )  (F  B) ) 

(SETQ  INTO  CL2) 

(<G  B  *X)  (F  *Y)  ) 

(PARAMOD  FROM  INTO) 

(  (F  *X)  (F  B)  (F  *Y)  (F  * *Y)  ) 


End  Listing  Six 
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LISTING  SEVEN 


(DEFUN  VARIABLEP  (LAMBDA  (V) 

(*  determine  if  V  is  a  variable:  if  it  starts  with  lower-case 
it  is  *) 

((ATOM  V) 

(GREATERP  (ASCII  (CAR  (UNPACK  V) ) )  (ASCII  ') )  ) 

NIL  )) 

(DEFUN  LPAR  (LAMBDA  (R) 

(*  return  left  parent  *) 

(CAR  R)  )) 

(DEFUN  LLIT#  (LAMBDA  (R) 

(*  return  left  litteral  number  *) 

(CADR  R)  )) 

(DEFUN  RPAR  (LAMBDA  (R) 

(*  return  right  parent  *) 

(CADDR  R)  ) ) 

(DEFUN  RLIT*  (LAMBDA  (R) 

(*  return  right  litteral  number  *) 

(CAR  (CDDDR  R) )  )) 

(DEFUN  NLITS  (LAMBDA  (R) 

(*  return  number  of  litterals  *) 

(CADR  (CDDDR  R) )  )  ) 

(DEFUN  MAXNDX  (LAMBDA  (R) 

(*  return  maximum  index  *) 

(CADDR  (CDDDR  R) )  )) 

(DEFUN  BINDINGS  (LAMBDA  (R) 

(*  return  the  bindings  *) 

(CAR  (CDDDR  (CDDDR  R) ) )  )) 

(DEFUN  SETLPAR  (LAMBDA  (R  V) 

(*  set  left  parent  *) 

(RPLACA  R  V)  )) 

(DEFUN  SETLLIT#  (LAMBDA  (R  V) 

(*  set  left  litteral  number  *) 

(RPLACA  (CDR  R)  V)  ) ) 

(DEFUN  SETRPAR  (LAMBDA  (R  V) 

(*  set  right  parent  *) 

(RPLACA  (CDDR  R)  V)  )) 

(DEFUN  SETRLIT*  (LAMBDA  (R  V) 

(*  set  right  litteral  number  *) 

(RPLACA  (CDDDR  R)  V)  )) 

a (DEFUN  SETNUMLITS  (LAMBDA  (R  V) 

(*  set  number  of  litterals  *) 

(RPLACA  (CDR  (CDDDR  R) )  V)  ) ) 

(DEFUN  SETMAXNDX  (LAMBDA  (R  V) 

(*  set  maximum  index  *) 

(RPLACA  (CDDR  (CDDDR  R) )  V)  )) 

(DEFUN  SETBINDINGS  (LAMBDA  (R  V) 

(*  set  bindings  *) 

(RPLACA  (CDDDR  (CDDDR  R) )  V)  )) 

(DEFUN  INRECP  (LAMBDA  (R) 

(*  is  R  an  input  record?  *) 

(NULL  (RPAR  R))  )) 

(DEFUN  LEQP  (LAMBDA  (X  Y) 

(*  is  X  less  than  or  equal  to  Y  ?  *) 

(NOT  (GREATERP  X  Y) )  ) ) 

(DEFUN  NMEMS  (LAMBDA  (L) 

(*  return  the  number  of  members  in  the  list  L  *) 

( (NULL  L)  0) 

(ADD1  (NMEMS  (CDR  L) ) )  )) 

(DEFUN  EXTRACT  (LAMBDA  (K  L  TMP) 

(*  return  the  Kth  member  of  L  *) 

(*  TMP  is  a  local  variable  *) 

(LOOP 

((ZEROP  K)  TMP) 

(SETQ  K  (SUB1  K) ) 

(SETQ  TMP  (POP  L) )  )  )) 

(DEFUN  RESOLVE  (LAMBDA  (CL1  I  CL2  J  LLIT  RLIT  LNDX  RNDX  BNDEV 
LSIGN  RSIGN) 

(*  resolve  clause  CL1  litteral  I  with  clause  CL2  litteral  J 
returning  a  new  clause  record  representing  the  resolvent: 
UNIFY  will  extend  the  binding  environment:  returns  NIL  if 
impossible  *) 

(GETLIT  CL1  I) 

(SETQ  LLIT  LITG) 

(SETQ  LNDX  INDEXG) 

(SETQ  LSIGN  SIGNG) 

(GETLIT  CL2  J) 

(SETQ  RLIT  LITG) 

(SETQ  RNDX  (PLUS  INDEXG  (MAXNDX  CL1 ) ) ) 

(SETQ  RSIGN  SIGNG) 

(*  create  the  new  clause  record  *) 

(SETQ  BNDEV  (LIST  CLl  I  CL2  J  (DIFFERENCE  (PLUS  (NLITS  CL1) 
(NLITS  CL2) )  2)  (PLUS  (MAXNDX  CLl)  (MAXNDX  CL2) )  NIL)) 

(*  test  for  opposite  signs  *) 

( (EQ  LSIGN  RSIGN)  NIL) 

(*  extend  the  environment  by  the  unification  algorithm  *) 

( (UNIFY  LLIT  LNDX  RLIT  RNDX)  BNDEV) 

NIL  )) 

(DEFUN  GETLIT  (LAMBDA  (CL  K) 
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LISTING  SEVEN  (Listing  continued,  text  begins  on  page  24.) 


(*  get  the  Kth  litteral  in  clause  CL:  return  the  litteral 
gotten  in  LITG:  and  the  associated  index  in  INDEXG  *) 

(*  if  CL  is  an  input  clause  then  extract  the  Kth  litteral  and 
set  the  index  to  1  *) 

(  (INRECP  CL) 

(SETQ  LITG  (EXTRACT  K  (LPAR  CL))) 

(SETQ  SIGNG  (EQ  K  1)) 

(SETQ  INDEXG  1)  ) 

(*  if  it  is  in  the  left  parent  of  the  clause  then  get  the 
litteral  from  the  left  parent  *) 

(*  this  is  true  if  K  is  less  than  the  litteral  last  resolved 
upon  in  the  left  parent  of  the  current  clause  *) 

(  ( LESSP  K  (LLIT#  CL)) 

(GETLIT  (LPAR  CL)  K)  ) 

(*  this  is  also  true  if  K  is  less  than  the  number  of  litterals 
in  the  left  parent  but  in  this  case  we  must  adjust  K  by  1 
*) 

((LESSP  K  (NUMLITS  (LPAR  CL))) 

(GETLIT  (LPAR  CL)  (ADD1  K) )  ) 

(*  if  the  selected  litteral  is  in  the  right  parent  but  left  of 
the  litteral  last  resolved  upon  then  get  the  litteral  from 
the  right  parent  with  the  appropriate  adjustment  to  K  *) 
((LESSP  K  (PLUS  (SUB1  (NUMLITS  (LPAR  CL)))  (RLIT#  CL))) 

(GETLIT  (RPAR  CL)  (ADD1  (DIFFERENCE  K  (NUMLITS  (LPAR  CL))))) 

(*  in  this  case  adjust  the  index  got  *) 

(SETQ  INDEXG  (PLUS  INDEXG  (MAXNDX  (LPAR  CL))))  ) 

(*  otherwise  the  selected  litteral  is  in  the  right  parent  to 
the  right  of  last  litteral  resolved  upon  so  adjust  K 
accordingly  and  get  the  litteral  *) 

(GETLIT  (RPAR  CL)  (PLUS  (DIFFERENCE  K  (NUMLITS  (LPAR  CL)))  2)) 

(*  and  adjust  the  index  gotten  *) 

(SETQ  INDEXG  (PLUS  INDEXG  (MAXNDX  (LPAR  CL))))  )) 

(DEFUN  UNIFY  (LAMBDA  (TERM1  INDEX1  TERM2  INDEX2) 

(*  attempt  to  unify  TERM1  under  INDEX1  with  TERM2  under  INDEX2 
and  extend  the  binding  environment  represented  in  the 
global  variable  BNDEV :  return  T  if  successful  or  NIL  if  the 
unification  is  impossible  *) 

(*  if  both  terms  and  indices  are  equal  then  return  T:  no 
extension  to  BNDEV  is  needed  *) 

((EQUAL  TERM1  TERM2) 

(EQ  INDEX1  INDEX2) 

T  ) 

(*  if  TERM1  is  a  variable  *) 

( (VARIABLEP  TERM1) 

(*  then  if  it  is  bound  in  the  current  environment  *) 

((ISBOUND  TERM1  INDEX1  BNDEV) 

(*  then  substitute  that  binding  and  attempt  to  unify  again 
*) 

(UNIFY  TERMB  INDEXB  TERM2  INDEX2 )  ) 

(*  else  if  the  variable  of  TERM1  occurs  in  TERM2  then  we 

have  a  recursive  """black"  "hole"""  situation  so  return 
NIL  *) 

((OCCUR  TERM1  INDEX1  TERM2  INDEX2)  NIL) 

(*  else  force  a  unification  by  adding  the  necessary  binding 
and  return  T  for  success  *) 

(BIND  TERMl  INDEX1  TERM2  INDEX2  BNDEV) 

T  ) 

(*  if  TERM2  is  a  variable  then  swap  the  2  terms  and  UNIFY  the 
other  way  *) 

( (VARIABLEP  TERM2) 

(UNIFY  TERM2  INDEX2  TERMl  INDEX1)  ) 

(*  otherwise  if  the  heads  of  the  terms  unify  then  return  the 
result  of  unifying  the  tails  of  the  terms:  the  environment 
is  extended  as  needed  *) 

((UNIFY  (CAR  TERMl)  INDEX1  (CAR  TERM2 )  INDEX2) 

(UNIFY  (CDR  TERMl)  INDEX1  (CDR  TERM2)  INDEX2 )  )  )) 

(DEFUN  ISBOUND  (LAMBDA  (VAR  INDEX  BNDEV) 

(*  determine  if  the  variable  VAR  under  the  index  INDEX  is 
bound  in  the  binding  environment  BNDEV:  if  it  is  then 
return  T  and  set  the  free  variables  TERMB  and  INDEXB  to 
the  term  and  index  respectively  to  which  it  is  bound:  *) 

(*  otherwise  return  NIL  and  do  not  alter  the  values  of  TERMB  and 
INDEXB  *) 

(*  if  BNDEV  is  an  input  record  then  it  cannot  be  bound  so 
return  NIL  *) 

(  (INRECP  BNDEV)  NIL) 

(*  if  VAR  under  INDEX  is  equal  to  the  head  of  the  binding 

environment  at  this  level  then  return  T  and  set  TERMB  and 
INDEXB  accordingly  *) 

( (EQUAL  (CONS  VAR  INDEX)  (CAR  (BINDINGS  BNDEV) ) ) 

(SETQ  TERMB  (CADAR  (BINDINGS  BNDEV))) 

(SETQ  INDEXB  (CAR  (CDDAR  (BINDINGS  BNDEV)))) 

T  ) 

(*  else  see  if  it  is  bound  in  the  tail  of  the  binding 
environment  at  this  level  *) 

((ISBOUND  VAR  INDEX  (CDR  (BINDINGS  BNDEV)))  T) 

(*  if  not  then  check  INDEX  to  see  whether  to  search  the  left 
or  right  parent  binding  environment  *) 

( (LEQP  INDEX  (MAXNDX  (LPAR  BNDEV))) 

(*  search  left  parent  *) 

(ISBOUND  VAR  INDEX  (LPAR  BNDEV))  ) 

(*  search  right  parent  *) 

((ISBOUND  VAR  (DIFFERENCE  INDEX  (MAXNDX  (LPAR  BNDEV)))  (RPAR 
BNDEV) ) 

(*  adjust  INDEXB  accordingly  *) 

(SETQ  INDEXB  (PLUS  INDEXB  (MAXNDX  (LPAR  BNDEV)))) 

(*  and  return  success  *) 

T  ) 

(*  all  possible  approaches  failed  so  return  NIL  for  not  bound  *) 
NIL  )) 

(DEFUN  OCCUR  (LAMBDA  (V  I  TERM  J) 

(*  see  if  the  variable  V  under  the  index  I  occurs  in  the  term 


TERM  under  the  index  J  and  return  T  or  NIL  *) 

(*  if  TERM  is  a  variable  *) 

((VARIABLEP  TERM) 

(*  then  if  it  is  bound  *) 

((ISBOUND  TERM  J  BNDEV) 

(*  then  make  the  substitution  and  test  for  occurance  *) 
(OCCUR  V  I  TERMB  INDEXB)  ) 

(*  if  V  equals  TERM  *) 

( (EQ  V  TERM) 

(*  then  return  T  if  I-J  else  NIL  *) 

(EQ  I  J)  )  ) 

(*  if  TERM  is  atomic  and  not  a  variable  *) 

(*  then  it  is  a  constant  so  return  NIL  *) 

((ATOM  TERM)  NIL) 

(*  otherwise  if  V  under  I  occurs  in  the  head  of  TERM  under  J 
then  return  T  *) 

( (OCCUR  V  I  (CAR  TERM)  J)  T) 

(*  otherwise  return  T  if  V  under  I  occurs  in  the  tail  of  TERM 
under  J  and  NIL  otherwise  *) 

(OCCUR  V  I  (CDR  TERM)  J)  )) 

(DEFUN  BIND  (LAMBDA  (V  I  TERM  J  BNDEV) 

(*  bind  V  under  I  to  TERM  under  J  in  BNDEV  *) 

(SETBINDINGS  BNDEV  (CONS  (CONS  (CONS  V  I)  (CONS  TERM  J) ) 
(BINDINGS  BNDEV) ) )  ) ) 

(DEFUN  *  (LAMBDA  COMMENTS 
NIL  )) 

(DEFUN  MAKECL  (LAMBDA  (CL) 

(*  make  a  clause  record  out  of  the  expression  CL  *) 

(LIST  CL  0  NIL  0  (NMEMS  CL)  1  NIL)  )) 


End  Listing  Seven 


LISTING  EIGHT 


(SETQ  CLAUSE- 1 
(  (F  x  y)  (G  x) 

(SETQ  CLAUSE-2 
(  (P  A  B  C)) 
(SETQ  CLAUSE- 3 
((G  «) 


'  ( (F  x  y)  (G  x) 
(P  A  y  x)) 

'  <  (P  A  B  C)) ) 

' ((g  on 


(P  A  y  x)  )) 


(SETQ  TEST  (RESOLVE  (MAKECL  CLAUSE-1)  2  (MAKECL  CLAUSE-3)  1) ) 

( 

(  ( (F  X  y)  (G  x)  (P  A  y  x))  0  NIL  031  NIL  ) 

2 

(  ((GC))  0  NIL  Oil  NIL  ) 

1 

2 

2 

(  ((x  .  1)  C  .  2)) 

) 


End  Listings 
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LISTING  ONE  (Text  begins  on  page  42.) 


\  LIFE  in  Expert-2 

\  simple  demo  program  -  this  version  on  MVP  Forth 
\  by  Jack  Park  1985 

:  WALL  ;  \  something  to  forget  when  done 

NOSHOW  \  a  word  added  to  EXPERT-2  to  cause  suppression  of  display 
\  of  any  inferences.  Sets  a  variable  to  00.  Variable  is  tested 
\  by  each  printing  word. 

VARIABLE  ARRAY 1  510  ALLOT 
VARIABLE  ARRAY2  510  ALLOT 

\  during  a  given  pass  through  the  cells,  one  array  will  be  the 
\  "old"  array,  the  other  the  "new"  array.  On  the  next  pass, 

\  arrays  reverse  position. 

:  CLEAR 1  ARRAY1  512  ERASE  ; 

:  CLEAR2  ARRAY2  512  ERASE  ; 

VARIABLE  "OLD 
VARIABLE  "NEW 
VARIABLE  "CELL 
VARIABLE  ?CELL 
VARIABLE  CELLTOGGLE 

VARIABLE  II  \  miscellaneous  variable  use  in  counting 

VARIABLE  JJ 
VARIABLE  KK 

219  CONSTANT  SYMBOL  \  graphics  symbol  for  IBM  PC  display 
\  this  symbol  can  be  changed  to  virtually  any  ASCII  symbol 
\  e.g.  ASCII  *  CONSTANT  SYMBOL  will  print  a  at  each  live  cell 

:  IJ  (  J  I  —  )  32  *  SWAP  2*  +  "OLD  0+0  (is  alive?  ) 

IF  1  "CELL  0  +!  THEN  ;  \  printing  symbol  is  truth  value  here 
\  if  a  printing  symbol  is  in  a  cell,  it  is  alive. 

\  if  a  cell  is  alive,  increment  count  in  center  cell.  Note,  this 
\  routine  counts  total  of  alive  "nearest  neighbors"  to  center 

\  cell . 

:  FIX  (  n  —  n  )  DUP  -1  - 
IF  DROP  15 

ELSE  DUP  16  -  IF  DROP  0  THEN 
THEN  ;  \  bounds  checking  for  array  edges 

\  this  form  of  bounds  checking  forces  a  square  (flat)  array  to 
\  behave  like  a  torus  -  there  will  be  end  effects  when  a 
\  life  form  grows  beyond  the  visible  edge  of  the  array. 

:  SETCELL  (  J  I  —  )  32  *  SWAP  2*  +  "NEW  0+0  OVER  ! 

(  clear  cell  )  "CELL  !  (  save  cell  address  )  ; 

\  support  for  numeric  processing  of  cell  counts 


:  DOCELLS  16  0  (  —  )  \  here  is  the  main  numeric  loop 
DO  16  0  (  note:  16  x  16  array  of  cells  ) 

DO  J  I  SETCELL 

J  1-  FIX  I  IJ 
J  1+  FIX  I  IJ 
J  I  1-  FIX  IJ 
J  I  1+  FIX  IJ 
J  1-  FIX  I  1-  FIX  IJ 
J  1-  FIX  I  1+  FIX  IJ 
J  1+  FIX  I  1-  FIX  IJ 
J  1+  FIX  I  1+  FIX  IJ 

LOOP 

LOOP  ;  \  count  all  alive  cells  around  each  cell 

\  count  is  saved  in  "NEW"  cell 

\  this  routine  could  be  sped  up,  but  it  runs  in  about  2  seconds 
\  as  is. 


\  be  sure  to  call  one  of  the  starting  patterns  before  RUN 
ARRAY 1  "NEW  !  0  ?CELL  !  32  0  (  run  up  to  32  generations  ) 

DO  16  0  I  1+  KK  1  SHOWCELLS 
DO  I  JJ  !  16  0 

DO  I  II  !  DIAGNOSE  (  run  the  rules  )  LOOP 
LOOP  0  ?CELL  !  ? TERM INAL  IF  LEAVE  THEN  (  tap  any  key  to  stop  ) 
LOOP  1  KK  +!  SHOWCELLS  ; 

\  II,  JJ,  and  KK  carry  loop  counters  outside  the  loops.  It  is 

\  not  possible  to  simply  pass  these  values  on  the  stack,  because 

\  they  are  used  well  into  the  DIAGNOSE  -  inference  engine  - 

\  routine. 

:  RUNCELLS  (  used  by  rules  )  ?CELL  0  NOT  (  have  we  run  yet?  ) 

IF  CELLTOGGLE  0 

IF  ARRAY 1  "OLD  !  ARRAY2  "NEW  !  0 

ELSE  ARRAY2  "OLD  !  ARRAY1  "NEW  !  1 

THEN  CELLTOGGLE  !  DOCELLS  (  get  all  the  counts  ) 

THEN  1  ?CELL  !  ; 


:  (ADDR)  JJ  0  32  *  II  @  2*  +  ;  \  numeric  support 

\  following  are  antecedent  numeric  tests  used  by  the  rules 
:  COUNT-O  (ADDR)  "NEW  0  +  0  0-  ;  \  return  truth  to  rules 
:  COUNT-1  (ADDR)  "NEW  0+01—; 

:  COUNT-2  (ADDR)  "NEW  @  +  @  2  -  ; 

:  COUNT-3  (ADDR)  "NEW  0+03—; 

:  COUNT>— 4  (ADDR)  "NEW  @  +  @  4  <  NOT  ; 

:  ? ALIVE  (  —  tf  )  RUNCELLS  (ADDR)  "OLD  0  +  0  ; 

\  note  use  of  the  print  character  as  a  truth  flag  in  ?ALIVE. 

\  each  antecedent  test  returns  a  truth  value  based  on  a  test: 

\  e.g.  COUNT-O  looks  at  the  "current"  new  cell  to  see  what  the 

\  count  of  its  nearest  neighbors  has  been  found  to  be.  Returns 
\  TRUE  if  count  -  0,  otherwise  returns  FALSE.  This  value  is 
\  the  truth  value  for  the  clause  that  called  COUNT-O  in  the 
\  rules  (ANDRUN  COUNT-0,  etc.) 

\  following  are  consequent  numeric  procedures  called  by  the 
\  rules 

:  LIVE  SYMBOL  (ADDR)  "NEW  0  +  1  TRUE  (  dummy  truth  value  )  ; 

:  DIE  0  (ADDR)  "NEW  @  +  !  TRUE  ; 

\  note  the  use  of  SYMBOL  as  a  truth  value;  SYMBOL  must  be  >  0 
:  PROPAGATE  (ADDR)  "OLD  0+0  (ADDR)  "NEW  0  +  !  TRUE  ; 

\  notice  that  all  procedures  must  return  a  truth  value  to 
\  the  inference  engine  -  even  in  the  consequent  fields. 

\  e.g.  LIVE  stores  the  SYMBOL  (which  means  the  cell  is  now 
\  alive)  into  the  current  cell,  then  returns  a  dummy  TRUE. 

\  following  is  the  knowledge  base 

RULES  \  beginning  of  rules,  start  the  rule  compiler 
IFRUN  ?ALIVE 
ANDRUN  COUNT-2 
THEN  cell  lives 
ANDTHENRUN  LIVE 
IFRUN  ?ALIVE 
ANDRUN  COUNT-3 
THEN  cell  lives 
ANDTHENRUN  LIVE 
IFNOTRUN  ? ALIVE 
ANDRUN  COUNT-3 
THEN  cell  lives 
ANDTHENRUN  LIVE 
IFRUN  COUNT-O 
THEN  cell  dies 
ANDTHENRUN  DIE 
IFRUN  COUNT>-4 
THEN  cell  dies 
ANDTHENRUN  DIE 
IFNOT  cell  lives 
ANDNOT  cell  dies 
THENHYP  cell  propagates 
ANDTHENRUN  PROPAGATE 

DONE  \  tidy  up  and  stop  the  rule  compiler. 

\  note  that  EXPERT-2  inference  engine  must  be  modified  with 


\  addition  of  a  variable  to  suppress  printing  out  inferences. 


End  Listing 


:  ( INITCELL)  (  y  x  —  )  32  *  SWAP  2  *  +  ARRAY1  +  SYMBOL  SWAP  !  ; 

:  EATER  (  a  starting  design  )  CLEAR 1 

5  4  (INITCELL)  6  4  (INITCELL)  1  5  (INITCELL)  2  5  (INITCELL) 

4  5  (INITCELL)  7  5  (INITCELL)  1  6  (INITCELL)  2  6  (INITCELL) 

5  6  (INITCELL)  6  6  (INITCELL)  ; 

:  PENTA  (  a  starting  design  )  CLEAR1 

4  6  (INITCELL)  9  6  (INITCELL)  2  7  (INITCELL)  3  7  (INITCELL) 

9  5  DO  I  7  (INITCELL)  LOOP  10  7  (INITCELL)  11  7  (INITCELL) 

4  8  (INITCELL)  9  8  (INITCELL)  ; 

\  to  run  the  system,  one  types  PENTA  RUN,  or  EATER  RUN 
\  consult  BYTE  Magazine,  December  1978  for  further  details 
\  cells  will  not  necessarily  behave  as  advertised  because  of 
\  edge  effects  in  a  limited  array 

:  SHOWCELLS  HOME  (  alias:  PAGE,  clearscreen)  16  0 
DO  16  0 

DO  J  32  *  I  2*  +  "NEW  0+0  EMIT  LOOP  CR 
LOOP  CR  KK  0  .  ;  \  display  the  array 


:  RUN  (  the  main  word  )  CLEAR2  1  CELLTOGGLE  ! 
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68K  ASSEMBLER 

LISTING  ONE  (Text  begins  on  page  52.) 

DEFINITION  MODULE  LongNumbers; 

PROCEDURE  LineParts  (f  :  FILE;  VAR  EndFile  :  BOOLEAN; 

(*  Routines  to  handle  HEX  digits  for  the  X68000  cross 

assembler.  •) 

VAR  Label,  Opcode  :  TOKEN; 

(*  All  but  LongPut  and  LongWrite  are  limited  to  8  digit  numbers.  •) 

VAR  SrcCp,  DestOp  :  OPERAND); 

(*  Reads  Line,  breaks  into  tokens,  on-passes  to  symbol  £  code  generators  *) 

FILE; 

END  Par«=*»r. 

EXPORT  QUALIFIED 

End  Listing  Three 

LONG,  LongClear,  LongAdd,  LongSub,  I.onglnc,  LongDec, 

LongCompare,  CardToLong,  LongToCard,  LongToInt, 

LongPut,  LongWrite,  StringToLong,  AddrBoundL,  AddrBoundW; 

CONST 

DIGITS  -  8; 

BASE  -  16; 

LISTING  FOUR 

TYPE 

LONG  -  ARRAY  (1.. DIGITS)  OF  INTEGER; 

DEFINITION  MODULE  SymbolTable; 

(*  Initializes  symbol  table.  Maintains  list  of  all  labels,  *) 

PROCEDURE  LongClear  (VAR  A  :  LONG) ; 

(*  along  with  their  values.  Provides  access  to  the  list.  *) 

(•  Sets  LONG  to  Zero  •) 

FRCM  LongNumbers  IMPORT 

PROCEDURE  LongAdd  (A.  B  ;  LONG;  VAR  Result  :  LONG) 

LONG; 

(*  Add  two  LONGs.  giving  Result  *) 

PROCEDURE  LongSub  (A,  B  :  LONG;  VAR  Result  :  LONG) 

FROM  Parser  IMPORT 

(•  Subtract  two  LONGs  (A  -  B) ,  giving  Result  •) 

PROCEDURE  CardToLong  (n  :  CARDINAL;  VAR  A  :  LONC) ; 

{•  Converts  CARDINAL  to  LONG  •) 

EXPORT  QUALIFIED 

PROCEDURE  LongToCard  (A  ;  LONG;  VAR  n  :  CARDINAL) 

BOOLEAN; 

FillSymTab,  SortSymTab,  ReadSymTab,  ListSymTab; 

(•  Converts  LONG  TO  CARDINAL,  returns  FALSE  if  conversion  impossible  •) 

PROCEDURE  LongToInt  (A  :  LONG;  VAR  n  :  INTEGER)  :  BOOLEAN; 

PROCEDURE  FillSymTab  (Label  :  TOKEN;  Value  :  LONG;  VAR  Full  ;  BOOLEAN); 

(•  Converts  LONG  to  INTEGER,  returns  FALSE  if  conversion  impossible  *) 

(*  Add  a  symbol  to  the  table  *) 

PROCEDURE  Longlr.c  (VAR  A  :  LONG;  n  :  CARDINAL); 

PROCEDURE  SortSymTab  (VAR  NumSyms  :  CARDINAL) ; 

(•  Sort  symbols  into  alphabetical  order  *) 

(*  Decrement  LONG  by  n  •) 

PROCEDURE  ReadSymTab  (Label  :  ARRAY  OF  CHAR; 

VAR  Value  :  LONG;  VAR  Duplicate  :  BOOLEAN)  :  BOOLEAN; 

PROCEDURE  LongCompare  (A,  B  :  LONG)  :  INTEGER; 

(*  Passes  Value  of  Label  to  calling  program  —  returns  FALSE  if  the  *) 

(•  Returns:  0  if  A  -  B,  -1  if  A  <  B,  +1  if  A  >  B  • 

(•  Label  is  not  defined.  Also  checks  for  Multiply  Defined  Symbols  *) 

PROCEDURE  LongPut  (f  :  FILE;  A  :  ARRAY  OF  INTEGER; 
(•  Put  LONG  number  in  FII£  f  •) 

Size  :  CARDINAL); 

PROCEDURE  ListSymTab  (1  :  CARDINAL;  VAR  Label  :  TOKEN;  VAR  Value  :  LONG) ; 

(*  Returns  the  i-th  item  in  the  symbol  table  *) 

PROCEDURE  LongWrite  (A  :  ARRAY  OF  INTEGER;  Sire  :  CARDINAL); 

(*  Write  LONG  number  to  console  screen  •) 

END  SymbolTable. 

PROCEDURE  StringToLong  (S  :  ARRAY  OF  CHAR;  VAR  A  : 
(•  Converts  a  string  (in  HEX)  into  a  LONG  •) 

LONG)  :  BOOLEAN; 

End  Listing  Four 

PROCEDURE  AddrBoundL  (VAR  A  :  LONG); 

(*  Forces  Address  to  a  68000  long  word  boundary  *) 

LISTING  FIVE 

PROCEDURE  AddrBoundW  (VAR  A  :  LONG); 

(•  Forces  Address  to  a  68000  word  boundary  *) 

DEFINITION  MODULE  CodeGenerator; 

END  LongNumbers . 

End  Listing  One 

(*  Uses  information  supplied  by  Parser,  Opera tionCodes,  *) 

(*  and  SyntaxAnalyzer  to  produce  the  object  code.  *) 

FRCM  Parser  IMPORT 

TOKEN,  OPERAND; 

LISTING  TWO 

FRCM  LongNumbers  IMPORT 

LONG; 

DEFINITION  MCOULE  CmdLin2; 

(*  Parses  command  line  -  returns  pointer  to  an  array  of  pointer  to  strings  *) 

EXPORT  QUALIFIED 

FROM  SYSTEM  IMPORT 

LZero,  AddrCnt,  Pass2,  BuildSymTable,  AdvAddrCnt,  GetObjectCode; 

ADDRESS; 

VAR 

EXPORT  QUALIFIED 

ReadCmdLin; 

Pass2  :  BOOLEAN; 

PROCEDURE  ReadCmdLin  (VAR  ArgC  :  CARDINAL;  VAR  ArgV  :  ADDRESS); 

(*  Gives  count  of  items  in  command  line,  and  an 

array  of  pointer  to  them  *) 

PROCEDURE  BuildSymTable  (VAR  AddrCnt  :  LONG; 

END  QndLin2. 

Label,  Opcode  :  TOKEN; 

LISTING  THREE 

End  Listing  Two 

End  Listing  Five 

LISTING  SIX 

DEFINITION  MODULE  SyntaxAnalyzer; 

(*  Analyzes  the  operands  to  provide  information  for  CodeGenerator  *) 

DEFINITION  MODULE  Parser; 

(*  Reads  the  Source  file,  and  splits  each  *) 

FRCM  LongNumbers  IMPORT 

(*  line  into  Label,  Opcode  &  Operand (s) .  *) 

LONG; 

FRCM  Strings  IMPORT 

FRCM  OperationCodes  IMPORT 

STRING; 

ModeTypeA,  ModeTypeB,  ModeA,  ModeB; 

FROM  Files  IMPORT 

FRCM  Parser  IMPORT 

FILE; 

TOKEN,  OPERAND,  OpLoc,  SrcLoc,  DestLoc; 

EXPORT  QUALIFIED 

EXPORT  QUALIFIED 

TOKEN,  OPERAND,  Line,  LineCount,  CpLoc,  SrcLoc,  DestLoc,  LineParts; 

OpMode,  Xtype,  SizeType,  OpConfig,  (*  TYPES  *) 

Size,  InstSize,  (*  VARs  *) 

AddrModeA,  AddrModeB,  Op,  Src,  Dest,  (*  VARs  *) 

CONST 

GetValue,  GetSlze,  (*  PROCEDURE'S  *) 

Tokens ize  -  8; 

OperandSize  -  20; 

GetlnstModeSize,  GetOperand,  GetMultReg;  (*  PROCEDURE'S  *) 

TYPE 

TYPE 

TOKEN  -  ARRAY  [0. .TokenSize]  OF  CHAR; 

OpMode  -  (DReg,  (*  Data  Register  *) 

OPERAND  -  ARRAY  (0. .OperandSize)  OF  CHAR; 

ARDir,  (*  Address  Register  Direct  *) 

ARInd,  (*  Address  Register  Indirect  *) 

VAR 

ARPost,  (*  Address  Register  with  Post- Increment  *) 

OpLoc,  SrcLoc,  DestLoc  :  CARDINAL; 

Line  :  STRING; 

LineCount  :  CARDINAL; 

ARP re,  (*  Address  Register  with  Pre-Decrement  *) 
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LISTING  SIX  (Listing  continued,  text  begins  on  page  52.) 

ARDisp,  (*  Address  Register  with  Displacement  *) 

PROCEDURE  StartListing  (f  :  FILE); 

ARDisX,  (*  Address  Register  with  Disp.  &  Index  *) 

AbsW,  (*  Absolute  Word  (16-bit  Address)  *) 

(*  Sign  on  messages  for  listing  file  —  initialize  *) 

AbsL,  {*  Absolute  Word  (32-bit  Address)  *) 

PCDisp,  (*  Program  Counter  Relative,  with  Displacement  *) 

PROCEDURE  WriteListLine  (f  :  FILE; 

PCDisX,  (*  Program  Counter  Relative,  with  Disp.  &  Index  *) 

AddrCnt,  ObjOp,  CbjSrc,  ObjDest  :  LONG; 

Imm,  (*  Irrmediate  *) 

nA,  nO,  nS,  nD  :  CARDINAL); 

MultiM,  (*  Multiple  Register  Move  *) 

(*  Writes  one  line  to  the  Listing  file.  Including  Object  Code  *) 

SR,  (*  Status  Register  *) 

CCR,  (*  Condition  Code  Register  *) 

USP,  (*  User's  Stack  Pointer  *) 

PROCEDURE  WriteSymTab  (f  :  FILE;  NumSym  :  CARDINAL); 

Null);  (*  Elrror  Condition,  or  Operand  missing  *) 

(*  Lists  symbol  table  in  alphabetical  order  *) 

Xtype  -  (XO,  Dreg,  Areg) ; 

SizeType  -  (SO,  Byte,  Word,  S3,  Long) ; 

END  Listing. 

CpConfig  =  RECORD  (*  OPERAND  CONFIGURATION  *) 

End  Listing  Eight 

Mode  :  OpMode; 

Value  :  LONG; 

Loc  :  CARDINAL;  (*  Location  of  Operand  on  line  *) 

Rn  ;  CARDINAL;  (*  Register  number  *) 

Xn  :  CARDINAL;  (*  Index  Reg.  nbr.  *) 

Xsize  :  SizeType;  (*  size  of  Index  *) 

LISTING  NINE 

X  :  Xtype;  (*  Is  index  Data  or  Address  register?  *) 

DEFINITION  MODULE  Srecord; 

END; 

(*  Creates  Motorola  S-records  of  program:  *) 

(*  SO  -  header  record,  •) 

(■  S2  -  code/data  records  (24  bit  address),  •) 

VAR 

(*  S8  -  termination  record  (24  bit  address).  *) 

Size  :  SizeType;  (*  size  for  OpCode  *) 

AbsSize  :  SizeType;  (*  size  of  operand  (Absolute  only)  *) 

FROM  Files  IMPORT 

FILE; 

InstSize  :  CARDINAL; 

AddrModeA  :  ModeA;  (*  Addressing  modes  for  this  instruction  *) 

FROM  LongNumbers  IMPORT 

AddrModeB  :  ModeB;  (*  ditto  *) 

Op  :  BITSET;  (*  Raw  bit  pattern  for  Opcode  *) 

LONG; 

Src,  Dest  :  OpConfig; 

EXPORT  QUALIFIED 

StartSrec,  WriteSrecLine,  EndSrec; 

PROCEDURE  GetValue  (Operand  :  OPERAND;  VAR  Value  :  LONG) ; 

(*  determines  value  of  operand  (in  Decimal,  HEX,  or  via  Symbol  Table)  •) 

PROCEDURE  StartSrec  (f  :  FILE;  SourceFN  :  ARRAY  OF  CHAR); 

(*  Writes  SO  record  (HEADER)  and  initializes  •) 

PROCEDURE  GetSize  (VAR  Symbol  :  ARRAY  OF  CHAR;  VAR  Size  :  SizeType); 

(*  determines  size  of  opcode:  Byte,  Word,  or  Long  *) 

PROCEDURE  WriteSrecLine  (f  :  FILE; 

AddrCnt,  ObjOp,  ObjSrc,  ObjDest  :  LONG; 

nA,  nO,  nS,  nD  :  CARDINAL); 

(•  Collects  Object  Code  --  Writes  an  S2  record  to  file  if  line  is  full  •) 

PROCEDURE  GetAbsSize  (VAR  Symbol  :  ARRAY  OF  CHAR;  VAR  AbsSize  :  SizeType); 

(*  determines  size  of  operand:  Word  or  Long  *) 

PROCEDURE  EndSrec  (f  :  FILE); 

(*  Finishes  off  any  left-over  (Partial)  S2  line,  •) 

PROCEDURE  GetlnstModeSize  (Mode  :  OpMode;  Size  :  SizeType; 

(•  and  then  writes  S8  record  (TRAILER)  *) 

VAR  InstSize  :  CARDINAL)  :  CARDINAL; 

END  Srecord. 

(*  Determines  the  size  for  the  various  instruction  modes.  *) 

PROCEDURE  GetOperand  (Oper  :  OPERAND;  VAR  Op  :  OpConfig) ; 

End  Listing  Nine 

{*  Finds  mode  and  value  for  source  or  destination  operand  *) 

PROCEDURE  GetMultReg  (Oper  :  OPERAND;  PreDec  :  BOOLEAN; 

Loc  :  CARDINAL;  VAR  Mult Ext  :  BITSET) ; 

LISTING  TEN 

(*  Builds  a  BITSET  marking  each  register  used  in  a  MCVEM  instruction  *) 

END  SyntaxAnalyzer. 

MODULE  X 68 000; 

End  Listing  Six 

(*  *) 

(*  MC68000  Cross  Assembler  *) 

(•  Copyright  (c)  1985  by  Brian  R.  Anderson  *) 

LISTING  SEVEN 

(*  This  program  may  be  copied  for  personal,  non-commercial  use  *) 

(*  only,  provided  that  the  above  copyright  notice  is  included  *) 

(*  on  all  copies  of  the  source  code.  Copying  for  any  other  use  *) 

(*  without  the  consent  of  the  author  is  prohibited.  *) 

DEFINITION  MODULE  ErrorX68; 

(*  Displays  error  messages  for  X68000  cross  assembler  *) 

(*  *) 

FROM  Files  IMPORT 

FRCM  Terminal  IMPORT 

FILE; 

WriteString,  WriteLn,  Readstring; 

EXPORT  QUALIFIED 

FROM  Files  IMPORT 

ErrorType,  ErrorCount,  Error,  WriteErrorCount; 

FILE,  FileState,  Open,  Create,  Write,  Close; 

TYPE 

FRCM  Strings  IMPORT 

ErrorType  =  (Dummy,  Too Long,  NoCode,  SymDup,  Undef,  SymFull,  Phase, 

STRING,  CompareStr,  Assign,  Concat,  Length,  Delete; 

ModeErr,  OperErr,  BraErr,  AddrErr,  SizeErr,  EndErr) ; 

IMPORT  ASCII; 

VAR 

ErrorCount  :  CARDINAL; 

FROM  CmdLin2  IMPORT  (*  Access  CP/M  command  line  *) 

ReadCmdLin; 

PROCEDURE  Error  (Pos  :  CARDINAL;  ErrorNbr  :  ErrorType) ; 

(*  Displays  Elrror  f ErrorNbr,  then  waits  for  any  key  to  continue  *) 

FRCM  LongNumbers  IMPORT 

LONG; 

PROCEDURE  WriteErrorCount  (f  :  FILE); 

(*  Error  count  output  to  Console  &  Listing  file  *) 

FRCM  SymbolTable  IMPORT 

SortSymTab; 

END  ErrorX68 . 

FRCM  Parser  IMPORT 

End  Listing  Seven 

TOKEN,  OPERAND,  LineCount,  LineParts; 

FRCM  CodeGenerator  IMPORT 

LISTING  EIGHT 

LZero,  AddrCnt,  Pass2,  BuildSymTable,  AdvAddrCnt,  GetObjectCode; 

FRCM  Listing  IMPORT 

StartListing,  WriteListLine,  WriteSymTab; 

DEFINITION  MODULE  Listing; 

(*  Creates  a  program  listing,  including  Addresses,  Code  &  Source.  *) 

FRCM  Srecord  IMPORT 

StartSrec,  WriteSrecLine,  EndSrec; 

FROM  Files  IMPORT 

FRCM  ErrorX68  IMPORT 

ErrorCount,  WriteErrorCount; 

FRCM  LongNumbers  IMPORT 

LONG; 

TYPE 

EXPORT  QUALIFIED 

FileName  -  ARRAY  [0- .14)  OF  CHAR; 

StartListing,  WriteListLine,  WriteSymTab; 
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LISTING  TEN 

(Listing  continued,  text  begins  on  page  52.) 


Write  (List,  ASCII. sub);  Write  (Srec,  ASCII. sub); 

IF  (Close  (Source)  f  FileOK) 

OR  (Close  (List)  #  FileOK) 

OR  (Close  (Srec)  f  FileOK)  THEN 
WrlteString  ("Error  closing  files...");  WriteLn; 
HALT; 

END; 

END  CloseFiles; 


VAR 

ArgC  :  CARDINAL; 

ArgV  :  POINTER  TO  ARRAY  [1 . .3]  OF  POINTER  TO  STRING;  (*  Command  Line  *) 
SourceFN,  ListFN,  SrecFN  :  FileName; 

Source,  List,  Srec  :  FILE; 

Label,  Opcode  :  TOKEN; 

SrcOp,  DestOp  :  OPERAND; 

EndFile  :  BOOLEAN; 

NumSyms  :  CARDINAL; 

ObjOp,  ObjSrc,  ObJDest  :  LONG; 
nA,  nO,  nS,  nD  :  CARDINAL; 


PROCEDURE  MakeNames  (VAR  S,  L,  R  :  FileName); 

(*  builds  names  for  Source,  Listing  &  S-Record  files  *) 

VAR 

T  :  FileName;  (*  temporary  work  name  *) 

1,  1  :  CARDINAL; 

BEGIN 

L  R  (*  set  Listing  &  S-rec  names  to  null  *) 

i  0;  1  0; 

WHILE  (S [i 1  t  0C)  AND  (S(iJ  •  '  ')  DO 

IF  S [i ]  -  THEN  (*  mark  beginning  of  file  extension  *) 
1  :«*  i; 

END; 

S[i)  CAP  (S[i) ) ; 

INC  (i); 

END; 

IF  S [1 )  -  '  '  THEN 

Delete  (S,  i.  Length  (S)  -  i)  ; 

END; 

Assign  (S,  T) ? 

IF  1  -  0  THEN 

Concat  (T,  ".ASM",  S) ; 

ELSE 

Delete  (T,  1,  i  -  1)  ; 

END; 

Concat  (T,  ".LST",  L) ; 

Concat  (T,  "  .S",  R) ; 

END  MakeNames; 


PROCEDURE  OpenFiles; 

BEGIN 

IF  Open  (Source,  SourceFN)  «  FileOK  THEN 
WriteLn; 

WriteString  ("No  Source  File:  ");  WrlteString  (SourceFN); 
WriteLn; 

HALT; 

END; 

IF  Create  (List,  ListFN)  #  FileOK  THEN  (*  DOS  may  trap  this  *) 
WriteLn; 

WriteString  ("Cannot  create  disk  files!");  WriteLn; 

HALT; 

END; 

IF  Create  (Srec,  SrecFN)  #  FileOK  THEN 
WriteLn; 

WriteString  ("Cannot  create  disk  files!");  WriteLn; 

HALT; 

END; 

END  OpenFiles; 


PROCEDURE  StartPass2; 

BEGIN 

IF  (Close  (Source)  I  FileOK)  OR 
(Open  (Source,  SourceFN)  I  FileOK)  THEN 
WriteString  ("Unable  to  'Reset*  Source  file  for  2nd  Pass."); 
WriteLn; 

HALT; 

END; 

Pass2  TRUE;  (*  Pass2  IMPORTed  frccn  CodeGenerator  *) 

AddrCnt  LZero;  (*  Assume  ORG  =  0  to  start  *) 

ErrorCount  0;  (*  ErrorCount  IMPORTed  from  ErrorX68  •) 

LineCount  0;  (*  LineCount  IMPORTed  from  Parser  *) 

EndFile  FALSE; 

END  StartPass2; 


BEX5IN  (*  X68000  —  main  program  *) 

ReadCmdLln  (ArgC,  ArgV) ; 

IF  ArgC  -  0  THEN 
WriteLn; 

WriteString  ("Enter  Source  Filename:  "); 
Readstring  (SourceFN)  ; 

WriteLn; 

ELSE 

Assign  (ArgV'' [1  p,  SourceFN); 

END; 

MakeNames  (SourceFN,  ListFN,  SrecFN); 


OpenFiles; 


WriteLn; 
WrlteString  (" 
WriteString  (" 
WriteLn;  WriteLn; 
WriteString  (" 
WriteLn;  WriteLn; 


68000  Cross  Assembler")  ;  WriteLn; 

~  pyrlght  (c)  1985  by  Brian  R.  Anderson"); 

Assembling  ");  WriteString  (SourceFN); 

WriteLn; 


Begin  Pass  1 

- .) 

WriteString  ("PASS  1");  WriteLn; 

AddrCnt  :-  LZero;  (*  Assume  ORG  -  0  to  start  *) 

EndFile  :-  FALSE; 

REPEAT 

LineParts  (Source,  EndFile,  Label,  Opcode,  SrcOp,  DestOp); 
BulldSymTable  (AddrCnt,  Label,  Opcode,  SrcOp,  DestOp); 
AdvAddrCnt  (AddrCnt ) ; 

UNTIL  EndFile  OR  (CompareStr  (Opcode,  "END")  -  0); 


Begin  Pass  2 

- .) 

WrlteString  ("PASS  2");  WriteLn; 

StartPass2;  (*  get  Source  file.  Parser  &  ErrorX68  ready  for  2nd  pass  *) 
SortSymTab  (NumSyms) ; 

StartLlsting  (List); 

StartSrec  (Srec,  SourceFN) ; 

REPEAT 

LineParts  (Source,  EndFile,  Label,  Opcode,  SrcOp,  DestOp); 

GetObjectCode  (Label,  OpCode, 

SrcOp,  DestOp, 

AddrCnt,  CbjCp,  ObjSrc,  ObjDest, 
nA,  nO,  nS,  nD  ) ; 

WriteListLine  (List,  AddrCnt,  CbjOp,  ObjSrc,  ObjDest,  nA,  nO,  nS,  nD) ; 
WriteSrecLine  (Srec,  AddrCnt,  ObjOp,  ObjSrc,  ObjDest,  nA,  nO,  nS,  nD) ; 
AdvAddrCnt  (AddrCnt ) ; 

UNTIL  EndFile  OR  (CompareStr  (OpCode,  "END")  -  0) ; 

EndSrec  (Srec);  (*  Also:  Finish  off  any  partial  line  *) 

WrlteErrorCount  (List);  (*  Error  count  output  to  Console  &  Listing  file  *) 
WriteSymTab  (List,  NumSyms);  (*  Write  Symbol  Table  to  Listing  File  *) 
CloseFiles; 

END  X 68 000. 


End  Listings 


PROCEDURE  CloseFiles; 

BEGIN 

(* - 

<*  *> 

(*  Ctrl-Z  written  to  files  before  closing  *) 

(*  due  to  bug  in  "Files"  module.  Remove  these  *) 

(*  before  submitting  listing  for  publication.  *) 

(*  *) 

(* - *) 
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_ METRIC  MINIMIZER 

LISTING  FOUR  (continued  from  March) 


/*  A'JXL.C 
* 

*  The  line  search  and  decision  routines 

*  (c)  Copyright  1985,  Billybob  Software.  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 
*/ 


^include  "global.h" 


/ 


**************************************** 


*/ 


getalpha  (  n  , 

fun  , 

xx  ,  xstep  , 

xlim  ,  z  ,  s  ,  g  ,  gO  , 

alpha 

,  debug  ,  data  ,  npoints  ,  const  ) 

int 

n  ; 

/*  number  of 

parameters 

*/ 

double 

(*fun) ( 

)  ; 

/*  pointer  to  the  function  to  minimize 

*/ 

double 

xx  []  ; 

/*  parameter 

vector 

*/ 

double 

xstep [ 

]  ; 

/*  stepsize 

for  parameter  derivative  calcs 

*/ 

BOUND 

xlim [ ] 

; 

/*  limits  on 

parameters 

*/ 

double 

z[]  ; 

/*  gradient 

vector 

*/ 

double 

s  [ )  ; 

/*  changes  direction  vector 

*/ 

double 

g  ; 

/*  value  of 

fen  for  the  given  vector  xx 

*/ 

double 

go  ; 

/*  expected 

value  of  the  minimum  of  the  fen 

*/ 

double 

*alpha 

; 

/*  scaling  parameter  we  are  trying  to  find 

*/ 

int 

debug  ; 

/*  flag  =  0 

for  no  print,  >0  for  debug  print 

*/ 

DATA 

data [ ) 

; 

/*  the  data 

*/ 

int 

npoints 

; 

/*  number  of 

data  points 

*/ 

double 

{ 

const [ 

)  ; 

/*  constants 

vector  needed  by  fen 

*/ 

/* 

*  find 
*/ 

alpha 

according  to 

Cohen,  pp  279-280 

int 

i  ; 

static 

double 

u  ; 

/*  see  Cohen  */ 

static 

double 

eta  ; 

/*  see  Cohen  */ 

static 

double 

t [ VECMAX ]  ; 

/*  see  Cohen  */ 

static 

double 

text [VECMAX]  ;  /*  same,  in  external  coordinates 

*/ 

static 

double 

zt [VECMAX]  ; 

/*  the  z  for  fen  evaluated  at  x  =  t 

*/ 

static 

double 

gt  ; 

/*  the  g  that  results  from  fen  at 

*/ 

/*  ■  =  t 

*/ 

static 

double 

nu  ; 

/*  see  Cohen  */ 

static 

double 

d  ; 

/*  see  Cohen  */ 

static 

double 

w  ; 

/*  see  Cohen  */ 

static 

double 

tempi  ; 

static 

double 

temp2  ; 

if  (debug>l)  { 

print f  ( "\t\t+  line  search  procedure  +\n") 

} 

u  =  dot  (  n  ,  z  ,  s  )  ; 
eta  =  -2.0  *  (g-gO)  /u; 

if  (eta  >  1.0) 

eta  =  1.0  ; 


for  (i=0  ;  i<n  ;  ++i) 

t  [ i ]  =  xx [i]  +  eta  *  s[i]  ; 

gozouta  (  n  ,  t  ,  text  ,  xlim  )  ; 

gt  =  (*fun)  (  const  ,  text  ,  data  ,  npoints  ,  0  )  ; 

derivs  (  n,  fun,  t,  xstep,  xlim,  zt,  data,  npoints,  const,  debug  ) ; 
nu  =  dot  (  n  ,  zt  ,  s  )  ; 

if  (debug>l) 

{ 

printf("u  and  nu  are:  %11.4e  %11.4e\n",  u  ,  nu  )  ; 
printfC'g  and  gt  are:  %11.4e  %11.4e\nM,  g  ,  gt  )  ; 
printfC'eta  is:  %11.4e\n",  eta  )  ; 
if  (debug>2) 

{ 

printf ( "vector  t  is:\n")  ; 
vout  (  n  ,  t  )  ; 
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print f ( "vector  zt  is:\n")  ; 
vout (  n  ,  zt  )  ; 

} 

} 

d  =  3*(g  -  gt)/eta  +  u  +  nu  ; 

if  (  (tempi  =  d*d)  <  (temp2  =  u*nu)  ) 

{ 

if  (debug>l) 

{ 

print f ( "cubic  interpolation  has  failed,  ")  ; 

print f ( "about  to  take  sqrt  of  negative  number !\n")  ; 

print f("d  squared  is  %11.4e  ",  tempi  )  ; 

printf("and  u*nu  is  %11.4e\n",  temp2  )  ; 

printf ("difference  is  %11.4e\n",  templ-temp2  )  ; 

} 

if  (  u  <  0.0  &&  nu  <  0.0  &&  gt  <  g  ) 

{ 

*alpha  =  eta  ; 
if  (debug>l) 

print f ( "return  with  alpha  =  eta\n")  ; 
return (  OK  )  ; 

} 

else 

( 

‘alpha  =  0.0  ; 
if  (debug>l) 

printf ("line  search  has  failed\n")  ; 
return (  BADLS  )  ; 

} 

} 

else 

{ 

w  =  sqrt (tempi  -  temp2)  ; 

‘alpha  =  eta  *  (  1.0  -  (nu+w-d) / (nu-u+2 . 0*w)  )  ; 
if  (debug>l) 

print f ("alpha  returned  is  %11.4e\n",  ‘alpha  )  ; 
return  (  OK  )  ; 

} 

} 

/***********★********************************************•*******************/ 


decide 

(  g  ,  gnew  , 

n  , 

znewi  , 

sigma  ,  y  , 

epsilon  . 

,  itermin 

,  iterations  ,  debug  ) 

double 

g  ; 

/* 

old  value  of  minimum 

*/ 

double 

gnew  ; 

/* 

new  value  of  minimum 

*/ 

int 

n  ; 

/* 

number  of  parameters 

*/ 

double 

znewi(]  ; 

/* 

vector  of  new  gradients 

*/ 

double 

sigma (]  ; 

/* 

change  vector  for  parameters 

*/ 

double 

y[]  ; 

/* 

the  transformation  matrix 

*/ 

double 

epsilon (]  ; 

/* 

cutoff  criteria  vector 

*/ 

int 

itermin  ; 

/* 

minimum  number  of  iterations 

*/ 

int 

iterations  ; 

/* 

current  iteration  number 

*/ 

int 

debug  ; 

/* 

debug  flag 

*/ 

{ 

/* 

*  makes  the  decision  to  continue  iterating  or  not 

*  returns  a  zero  if  we  want  to  keep  going 

*  returns  a  positive  number  if  we  have  a  normal  stopping  reason 

*  returns  a  negative  number  if  we  have  a  catastrophic  stopper 

*/ 

static  double  edm  ; 

static  double  temp [VECMAX]  ; 

if  (debug>l) 

{ 

printf ("\t\t+++++++++++++++++++++++++\n")  ; 
printf ("\t\t+  decision  making  logic  +\n")  ; 
printf ("\t\t+++++++++++++++++++++++++\n")  ; 
printf ("old  minimum  was:  %11.4e,  new  minimum  is  %11.4e\n", 
g  ,  gnew  )  ; 

printf ("ratio  new/old  is:  %11.4e\n",  gnew/g  )  ; 

} 

/* 

*  exit  if  the  new  "minimum"  is  greater  than  or  equal  to  the  old  minimum 
*/ 
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if  (gnew  >=  g) 

{ 

if  (debug>l) 

print f ( "STOP !! !  new  minimum  is  not  lower !\n")  ; 

return  (  BADMIN  )  ; 

) 

/* 

*  if  the  edm  (estimated  distance  to  the  minimum)  is  negative  we  have 

*  a  catastrophic  problem  and  should  stop 
*/ 

matvec (  n  ,  y  ,  znewi  ,  temp  )  ; 
edm  =  dot (  n  ,  znewi  ,  temp  )  ; 

if (  edm  <0.0  ) 

{ 

if  (debug>l) 

printf ( "STOP ! ! !  edm  is  negative  =  %11.4e\n",  edm); 
return  (  NEGEDM  )  ; 

) 

/* 

*  now  look  at  normal  exits  if  the  minimum  number  of  iterations  has 

*  been  accomplished 
*/ 

if  (iterations  <  itermin)  { 

if  (debug>l)  printf (" — >keep  going,  too  few  iterat ions\n")  ; 
return (  OK  )  ; 

) 

/* 

*  edm  test:  two  ways  to  calculate,  stop  if  either  satisfies 
*/ 

if  (edm  <  epsilon [0]) 

( 

if  (debug>l) 

print f ( "STOP,  close  enough,  edm  =  %11.4e\n",  edm); 
return  (  EDM1  )  ; 

} 

edm  =  dot (  n  ,  sigma  ,  sigma  )  ; 

if  (edm  <  epsilon [0]) 

( 

if  (debug>l) 

printf ( "STOP,  close  enough,  edm  =  %11.4e\n",  edm); 
return  (  EDM2  )  ; 

) 

/* 

*  %  change  in  g  less  than  "something"  means  that  approach  is  too  slow 
*/ 

if  (  g-gnew  <  epsilon [l]*g  ) 

( 

if  (debug>l) 

printf ("STOP,  too  slow,  fractional  change  =  %11.4e\n", 
(g-gnew) /g  )  ; 

return  (  TOOSML  )  ; 

) 

/* 

*  fall  through  case 

*  note  that  case  of  maximum  number  of  iterations  is  handled  in  the 

*  calling  program 
*/ 

if  (debug>l) 

printf (" - >keep  going,  no  stoppers  found... \n")  ; 

return (  OK  )  ; 


End  Listing  Four 
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bfgsa  i 

[  n  ,  y  , 

sigma  ,  xi 

,  a  ,  debug  ) 

int 

n  ; 

/* 

number  of  parameters 

*/ 

double 

*y  ; 

/* 

current  Y  matrix 

*/ 

double 

*sigma  , 

r  /* 

changes  vector 

*/ 

double 

*xi  ; 

/* 

change  in  gradient  vector 

*/ 

double 

*a  ; 

/* 

the  result 

*/ 

int 

debug  ; 

/* 

flag  =  0  for  no  print,  >0  for  debug  print 

*/ 

f 

/* 

*  compute  the  matrix  A  which  is  used  to  correct  Y 

*  Broyden  Fletcher  Goldfarb  Shanno  method 
*/ 

int  i  ,  j  ; 

static  double  temp[VECMAX]  ; 
static  double  tmpa [MATMAX]  ; 
double  norm  ; 

norm  =  1.0  /  dot  (  n  ,  sigma  ,  xi  )  ; 
matvec (  n  ,  y  ,  xi  ,  temp  )  ; 

for  ( j=0  ;  j<n  ;  +  + j) 

temp( j]  *  sigma [j]  -  temp[j]  ; 

cross (  n  ,  temp  ,  sigma  ,  tmpa  )  ; 
cross (  n  ,  sigma  ,  temp  ,  a  )  ; 
i  =*  n*n  ; 

for  (j=0  ;  j<i  ;  ++j) 

a [ j ]  =  norm  *  (  a [ j ]  +  tmpa[j]  )  ; 

if  (debug>l) 

{ 

print f ( "AAAAA  correcting  matrix  AAAAA  is:\n")  ; 
mout (  n  ,  a  )  ; 

} 

} 

/* - */ 


bfgsb  (  n  ,  y  ,  sigma  ,  xi  ,  b  ,  debug  ) 

int  n  ;  /*  number  of  parameters  */ 

double  *y  ;  /*  current  Y  matrix  */ 

double  ♦sigma  ;  /*  changes  vector  */ 

double  *xi  ;  /*  change  in  gradient  vector  */ 

double  *b  ;  /*  the  result  */ 

int  debug  ;  /*  flag  =  0  if  no  print,  >0  for  debug  print  */ 

{ 

/* 

*  compute  the  matrix  B  which  is  used  to  update  Y 

*  Broyden  Fletcher  Goldfarb  Shanno  method 
*/ 


int  i  ; 

static  double  temp(VECMAX)  ; 
double  *t  ; 
double  norm  ; 

t  =  b  ; 

norm  =  1.0  /  dot (  n  ,  sigma  ,  xi  )  ; 
norm  =  -  norm  *  norm  ; 
matvec (  n  ,  y  ,  xi  ,  temp  )  ; 

for  (i=0  ;  i<n  ;  ++i) 

temp[i]  =  sigma [i]  -  temp[i]  ; 

norm  *=  dot (  n  ,  temp  ,  xi  )  ; 
cross (  n  ,  sigma  ,  sigma  ,  b  )  ; 
i  =  n*n  ; 

while (  i —  ) 

*b++  *=  norm  ; 
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/*  UP.C 
* 

*  Routines  for  updating  the  matrix  y 

*  (c)  Copyright  1985,  Billybob  Software.  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 
*/ 


tinclude  "global. h" 

/* - */ 

dfpa  (  n  ,  sigma  ,  xi  ,  a  ,  debug  ) 

int  n  ;  /*  number  of  parameters  */ 

double  *sigma  ;  /*  changes  vector  */ 

double  *xi  ;  /*  change  in  gradient  vector  */ 

double  *a  ;  /*  the  result  */ 

int  debug  ;  /*  flag  =  0  for  no  print,  >0  for  debug  print  */ 

{ 

/* 


*  Compute  the  matrix  A  which  is  used  to  correct  Y 

*  Davidon  Fletcher  Powell  method 
*/ 

int  i  ; 
double  norm  ; 
double  *t  ; 

t  =  a  ; 

cross (  n  ,  sigma  ,  sigma  ,  a  )  ; 
norm  =1.0  /  dot (  n  ,  sigma  ,  xi  )  ; 
i  =  n*n  ; 

while  (  i —  ) 

*a++  *=  norm  ; 

if  (debug>l) 

{ 

print f ("AAAAA  correcting  matrix  AAAAA  is:\n")  ; 
mout (  n  ,  t  )  ; 

) 

} 

/* - */ 


dfpb  (  n  ,  y  ,  xi  ,  b  ,  debug  ) 

int  n  ;  /*  number  of  parameters  */ 

double  *y  ;  /*  current  Y  matrix  */ 

double  *xi  ;  /*  change  in  gradient  vector  */ 

double  *b  ;  /*  the  result  */ 

int  debug  ;  /*  flag  =  0  if  no  print,  >0  for  debug  print  */ 

{ 

/* 

*  compute  the  matrix  B  which  is  used  to  update  Y 

*  Davidon  Fletcher  Powell  method 
*/ 


int  i  ; 

static  double  temp[VECMAX]  ; 
double  *t  ; 
double  norm  ; 

t  =  b  ; 

matvec (  n  ,  y  ,  xi  ,  temp  )  ; 
norm  =  -  1.0  /  dot (  n  ,  temp  ,  xi  )  ; 
cross  i  n  ,  temp  ,  temp  ,  b  )  ; 
i  =  n*n  ; 

while (  i —  ) 

*b++  *=  norm  ; 

if  (debug>l) 

{ 

printf ("BBBBB  correcting  matrix  BBBBB  is:\n")  ; 
mout (  n  ,  t  )  ; 

} 

} 


(continued  on  next  page) 
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if  (debug>l) 

{ 

print f ( "BBBBB  correcting  matrix  BBBBB  is:\n")  ; 
mout  (  n  ,  t  )  ; 

} 

} 

/* - */ 


gety  (  n  ,  a  ,  b  ,  y  ,  debug  ) 

int  n  ; 

double  *a  ; 

double  *b  ; 

double  *y  ; 

int  debug  ; 

{ 

/* 

*  use  matrices  A  and  B  to  correct  Y 
*/ 

int  i  ; 

double  *t  ; 

t  =  y  ; 

i  =  n*n  ; 

while (  i —  ) 

*y++  +=  *a++  +  *b++  ; 

if  (debug>l) 

{ 

print f ( "YYYYY  new  matrix  YYYYY  is:\n") 
mout (  n  ,  t  )  ; 

} 


LISTING  SIX 


End  Listing  Five 


/*  UTIL . C 
★ 

*  Contains  miscellaneous  routines  needed  for  variable  metric  minimization 

*  program,  including  matrix  and  vector  utilities 

*  (c)  Copyright  1985,  Billybob  Software.  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 

*/ 


#include  "global. h" 

#def ine  INALINE  6 


gozinta(  n  ,  xintern  ,  xextern  ,  xlim  ) 

int  n  ; 

double  xintern []  ; 

double  xextern []  ; 

BOUND  xlimU  ; 

{ 

/* 

*  transform  all  external  coordinates  to  internal  coordinates 
*/ 


} 


int  i  ; 

for  (  i=0  ;  i<n  ;  ++i  ) 

tointern (  i  ,  xintern  ,  xextern  ,  xlim  )  ; 


gozouta(  n  ,  xintern  ,  xextern  ,  xlim  ) 

int  n  ; 

double  xintern []  ; 

double  xextern [ ]  ; 

BOUND  xlim [ J  ; 

{ 

/* 

*  transform  all  internal  coordinates  to  external  coordinates 
*/ 


(continued  on  nejct  page) 
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) 


for  (  i=0  ;  i<n  ;  ++i  ) 

toextern (  i  ,  xintern  ,  xextern  ,  xlim  )  ; 


/* - */ 


tointern  (  j  ,  xintern  , 

xextern  , 

xlim  ) 

int 

j  ; 

/* 

parameter  to  transform 

*/ 

double 

xintern []  ; 

/* 

internal  coordinates 

*/ 

double 

xextern []  ; 

/* 

external  coordinates 

*/ 

BOUND 

xlim[]  ; 

/* 

limits  on  the  parameters 

*/ 

i 

/* 

*  transform  to  unbounded  "internal"  coordinates  used  by 

*  minimization  program. 

*/ 

double  y  ; 

if (  xlim [ j ] .fl  ) 

{ 

if  (  xlim [ j ] .mi  ==  0.0  ) 

xintern [j]  =  xextern [j]  ; 

else 

{ 

y  =  (  (xextern [ j] -xlim [ j ]. lo)  /  xlim [j]. mi  )  -  1.0  ; 
xintern (j]  =  atan (  y  /  sqrt (  1.0  -  y*y  )  )  ; 

} 

} 

else 

xintern [j]  =  xextern [j]  ; 

} 

/* - */ 


toextern  (  j  ,  xintern  , 

xextern  , 

xlim  ) 

int 

j  ; 

/* 

parameter  to  transform 

*/ 

double 

xintern []  ; 

/* 

internal  coordinates 

*/ 

double 

xextern ( ]  ; 

/* 

external  coordinates 

*/ 

BOUND 

xlim[]  ; 

/* 

limits  on  the  parameters 

*/ 

/* 

*  transforms  to  bounded  "external"  coordinates  known  to  the  real  world 


*/ 


} 


if (  xlim [ j ] .fl  ) 

xextern( j]  =  xlim[j].lo  +  xlim [j] .mi  * 

(  sin (xintern  [  j] )  +  1.0  )  ; 

else 

xextern [j]  *  xintern [j]  ; 


*/ 


derivs 

(  n  ,  fun  ,  xintern  ,  xstep 

,  xlim  ,  z  ,  data  ,  m  ,  const  ,  debug  ) 

int 

n  ; 

/* 

number  of  parameters 

*/ 

double 

(*fun)  ()  ; 

/* 

pointer  to  the  function  to  minimize 

*/ 

double 

xintern [ ]  ; 

/* 

coordinates  vector 

*/ 

double 

xstep []  ; 

/* 

step  size  to  take  on  each  component 

*/ 

BOUND 

xlim [ ]  ; 

/* 

limit  vector 

*/ 

double 

z[]  ; 

/* 

derivative  vector 

*/ 

DATA 

data [ ]  ; 

/* 

the  data 

*/ 

int 

m  ; 

/* 

number  of  data  points 

*/ 

double 

const  [  ]  ; 

/* 

constants  required  by  fen 

*/ 

int 

( 

debug  ; 

/* 

debug  flag 

*/ 

/* 

*  compute  the 

derivatives 

of  the  vector  x  using  a  simple 

*  finite  difference. 

*/ 

int  i  ; 

static  double 

xextern [VECMAX] ; /*  throwaway  vector  in  ext  coords 

*/ 

static  double 

fl  ,  f 2  ; 

/*  values  of  fen  at  +/-  stepsize 

*/ 

static  double 

xtemp  ; 
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static  double  eps  ; 


gozouta(  n  ,  xintern  ,  xextern  ,  xlim  )  ; 
for  (  i=0  ;  i<n  ;  ++i  ) 

{ 

xtemp  =  xintern  [i]  ; 

eps  =  fabs (  xtemp  )  *  xstep[i]  ; 

xintern [i]  =  xtemp  +  eps  ; 

toextern(  i  ,  xintern  ,  xextern  ,  xlim  )  ; 

fl  =  (*fun)  (  const  ,  xextern  ,  data  ,  m  ,  0  )  ; 
xintern [i]  =  xtemp  -  eps  ; 

toextern(  i  ,  xintern  ,  xextern  ,  xlim  )  ; 
f2  =  (*fun) (  const  ,  xextern  ,  data  ,  m  ,  0  )  ; 
z [ i]  =  (fl  -  f2)  /  (  2.0  *  eps  )  ; 

if  (debug>2) 

printf ("i, f 1, f2, step, deriv  %d  %12e  %12e  %12e  %12e\n", 
i,  fl,  f 2,  eps  ,  z[i]  )  ; 

xintern [i]  =  xtemp  ; 

toextern (  i  ,  xintern  ,  xextern  ,  xlim  )  ; 

} 

if  (debug==2) 

{ 

print f ( "derivatives  are:\n") ; 
vout (  n  ,  z  )  ; 

} 

} 

/* - */ 

raz  (  nparam  ,  itermin  ,  iterlim  ,  nreset  ,  debug  ,  limit  ,  dstep  , 
param  ,  gO  ,  epsilon  ,  method  ) 

(continued  on  ne?d  page) 
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int 

♦nparam  ; 

/* 

number  of  parameters 

*/ 

int 

*itermin  ; 

/* 

minimum  number  of 

iterations 

*/ 

int 

*iterlim  ; 

/* 

maximum  number  of 

iterations 

♦/ 

int 

*nreset  ; 

/* 

reset  y  after  nreset  iters 

*/ 

int 

♦debug  ; 

/* 

debug  flag 

*/ 

BOUND 

limit []  ; 

/* 

limit  vector 

*/ 

double 

dstep[]  ; 

/* 

step  size  for  derivatives 

*/ 

double 

param[]  ; 

/* 

initial  values  of 

parameters 

*/ 

double 

*gO  ; 

/* 

expected  value  of 

minimum 

*/ 

double 

epsilon ( ]  ; 

/* 

stopping  criteria 

vector 

*/ 

int 

♦method  ; 

/* 

update  method  for 

y 

♦/ 

/* 

*  reinitialize  important  parameters  before  reading,  so  that  we 

*  can  later  test  to  see  if  they  were  set  in  the  dataset 
*/ 

int  j  ; 

♦debug  =  *nparam  =  *itermin  =  *iterlim  =  *nreset  =  0  ; 

*g0  =  0.0  ; 

*method  =  DFP  ; 

for  (  j=0  ;  j<VECMAX  ;  ++j  ) 

{ 

limit l j) . f 1  —  0 
dstep[j]  =  0.0  ; 
epsilon [j]  =  0.0  ; 

param[j]  =  0.0  ; 

} 

} 

/* - */ 


dfault 

(  n  ,  itermin  , 

,  iterlim  ,  nreset  ,  epsilon  ,  xlim  ,  dstep  , 

,  debug  ) 

int 

n  ; 

/* 

number  of  parameters 

*/ 

int 

♦itermin  ; 

/* 

minimum  number  of  iterations 

*/ 

int 

♦iterlim  ; 

/* 

maximum  number  of  iterations 

V 

int 

♦nreset  ; 

/* 

reset  y  matrix  after  this  many 

iters  */ 

double 

epsilon (]  ; 

/* 

stopping  criteria  vector 

*/ 

BOUND 

xlimf]  ; 

/* 

limit  vector  for  parameters 

*/ 

double 

dstep[]  ; 

/* 

step  sizes  for  derivative  calc 

*/ 

int 

debug  ; 

/* 

flag  for  debug 

*/ 

/* 

*  this  routine  sets  defaults  if  parameters  not  set  with  input  data 
*/ 

int  j  ; 

if  (debug) 

( 

printf ("\t\t ++++++ +++++++++++++\n")  ; 
printf ("\t\t+  initializations  +\n")  ; 
printf ("\t\t+++++++++++++++++++\n")  ; 

) 

/* 

*  check  that  the  number  of  parameters  has  been  set;  fatal  error  if  not! 
*/ 

if  <  in) 

return  (  -1  )  ; 

/* 

*  set  up  other  defaults  as  required  —  these  depend  on  knowing  n 
*/ 


if  1 

[  !*itermin  ) 

♦itermin  =  n  ; 

if  ( 

!*iterlim  ) 

♦iterlim  =  2*n 

if  ( 

!  *nreset  ) 
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nreset 


(3*n)/2  ; 


for  (j=0  ;  j<n  ;  ++j) 

if  (dstep(j)  ==  0.0) 

dstep(j)  =  0.01  ; 

if  (debug) 

{ 

printfC'min  iters  =  %3d,  max  iters  =  %3d,  ",  *itermin  , 

*iterlim  )  ; 

printf ("reset  y  every  %3d  iterations\n",  *nreset  )  ; 

printf ("step  sizes  for  derivatives : \n")  ;  vout (  n  ,  dstep  )  ; 

) 

if  (  epsilon ( 0 ]  ==  0.0  ) 

{ 

epsilon[0]  =  1.0e-06  ; 
epsilon [1]  =  0.001  ; 

if  (debug)  print f ( "epsilons  set  to  def aults : \n")  ; 

) 

else  if  (debug) 

print f ( "epsilons  from  input  data:\n")  ; 
if  (debug) 

vout (  NEPS  ,  epsilon  )  ; 

/* 

*  note  that  if  you  add  other  stopping  criteria  (more  elements  in 

*  the  epsilon  vector)  you  will  have  to  modify  this  code 

* 

*  the  following  defaults  were  set  in  raz  and  remain  if  not  changed 

*  by  the  data  read  in  reader: 

*  starting  values  of  parameters:  0.0 

*  *  expected  value  of  minimum:  0.0 

*  constrained/unconstrained:  unconstrained  (all) 

*  parameter  names:  blank 
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*  updating  method  for  y  : 


Davidon-Fletcher-Powell  (DFP) 


*  variables  used  for  intern< — >extern  conversions: 


for  ( j=0  ;  j<n  ;  j++) 
if  (xlim [ j J . f 1) 

xlim[j].mi  =  (xlim[j].up  -  xlim[j].lo)  /  2.0  ; 

return (  0  )  ; 


vout  (  n  ,  a  ) 
int  n  ; 
double  *a  ; 

{ 

/* 

*  output  the  floating  point  vector  a  with  n  components 

*  INALINE  values  to  a  line,  indent  succeeding  lines  appropriately 
*/ 

praline (  n  ,  a  ,  0  )  ; 
putchar ( 1 \n  ' )  ; 


praline (  n  ,  a  ,  indent  ) 
int  n  ; 

double  *a  ; 
int  indent  ; 


*  print  out  as  many  lines  as  required,  indenting  as  we  go 


if  (  indent  ) 

{ 

putchar  (' \n 1 )  ; 
for  (  i=indent  ;  i  ;  — i  ) 
putchar  ( '  ' ) ; 

) 

for  <  i=INALINE  ;  i  £&  n  ;  — i  ,  — n  ) 
printf ("%11 . 4e  "  ,  *a++  )  ; 


praline (  n  ,  a  ,  ++indent  ) 


mout  (  n  ,  a  ) 
int  n  ; 
double  *a  ; 


*  output  the  floating  point  matrix  a  with  n  by  n  components 
*/ 

int  i  ; 
double  *p  ; 

for  (i=n  ,  p=a  ;  i  ;  — i  ,  p  +=  n  ) 
vout (  n  ,  p  )  ; 


double  dot (  n  ,  a 
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LISTING  SIX  (Listing  continued) 


cross (  n  ,  vl  ,  v2  ,  m  ) 
int  n  ; 
double  *vl  ; 
double  *v2  ; 
double  *m  ; 

{ 

/* 

*  product  of  two  vectors  of  dimension  n  yielding  an  n  by  n  matrix 
*/ 


int  i  ,  j  ; 

double  *p  ; 


} 


for(  i=n  ,  p=v2  ;  i  ;  — i  ,  ++vl  ,  p=v2  ) 
for(  j=n  ;  j  ;  — j  ) 

*m++  =  *vl  *  *p++  ; 


/*- 


matvec (  n  ,  m  ,  vl  ,  v2  ) 

int  n  ; 

double  *m  ; 

double  *vl  ; 

double  *v2  ; 

( 

/* 

*  product  of  an  n  by  n  matrix  and  a  column  vector  with  n  components 

*  yielding  a  second  n  component  vector:  m  *  vl  =  v2 
*/ 

int  i  ,  j  ; 

double  *p  ; 


} 


for  (  i=n  ,  p=vl  ;  i  ;  — i  ,  ++v2  ,  p=vl  ) 
for  (  j=n  ,  *v2=0.0  ;  j  ;  — j  ) 

*v2  +=  *m+  +  *  *p++  ; 


End  Listing  Six 


LISTING  SEVEN 


/*  READ . C 


*  reads  standard  input  to  get  appropriate  parameters 

*  echoes  the  data  as  it  is  read 

*  (c)  Copyright  1985,  Billybob  Software.  All  rights  reserved. 

*  This  program  may  be  reproduced  for  personal,  non-profit  use  only. 
*/ 


tinclude 
#def ine 
#def ine 
#def ine 
#def ine 


"global . h" 
LEN 

MAXKEY 

DEBUGON 

LF 


130 

19 

if  (*debug) 
putchar ( * \n  * ) 


/************** 


reader  (  fun  ,  const  ,  nparam  ,  param  ,  limit  ,  dstep  ,  pname  , 

epsilon  ,  itermin  ,  iterlim  ,  nreset  ,  gO  ,  debug  , 
data  ,  npoints  ,  npmax  ,  method  ) 


int 

*fun  ; 

/» 

address  of  function  (non-portable) 

*/ 

double 

const  [  ]  ; 

/* 

values  of  constants  used  in  fen 

*/ 

int 

♦nparam  ; 

/* 

number  of  parameters  to  be  found  by  fitting 

*/ 

double 

param [ ]  ; 

/* 

starting  values  of  parameters 

*/ 

BOUND 

limit []  ; 

/* 

on-off  flag,  upper  and  lower  limits 

*/ 

double 

dstep [ ]  ; 

/* 

step  sizes  used  to  calculate  derivatives 

*/ 

char 

*pname [ ]  ; 

/* 

parameter  names 

*/ 

double 

epsilon [ ]  ; 

/* 

vector  of  stopping  criteria  for  iteration 

*/ 

int 

*itermin  ; 

/* 

minimum  number  of  iterations  required 

*/ 

int 

*iterlim  ; 

/* 

maximum  number  of  iterations  allowed 

*/ 

int 

♦nreset  ; 

/* 

#  of  iters  to  reset  y  matrix 

*/ 

double 

*g0; 

/* 

expected  value  of  minimum 

*/ 

int 

* debug  ; 

/* 

debug  mode 

*/ 

DATA 

data [ ]  ; 

/* 

data  from  input  file 

*/ 

int 

*npoints  ; 

/* 

number  of  data  points 

*/ 

(continued  on  page  98) 
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_ METRIC  MINIMIZED 

LISTING  SEVEN  (Listing  continued) 


npmax  ; 
♦method  ; 


int  neon 
char  inst 
char  *res 
char  *fir 
static  char 
static  char 


/*  maximum  number  of  data  points  allowed 
/*  dfp  or  bfgs  updating  method 

;  /*  number  of  constants  used  in  fen 


nconst  ;  /*  ni 

instring [LEN]  ; 
♦restofline  ; 
♦firstword  ; 
char  funname[]  = 
char  *key [MAXKEY] 


"bfgs"  , 

/* 

0 

*/ 

"constants"  , 

/* 

1 

*/ 

"debug"  , 

/* 

2 

*/ 

"derivsteps"  , 

/* 

3 

*/ 

"dfp"  , 

/* 

4 

*/ 

"end"  , 

/* 

5 

*/ 

"epsilons"  , 

/* 

6 

*/ 

"exmin"  , 

/* 

7 

*/ 

"funname"  , 

/* 

8 

*/ 

"iterlim"  , 

/* 

9 

*/ 

"itermin"  , 

/* 

10 

*/ 

"limit flags"  , 

/* 

11 

*/ 

"lowerlimits"  , 

/* 

12 

*/ 

"newdata"  , 

/* 

13 

*/ 

"next"  , 

/* 

14 

*/ 

"pstart"  , 

/* 

15 

*/ 

"reset"  , 

/* 

16 

*/ 

"sd"  , 

/* 

17 

*/ 

"upperlimits" 

/* 

18 

*/ 

*  note  above  order;  keywords  are  tested  below  in  same  order. 

*  remember  this  when  adding  keywords! 

*/ 

int  i  ,  j  ,  nemd  ,  ncom  ,  bad  ; 

iifdef  C80 

int  chan  ; 

#else 

FILE  *chan  ; 

FILE  *fopen ( )  ; 
char  *fgets()  ; 

tendif 


loop  until  a  "next"  or  "end"  command  is  picked  up 


nemd  =  ncom  =  bad  =  0  ; 
for  (;;) 

< 


#ifdef  C80 


if  (  !  getline(  instring  ,  LEN  )  ) 
return (  ALLDONE  )  ; 

printf ( "%s\n",  instring)  ; 


*  C-80  library  routine  getline  returns  the  line  stored  into 

*  "instring"  with  the  null  at  the  end,  but  with  the  '\n' 

*  stripped  off. 


if  (fgets(  instring  ,  LEN  ,  stdin  )  ==  NULL) 
return (ALLDONE) ; 


printf ("%s",  instring) 


restofline  =  instring  ; 

getnext (  &restofline  ,  fifirstword  )  ; 
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/*  bfgs 


/*  constants 


/*  debug 


for  (  j=0  ;  j<MAXKEY  ;  ++j  ) 

if  (  !  strcmp(  firstword  ,  key[j]  )  ) 
break  ; 


switch  (j) 

{ 

*/ 

case  0: 

++ncmd  ; 

DEBUGON  printf ("bfgs  update  requested\n" )  ; 
*method  =  BFGS  ; 
break  ; 

*/ 

case  1: 

++ncmd  ; 

DEBUGON  printf ("%d  constants  in  %s:\n",  nconst  , 
funname  ) ; 

for  (i=0  ;  i  <  nconst  ;  ++i) 

{ 

getnext (  firestofline  ,  &firstword  )  ; 
if(  check (  firstword  )  ) 

{ 

++bad; 

break; 

} 

const [i]  =  (double)  atof  (  firstword  )  ; 
DEBUGON  printf ("%e  ",  const [i]); 

) 

DEBUGON  LF; 
break  ; 

*/ 

case  2 : 

++ncmd  ; 

getnext (  irestofline  ,  fifirstword  )  ; 
if  (  check (  firstword  )  ) 

( 
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_ METRIC  MINIMIZER 

LISTING  SEVEN  (Listing  continued) 


♦debug  =  atoi (  firstword  )  ; 

DEBUGON  printf ("debug  level  is  %d\n",  *debug) ; 
break  ; 


/*  derivsteps  */ 

case  3: 


+  +  ncmd  ; 

DEBUGON  printf ("derivsteps  are:\n"); 
for  (i=0  ;  i  <  *nparam  ;  ++i) 

{ 

getnext (  irestofline  ,  &firstword  )  ; 
if  {  check (  firstword  )  ) 

{ 

++bad; 

break; 

} 

dstep[i]  =  (double)  atof (  firstword  ) 
DEBUGON  printf ("%e  ",  dstep[i]); 

} 

DEBUGON  LF; 
break  ; 


++ncmd  ; 

DEBUGON  printf ("dfp  update  requested\n")  ; 
♦method  =  DFP  ; 
break  ; 


DEBUGON  printf ("end  of  all  data\n")  ; 
return (  ALLDONE  )  ; 


/*  epsilons  */ 

case  6: 


/*  funname 


++ncmd  ; 

DEBUGON  printf ("%d  epsilons  for  cutoffs: \n", 

NEPS  ) ; 

for  (i=0  ;  i  <  NEPS  ;  ++i) 

{ 

getnext (  srestofline  ,  sfirstword  )  ; 
if  (  check (  firstword  )  ) 

{ 

++bad; 

break; 

) 

epsilon [i]  =  (double)  atof  (  firstword  ); 
DEBUGON  printf ("%e  ",  epsilon [i]); 

) 

DEBUGON  LF; 
break  ; 


++ncmd  ; 

getnext (  &restofline  ,  Sfirstword  )  ; 
if  (  check (  firstword  )  ) 


*g0  =  (double)  atof (  firstword  )  ; 

DEBUGON  printf ("expected  minimum  is  %11.4e\n",  *g0) ; 
break  ; 


++ncmd  ; 

getnext (  &restofline  ,  Sfirstword  )  ; 

if(  check (  firstword  )  ) 

{ 

++bad; 


strcpy(  funname  ,  firstword  )  ; 

DEBUGON  printf ("function  to  minimize  is  %s\n'\ 

funname  )  ; 


(continued  on  page  102) 
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_ METRIC  MINIMIZER 

LISTING  SEVEN  (Listing  continued) 


if  (  funlib(  f unname,  fun,  nparam,  &nconst,  pname) ) 

{ 

DEBUGON  print f ("function  not  in  library ! \n" )  ; 
++bad  ; 

} 

break  ; 

/*  iterlim  */ 

case  9: 

++ncmd  ; 

getnext (  &restofline  ,  &firstword  )  ; 
if(  check (  firstword  )) 

( 

++bad; 

break; 

} 

*iterlim  -  atoi (  firstword  )  ; 

DEBUGON  printf ("iterlim  is  %d\n",  *iterlim) ; 
break  ; 

/*  itermin  */ 

case  10: 

++ncmd  ; 

getnext (  irestofline  ,  Sfirstword  )  ; 
if(  check (  firstword  )  ) 

{ 

++bad; 

break; 


) 

♦itermin  -  atoi{  firstword  )  ; 

DEBUGON  printf ("itermin  is  %d\n",  *itermin) ; 
break  ; 

/*  limitflags  */ 

case  11: 

++ncmd  ; 

DEBUGON  printf ("limitflags  are:\n")  ; 
for  (i=0  ;  i  <  *nparam  ;  ++i) 

( 

getnext (  &restofline  ,  ifirstword  )  ; 
if  (  check (  firstword  )  ) 

( 

++bad; 

break; 

} 

limit [ i ) . f 1  -  atoi  (  firstword  )  ; 
DEBUGON  printf ("%d  ",  limit ( i ]. fl) ; 

) 

DEBUGON  LF; 
break  ; 

/*  lowerlimits  */ 

case  12: 

++ncmd  ; 

DEBUGON  printf ("lowerlimits  are:\n")  ; 
for  (i=0  ;  i  <  *nparam  ;  ++i) 

{ 

getnext  (  firestofline  ,  ifirstword  )  ; 
if  (  check (  firstword  )  ) 

( 

++bad; 

break; 


) 

limit (ij.lo  =  (double)  atof (  firstword  )  ; 
DEBUGON  printf ("%e  ",  limit ( i ]. lo) ; 

} 

DEBUGON  LF; 
break  ; 


/*  newdata  */ 

case  13: 

++ncmd  ; 

getnext (  firestofline  ,  fifirstword  )  ; 

DEBUGON  print f ("datafile  requested  was  %s\n"  , 

firstword  )  ; 

if  (  check (  firstword  )  ) 

( 

++bad; 

break; 


Dr.  Dobb's  Journal,  April  1986 


102 

289 


) 

chan  =  f open (  firstword  ,  "r") ; 

if  (  !chan  ) 

{ 

print f  ("datafile  can't  be  opened!\n")  ; 
return (  ALLDONE  )  ; 

) 

fscanf(  chan  ,  "%d"  ,  npoints  )  ; 

DEBUGON  printf("%d  datapoints  in  file\n",  *npoints) ; 

if  (*npoints  >  npmax) 

++bad  ; 

printfC'more  data  than  allowed!  \n")  ; 
printf("%d  datapoints  in  file\n",  *npoints) ; 
printf("%d  points  allowed  for\n",  npmax  )  ; 
break  ; 

for  (i=0  ;  i<*npoints  ;  ++i) 

#ifdef  C80 

fscanf(chan,  "%f  %f",  Sdata[i].x,  sdata[i].y); 

#else 

f scanf (chan, "»lf  %lf ", tdata [i] . x,  sdata(il.y); 

#endif 

DEBUGON  printf ("%3d  %£\n"  ,  i+1  , 

data[i].x  ,  data[i).y  )  ; 

f close (  chan  )  ; 
break  ; 

/*  next 

*/ 

case  14: 

++ncmd  ; 
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_ METRIC  MINIMIZER 

LISTING  SEVEN  (Listing  continued) 


DEBUGON  printf ("end  of  this  data  set\n"); 
printf(”%2d  command  lines  read\n",  ncmd)  ; 
printf("%2d  comment  lines  read\n",  ncom)  ; 

if(  !  *nparam  ) 

++bad  ; 

return (  bad  )  ; 

/*  pstart  */ 

case  15: 

++ncmd  ; 

DEBUGON  printf ("starting  values  are:\n"  )  ; 
for  (i=0  ;  i  <  *nparam  ;  ++i) 

{ 

getnext (  firestofline  ,  fifirstword  )  ; 
if  (  check (  firstword  )  ) 

{ 

++bad; 

break; 

} 

param[i]  -  (double)  atof (  firstword  )  ; 

DEBUGON  printf ("%e  ",  param(ij); 

) 

DEBUGON  LF; 
break  ; 

/*  reset  */ 

case  16: 

++ncmd  ; 

getnext (  &restofline  ,  &firstword  )  ; 
if  (  check (  firstword  )  ) 

{ 

++bad; 

break; 

) 

*nreset  =  atoi (  firstword  )  ; 

DEBUGON  printf ("reset  is  %d\n",  *nreset) ; 
break  ; 

/*  sd  */ 

case  17: 

++ncmd  ; 

DEBUGON  print f ("steepest  descent  update  requested\n" )  ; 

♦method  =  STDES  ; 
break  ; 

/*  upperlimits  */ 

case  18: 

++ncmd  ; 

DEBUGON  printf ("upperlimits  are:\n") ; 
for  (i=0  ;  i  <  *nparam  ;  ++i) 

{ 

getnext  (  &restofline  ,  fifirstword  )  ; 
if  (  check (  firstword  )  ) 

{ 

++bad; 

break; 

) 

limit [i]. up  =  (double)  atof(  firstword  )  ; 

DEBUGON  printf ("%e  ",  limit (i) .up) ; 

) 

DEBUGON  LF; 
break  ; 

/* 

*  anything  else  is  a  comment;  throw  away  and  go 

*  to  next  line. 

*/ 


} 

} 

y********* 


default : 

++ncom  ; 

DEBUGON  printf ("***%s*** 


} 


taken  as  commencXn", 
firstword  )  ; 


*/ 


(continued  on  page  106) 
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_ METRIC  MINIMIZER 

LISTING  SEVEN  (Listing  continued) 


getnext {  string  ,  next  ) 
char  **string  ; 
char  **next  ; 

{ 

/* 

*  splits  the  input  string  "string"  into  two  pieces: 

*  "next"  contains  the  first  word  with  no  leading  or  trailing  blanks 


*  1 

'string"  then 

contains  the  rest  of  the  line 

*/ 

int 

length  ; 

char 

*p  ; 

length 

=  strlen(  p  - 

!  *string  )  ; 

while ( 

length —  >  0 

&&  isspace(  *p++  )  ) 

♦next  = 

!  — p  ; 

while!  length —  >=  0  &&  !isspace(  *  ++p  )  ) 


*p  =  '\0*  ; 

♦string  =  ++p  ; 

} 

/★if***********************************************************************/ 


check (  string  ) 
char  *string  ; 

{ 

/* 

*  checks  if  a  string  starts  with  a  blank 

*  if  the  string  was  obtained  with  getnext,  this  means  the  string 

*  is  blank  unconditionally  report  this  error 
*/ 


if  (  !  *string  ) 

{ 

print f ( "Unexpected  blank  encountered ! \n")  ; 
return (  1  )  ; 

} 

else 


LISTING  EIGHT 


Test  input  for  the  VMM  program 
File  name  is  "al.dat" 

Sample  input  using  the  Cohen  function 

Demonstrates  using  the  limit  flags  and  detail  debug  printout 


funname 

cohen 

pstart 

1.0 

1.0 

limit  flags 

1 

1 

lowerlimits 

0.5 

0.75 

upperlimits 

2.0 

3.0 

iterlim 

10 

debug 

2 

next 

This  case  tests  a  function  which  uses  "experimental" 

Note  the  non- 

default 

epsilons  for  this  case 

funname 

sine 

pstart 

1.57 

-0.65  0.08  -0.005 

epsilons 

1.0e-14 1.0e-6 

newdata 

b : sine 

.  dat 

iterlim 

12 

reset 

8 

debug 

1 

next 

The  following 

cases  use  the  Rosenbrock  function 

These  correspond  to  the  benchmarks... 

Case  1 

funname  rosen 

pstart  -1.2 

1.0  -1 

.2  1.0  -1.2  1.0  -1.2  1.0  -: 

1.0 


constants  100.  100.  100.  100.  100. 


End  Listing  Seven 
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-1.2  1.0  -1.2  1.0 


-1.2  1.0 


1.2  0.8  1.2 

100.  100. 


0.8  1.2  0.8 


8  1.2  0.8  1.2  0.8 


1.2  0.8  1.2  0.8  1.2  0.8 


1.0 

100. 


-1.2  1.0 


-1.2  1.0 


sd 
next 
Case  2 

f unname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1,2  1.0 

constants  10.  10.  10.  10.  10. 

sd 
next 
Case  3 

f unname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1.2  1.0 

constants  1.  1.  1.  1.  1. 

sd 
next 
Case  4 

f unname  rosen 

pstart  1.2  0.8  1.2  0.8 

constants  100.  100.  -100. 

sd 
next 
Case  5 

f unname  rosen 

pstart  1.2  0.8  1.2  0.8  1.2  0. 

constants  10.  10.  10.  10.  10. 

sd 

next 
Case  6 

f unname rosen 

pstart  1.2  0.8  1.2  0.8 

constants  1.  1.  1.  1.  1. 

sd 
next 
Case  7 

f unname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1.2 

constants  100.  100.  100.  100. 

dfp 

reset  5 
next 
Case  8 

f unname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1.2 
constants  10.  10.  10.  10.  10. 

dfp 

reset  5 
next 
Case  9 

f unname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1.2 
constants  1.  1.  1.  1.  1. 

dfp 

reset  5 
next 
Case  10 
f unname  rosen 

pstart  1.2  0.8  1.2  0.8 

constants  100.  100.  100. 

dfp 

reset  5 
next 
Case  11 
f unname rosen 

pstart  1.2  0.8  1.2  0.8  1 

constants  10.  10.  10.  10. 

dfp 

reset  5 
next 
Case  12 
f unname  rosen 

pstart  1.2  0.8  1.2  0.8  1.2 

constants  1.  1.  1.  1.  1. 

dfp 

reset  5 
next 
Case  13 
f unname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1.2  1.0  -1.2  1.0  -1.2  1.0 

constants  100.  100.  100.  100.  100. 

bfgs 

reset  5 
next 


-1.2  1.0 


-1.2  1.0 


1.0  -1.2  1.0  -1.2  1.0 


1.2  0.8  1.2 

100.  100. 


0.8  1.2  0.8 


.2  0. 
10. 


8  1.2  0.8  1.2  0.8 


0.8  1.2  0.8  1.2  0.8 
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LISTING  EIGHT  (Listing  continued) 


Case  14 
funname  rosen 

pstart  -1.2  1.0  -1.2  1.0  -1.2  1.0  -1.2  1.0  -1.2  1.0 

constants  10.  10.  10.  10.  10. 

bfgs 

reset  5 
next 
Case  15 
funname  rosen • 

pstart  -1.2  1.0  -1.2  1.0  -1.2  1.0  -1.2  1.0  -1.2  1.0 

constants  1.  1.  1.  1.  1. 

bfgs 

reset  5 
next 
Case  16 
funname  rosen 

pstart  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8 

constants  100.  100.  100.  100.  100. 

bfgs 

reset  5 
next 
Case  17 
funname  rosen 

pstart  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8 

constants  10.  10.  10.  10.  10. 

bfgs 

reset  5 
next 
Case  18 
funname  rosen 

pstart  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8 

constants  1.  1.  1.  1.  1. 

bfgs 

reset  5 

next 

end 

ame  rosen 

pstart  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8  1.2  0.8 

constants  1.  1.  1.  1.  1. 

bfgs 

reset  End  Listing  Eight 

LISTING  NINE 

/*  Listing  9 

*  The  way  it  is  done  in  vmm 

*  This  works  and  will  be  portable 

*  so  long  as  addresses  are  the 

*  same  size  as  ints. 

*  Fine  on  16  bit  systems  with  "small 

*  model"  e.g.  64K  programs 
*/ 


Idefine  double  float 

tinclude  "fprintf.h" 

#include  "scanf.h" 

/* - */ 

main ( ) 

{ 


double  *  (*fun)  ()  ; 
double  a  ,  b  ; 

while  (1)  { 

readit (  4fun  ,  4a  ,  4b  )  ; 

doit (  fun  ,  a  ,  b  )  ; 

} 

} 

/* - */ 

readit (  fun  ,  a  ,  b  ) 
int  *fun  ; 
double  *a  ; 
double  *b  ; 

{ 

char  string [10]  ; 
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scanf("%s  %f  %f",  string  ,  a  ,  b  )  ; 


funlib(  fun  ,  string  )  ; 

} 

/* - */ 

f unlib (  fun  ,  string  ) 
int  *fun  ; 
char  string!]  ; 

{ 

double  sum()  ; 
double  mul()  ; 


if  (  !strcmp(  string,  "add"  )  )  *fun  =  sum  ; 
else  if  (  !strcmp(  string,  "mul"  )  )  *fun  =  mul  ; 
else  exit  (0) ; 

} 

/* - */ 

doit (  fun  ,  a  ,  b  ) 
double  (*fun)  ()  ; 
double  a  ; 
double  b  ; 

{ 

double  g  ; 

g  =  (*fun) (  a  ,  b  )  ; 

printf("%f  is  the  result\n"  ,  g  )  ; 

} 

/* - */ 

double  sum(  a  ,  b  ) 
double  a  ; 
double  b  ; 

{ 

printf("%f  +  %f  =  %f\n"  ,  a  ,  b  ,  a+b  )  ; 
return!  a  +  b  )  ; 


} 

/* - */ 

double  mul(  a  ,  b  ) 
double  a  ; 
double  b  ; 

{ 

printf("%f  *  %f  =■  %f\n"  ,  a  ,  b  ,  a*b  ) 
return (  a  *  b  )  ; 

} 

LISTING  TEN 


End  Listing  (Vine 


/*  Listing  10 

*  The  correct  and  most  portable  way  to  pass  an  object  which  is  a 

*  pointer  to  a  function 
*/ 


tinclude  <stdio.h> 

/* - 

main  ( ) 

{ 

double  (*fun)  ()  ; 


double  (*readit () ) () 


double  a  ,  b  ; 


*/ 


/*  fun  is  a  pointer  to  a  function 

*  which  returns  a  double 
*/ 

/*  readit  is  a  function  that 

*  returns  a  pointer  to  a  function 

*  that  returns  a  double 
*/ 


whiled)  { 

fun  =  readit(  &a  ,  £b  )  ; 
doit (  fun  ,  a  ,  b  )  ; 

) 

} 


/ 


*/ 


double  (*readit(  a  ,  b  )) () 
double  *a  ; 
double  *b  ; 

{ 

double  (*fun)  ()  ; 
double  (*funlib () ) () 


/*  note  position  of  arguments  */ 


/*  funlib  is  a  function  which 

*  returns  a  pointer  to  a  function 

*  which  returns  a  double 
*/ 

(continued  on  nejtt  page) 
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METR  C  MINIMIZER 


LISTING  TEN  (Listing  continued) 


char  string [10]  ; 

scanf ("%s  %lf  %lf"/  string  ,  a  ,  b  ) 

fun  =  funlib(  string  )  ; 
return (  fun  )  ; 


double  (*funlib(  string  ))  ()  /*  note  position  of  arguments 
char  string  []  ; 

{ 

double  (*fun)  ()  ; 
double  sum()  ; 
double  mul()  ; 

if  (  !strcmp(  string,  "add"  )  ) 
fun  =  sum  ; 

else  if  (  !strcmp(  string,  "mul"  )  ) 
fun  =  mul  ; 

else 

exit (0) ; 
return  (  fun  )  ; 


/* - */ 

doit {  fun  ,  a  ,  b  ) 
double  (*fun)  ()  ; 
double  a  ; 
double  b  ; 

{ 

double  g  ; 

g  =  (*fun)  (  a  ,  b  )  ; 

printf("%f  is  the  result\n"  ,  g  )  ; 

} 

/* - */ 

double  sum(  a  ,  b  ) 
double  a  ; 
double  b  ; 

{ 

printf("%f  +  %f  =  %f\n"  ,  a  ,  b  ,  a+b  ) 
return (  a  +  b  )  ; 

} 

/* - */ 

double  mul(  a  ,  b  ) 
double  a  ; 
double  b  ; 

{ 

printf("%f  *  %f  =  %f\n"  ,  a  ,  b  ,  a*b  ) 
return (  a  *  b  )  ; 

} 


End  Listings 
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1 6-BIT 


LISTING  ONE  (Text  begins  on  page  116.) 


SQRT 

;  Returns  square 

root  of  DO  in  DO. 

stosb 

store  high  digit 

;  Uses  algorithm 

from  April  85  EDN 

cld 

restore  direction  flag 

ret 

•back  to  caller 

MOVEM.L 

D1-D2,- (A7) 

byte_to_dec  endp 

MOVE.L 

#40000000H,D2  / 

set  largest  guess 

BRA.S 

START 

enter  sizing  loop 

SIZE 

LSR.L 

2,  D2 

divide  guess  by  4 

START 

CMP.L 

D2,  DO 

/ 

BCS 

SIZE 

branch  if  guess  is  greater 

;  variation  2,  handles  arguments 

0-99 

MOVE.L 

D2,D1 

else  set  root  to  guess 

; 

SUB.L 

D2,  DO 

subtract  guess 

byte  to  dec  proc  near 

call  with  AL  =  value  to  convert 

LSR.L 

2,  D2 

divide  guess  by  4 

Dl  =  addr  for  string 

LOOP 

then  do  normal  square  root 

aam 

convert  to  two  digits 

SUB.L 

D1,D0 

subtract  current  root  value 

or  ax, '00' 

make  them  ASCII 

SUB.L 

D2,D0 

and  guess 

xchg  ah,al 

BMI.S 

NEG 

jump  if  <  0 

stosb 

store  middle  digit 

LSR.L 

1,D1 

divide  root  by  2 

mov  al,ah 

ADD.L 

D2,D1 

add  guess  to  root 

stosb 

•store  high  digit 

BRA.S 

NEXT 

ret 

;back  to  caller 

NEG 

ADD.L 

ADD.L 

D2,D0  ; 

Dl,  DO 

if  negative  then  guess 

is  too  large 

add  guess  back  in 

byte  to  dec  endp 

End  Listing  Three 

LSR.L 

1,D1 

divide  root  by  2 

NEXT 

LSR.L 

2,  D2 

divide  guess  by  4 

BNE 

LOOP 

done  when  =  0 

MOVE.L 

MOVEM.L 

Dl,  DO 

(A7)+,D1-D2 

get  root 

restore  registers 

LISTING  FOUR 

RTS 

and  end 

End  Listing  One 

/* 

LISTING  TWO 


TAIL . C  A  utility  to  dump  the  last  <n>  lines  of  a  file 
to  the  Standard  Output  device  (which  may 
be  redirected  to  a  file  or  printer) . 

Usage  is:  C>TAIL  (  -n  )  uni t: pa th\ filename. ext 


DIV32 

;  Divides  32-bit  number  in  D1  by  32-bit  number  in  DO. 
;  Both  numbers  must  be  positive,  and  DO  must  be 
;  greater  than  65535. 

;  Returns  32-bit  quotient  in  Dl,  remainder  in  DO. 


MOVEM.L 

MOVEQ 

SWAP 

MOVE 

CLR.W 


MOVEQ 

LOOP 

ADD.L 

ADDX.L 

CMP.L 

BCC.S 

SUB.L 

SUB.L 

ADDQ 

COUNT 

DBRA 

MOVE.L 

MOVEM.L 

RTS 


D2-D3,-(A7) 
0,  D2 
D1 

DlfD2 

D1 


15,  D3 

D1,D1 

D2,D2 

D0,D2 

COUNT 

D0,D2 

D0,D2 

1,D1 

D3, LOOP 
D2,  DO 

(A7)+,D2-D3 


save  scratch  registers 
clear  remainder  register 

hi  dividend  to  D2 

clear  quotient  register 

D1  low  half  is  quotient,  hi  half 

is  low  part  of  dividend 

set  counter 

divide  loop 

shift  quotient  and  shift  next 
bit  of  dividend  to  Carry 
shift  remainder 
remainder  <  divisor? 
jump  if  so,  else  subtract 
divisor  from  remainder 

and  set  bit  in  quotient 
decrement  counter 
and  loop 
remainder  to  DO 
restore  registers 
and  end 


End  Listing  Two 


LISTING  THREE 


Default  value  for  n  is  5. 

Version  1.0  Nov.  19,  1985 

Copyright  (C)  1985  Norman  McIntosh 

May  be  freely  reproduced  for  non-commercial  use. 

To  compile  with  Microsoft  C: 

OMSC  TAIL; 

OLINK  TAIL; 


*/ 


♦include  <stdio.h> 
♦  include  <  f cntl . h> 


♦define  REC_SIZE  12b 

main(  argc,  argv  ) 
int  argc; 
char  *argv[]; 

(  int  handle, 

lines, 

bytes_read; 

long  file_ptr, 

backup  () , 


lseek  ( ) ; 


/*  size  of  input  file  records  */ 


/*  handle  for  input  file  */ 
/*  Number  of  lines  from  end 
to  print.  */ 


/*  file  byte  offset,  current  rec  */ 
/*  Function  to  backup  the 

specified  number  of 

records.  */ 


char  file_buf[  REC_SIZE+1  ];  /*  data  block  from  file  */ 

/*  Abort  if  no  filename  supplied,  or  more  than  2  parameters.  */ 


if  (  argc  <2  I  I  argc  >  3  ) 

(  fprintf(  stderr,  "\nUsage  :  tail  [-n]  <file  name>\n"  ); 
return  1; 

) 


lines  -5; 


/*  Set  default  number  of 

lines.  */ 


;  variation  1, 

handles 

arguments  0-255 

byte  to  dec  proc  near 

;call  with  AL  =  value  to  convert 

;  DI  =  addr  for  string 

add 

di,  2 

; point  to  low  digit 

std 

,*set  for  high  to  low  store 

aam 

/convert  low  order  digit 

or 

al,  'O' 

/make  it  ASCII 

stosb 

/and  store  low  digit 

mov 

al,ah 

/load  high  part 

aam 

/convert  high  and  middle  digit 

or 

ax, ' 00 

'  /make  them  ASCII 

stosb 

/store  middle  digit 

mov 

al,ah 

argv++;  /*  Past  program  name .  */ 

if  (  **argv  —  )  /*  check  for  lines  option.  */ 

{  lines  -  atoi(  *argv  +  1  ); 
argv++; 

) 

/*  Open  specified  file  in  raw  mode,  abort  if  open  fails  */ 

if  (  (  handle  -  open (  *argv,  0_BINARY  |  O  RDWR  )  )  —  -1  ) 

{  fprintf(  stderr,  "\ntail:  can't  find  file:  %s  \n",  *argv  ), 
return  1; 

) 

/*  Print  filename  and  number  of  lines  to  print.  */ 
printf(  "\nTail  of  file:  %s  for  %d  lines",  *argv,  lines  ); 
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/*  Set  starting  offset  into  the  file.  */ 
file_ptr  -  backupt  handle,  lines  ); 

/*  Seek  to  the  specified  position.  */ 
if  (  lseek(  handle,  file_ptr,  0  )  —  -1L  ) 

{  fprintf (stderr,  "\ntail :  can't  seek  to  end:  %s  \n",*argv); 
return  1; 

} 

/*  Read  and  print  until  the  end  of  file.  */ 

while ( (bytes_read-read (  handle,  file_buf,  REC_SIZE  ))  >0) 

{  /*  Force  a  null  on  the  end  of  the  string.  */ 

file_buf[  bytes  read  ]  -  ' \0 1 ; 
printf(  "%s",  frie_buf  ); 

} 

close (  handle  );  /*  close  the  input  file  */ 

return  0;  /*  return  success  code  */ 


) 


/* 

Backup  the  specified  number  of  records  or  until  the 
beginning  of  the  file.  Return  the  offset  (a  long) 
into  the  file  of  where  that  record  begins. 


static  long  backupt  handle,  recs  ) 
int  handle,  /* 

recs;  /* 


long 

filejptr. 

/* 

rslt. 

/* 

lseek ( )  ; 

char 

file  buf [REC  SIZE], 

/* 

*p; 

/* 

int 

n; 

/* 

Handle  to  the  input  file.  */ 
Number  of  records  to  backup.  */ 
Pointer  to  current  record.  */ 
Return  from  seek.  */ 

data  block  from  file  */ 

Pointer  into  file_buf.  */ 
Counter.  */ 


/*  Seek  to  the  end  of  the  file.  */ 


file_ptr  -  lseekt  handle,  0L,  2  ); 
if  (  file_ptr  - - 1L  ) 

{  fprintf (  stderr,  "\ntail:  can't  seek  to  file  end\n"  ); 
exit (  1  ) ; 

} 

/*  Loop  until  we  have  found  the  specified 
number  of  records.  */ 


while {  1  ) 

/*  If  file_ptr  <  REC_SIZE  then  only  backup  to  0, 
otherwise  back  up  a  full  REC_SIZE.  */ 

if  (  filejptr  >  (long) REC_SIZE  ) 
n  -  REC_SIZE; 
else 

n  -  (int) file_ptr; 

filejptr.—  (long)n;  /*  Decrement  position  in  file  */ 

/*  Seek  to  the  desired  position.  */ 

rslt  -  lseek(  handle,  filejptr,  0  ); 
if  (  rslt  —  -1L  ) 

{  fprintf (  stderr,  "\ntail:  can't  seek  to  file  end\n"  ); 
exit (  1  ) ; 

) 

/*  Read  the  record.  */ 


if  (  read (  handle,  file_buf,  n  )  >-  0  ) 

{  /*  Set  pointer  to  end  of  buffer.  */ 

p  -  file_buf; 
p  +-  n; 

/*  While  we  still  have  characters  in  the  buffer, 

look  for  a  return.  If  found  decrement  the  number 
records.  If  the  number  of  records  is  less  than 
zero  then  exit.  */ 


} 


while (  n —  ) 

{  if  (  Mp— )  —  '\n'  ) 
if  (  — recs  <  0  ) 
break; 

} 


/*  If  we  have  found  the  number  of  records  that  we 

desire  or  we  are  at  the  beginning  of  the  file  then 
increment  filejptr  by  the  number  of  characters  left 
in  the  buffer.  */ 


if  (  recs  <0  ||  filejptr  —  0L  ) 

{  filejptr  +-  n  +  1; 
break; 

) 

> 

return  filejptr;  /*  offset  in  the  file  */ 


End  Listings 
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COLUMNS 


16-BIT  SOFTWARE  TOOLBOX 


VDISK  Bites  Back 

recently  had  another  painful  les¬ 
son  concerning  how  much  faith  to 
put  in  IBM  documentation.  My  own 
company's  product  PC/FORTH,  a 
Forth-83  Standard  interpreter/com¬ 
piler  for  IBM  PCs,  PC/ATs,  and  compa¬ 
tibles,  is  unlike  traditional  Forth  sys¬ 
tems  in  that  it  runs  as  a  task  under  DOS 
and  is  carefully  integrated  into  the 
DOS  environment.  My  coworkers  and 
I  spend  a  lot  of  time  poring  over  the 
IBM  technical  manuals  to  ensure  that 
we  maintain  compatibility  across  all 
current  and  future  IBM  models  and  to 
wring  the  maximum  performance 
out  of  the  video  hardware. 

In  the  latest  version  of  PC/FORTH, 
the  video  and  graphics  routines  had 
grown  so  extensive  that  we  decided 
to  factor  them  out  into  a  separate  res¬ 
ident  system  driver  that  would  com¬ 
municate  with  PC/FORTH  through  a 
software  interrupt.  Because  all  the 
IBM  technical  manuals  stated  that  in¬ 
terrupts  OFOH  through  OFFH  were  not 
used,  we  picked  interrupt  OFFH  for 
our  PC/FORTH  message  passing  and 
went  on  to  other  problems. 

After  somewhat  more  than  a  thou¬ 
sand  copies  of  this  version  were  in  use 
in  the  field,  we  began  to  get  some 
strange  reports  of  horrible  crashes 
when  PC/FORTH  was  used  on  a  PC/AT 
with  IBM's  VDISK  installable  RAM  disk 
driver.  This  problem  was  completely 
perplexing  to  us,  because  PC/FORTH 
does  all  of  its  file-and-record  I/O 
through  normal  DOS  calls,  and  one  log¬ 
ical  disk  unit  looks  just  like  another. 

The  idea  of  trying  to  find  the  prob¬ 
lem  in  VDISK  was  intimidating.  VDISK 
is  a  large  chunk  of  code  that  is  even 
more  obscure  than  is  usual  for  IBM, 
and  it  makes  several  calls  on  PC/AT 
ROM  BIOS  routines  that  are  both  con- 


by  Ray  Duncan 

voluted  and  fragmented. 

When  an  application  program 
running  under  PC  DOS  in  the  80286's 
Real  Mode  accesses  a  file  on  the  VDISK 


RAM  disk,  the  request  filters  down 
through  the  DOS  kernel  in  the  usual 
way.  It  is  translated  into  logical  sec¬ 
tor  addresses  by  inspection  of  the 
RAM  disk’s  file  allocation  table  and  di¬ 
rectory  and  is  then  passed  as  logical 
sector  transfer  requests  to  the  VDISK 
device  driver. 

In  order  for  VDISK  to  access  a  logi¬ 
cal  sector  in  the  VDISK  extended 
memory  it  sets  up  some  descriptor 
tables,  stuffs  a  flag  into  the  CMOS  RAM 
area,  and  switches  the  80286  into  Pro¬ 
tected  Mode.  Now,  getting  back  into 
Real  Mode  so  that  VDISK  can  deliver 
the  data  to  the  requesting  program  is 
a  bit  of  a  problem.  The  current  mod¬ 
els  of  the  80286  have  no  provision  for 
returning  to  Real  Mode  because  it 
would  provide  a  means  for  pro¬ 
grams  to  defeat  the  protection  mech¬ 
anisms  altogether. 

Instead,  VDISK  sends  a  special  signal 
to  the  keyboard’s  controller  and  sim¬ 
ply  halts  the  80286  CPU.  The  keyboard 
control  recognizes  the  signal  and 
forces  an  interrupt  of  the  80286,  which 
restarts  it  as  though  it  has  just  been 
turned  on.  The  80286  goes  through  its 
usual  power-up  ROM  sequence,  fid¬ 
dles  around  awhile,  and  finally  in¬ 
spects  the  CMOS  RAM  for  the  VDISK  flag; 
when  it  finds  the  flag,  it  restores  the 
previous  contents  of  the  CPU  registers 
and  transfers  control  back  to  DOS  and 
the  application  program. 

The  fact  that  this  kludge  works  at 
all  is  amazing;  the  fact  that  it  works 
fast  enough  to  be  useful  for  anything 
is  a  tribute  to  the  power  of  the  80286. 

Sadly  enough,  after  tracing  out  and 
marvelling  at  all  this  grotesque  code, 


we  were  no  wiser  about  why  PC/ 
FORTH  was  crashing  when  used  with 
VDISK.  It  took  a  particularly  deter¬ 
mined  user,  armed  with  a  hardware 
debugging  probe  and  lots  of  pa¬ 
tience,  to  discover  the  explanation: 
VDISK  inexplicably  trashes  the  vec¬ 
tors  for  interrupts  0F0H-OFFH  some¬ 
where  in  the  transition  from  Real 
Mode  to  Protected  Mode  and  back 
again.  Even  knowing  what  to  look 
for,  we  haven't  found  the  little  bit  of 
code  in  VDISK  that  does  the  dirty 
work — but  it's  in  there  somewhere! 

LaserJet  and  WordStar 

Some  months  ago  I  discussed  the 
problems  of  getting  WordStar  to 
work  with  the  Hewlett-Packard  La¬ 
serJet  printer.  I  eventually  obtained  a 
new  printer-support  disk  from  Mi¬ 
croPro  that  gave  WordStar  control  of 
the  LaserJet's  italics,  boldface,  and  mi¬ 
crojustification,  but  there  was  still  no 
support  for  the  proportional  fonts 
needed  for  really  high-quality  output. 

I  have  recently  been  blessed  with 
the  following  utility  programs,  from 
two  different  companies,  that  can  be 
used  with  WordStar  document  files 
to  produce  typeset-quality  output  on 
the  LaserJet: 

•  StarJet  2.0  from  Control-C  Software, 
6441  S.W.  Canyon  Court,  Portland, 
OR  97221;  (503)  292-8842.  Price:  $150. 
Requires  45K  RAM  to  execute.  Not 
copy  protected. 

•  Polaris  Printmerge  from  Polaris 
Software,  310  Via  Vera  Cruz,  Ste. 
205,  San  Marcos,  CA  92069;  (619)  471- 
0922.  Price:  $99.  Requires  196K  RAM 
to  execute.  Copy  protected,  but 
non-copy-protected  disk  available 
for  an  additional  $25. 

Polaris  Printmerge  requires  more 
drastic  alterations  to  your  document 
files  and  has  weaker  support  for  co¬ 
lumnar  data  in  the  proportional 
fonts.  But  both  programs  are  easy  to 
use  and  allow  full  access  to  all  the 
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fonts,  proportional  spacing,  and 
right  justification.  They  can  also 
draw  pretty  lines  and  boxes  for  gen¬ 
eration  of  custom  forms. 

Microsoft  Macro 
Assembler 

Microsoft  has  just  released  a  new  ver¬ 
sion  (4.0)  of  its  Macro  Assembler  that 
contains  a  number  of  impressive  im¬ 
provements  over  previous  versions. 
Overall  assembly  speed  has  been  im¬ 
proved  by  a  factor  of  2  to  3,  and  the 
input/output  buffers  and  macro  text 
have  been  moved  out  of  the  symbol 
space,  allowing  assembly  of  larger 
source  files.  Most  of  the  bugs  men- 
)  honed  in  earlier  16-Bit  Toolbox  col¬ 
umns  have  been  fixed,  including  gen¬ 
eration  of  the  correct  opcodes  for  all 
the  special  80286  instructions. 

A  number  of  new  features  have 
been  added,  including  switches  to  set 
the  file  buffer  to  any  size  from  IK  to 
63K,  to  define  a  symbol  from  the 
command  line  to  control  conditional 
assembly  directives,  and  to  check  for 
impure  code  that  would  cause  prob¬ 
lems  in  80286  Protected  Mode. 

The  CREF  (Cross  Reference  Utility), 
LINK  (Object  File  Linker),  SYMDEB 
(Symbolic  Debugger),  and  MAKE  (Pro¬ 
gram  Maintenance  Utility)  utilities 
have  all  been  enhanced,  and  two 
new  utilities  have  been  added.  These 
are  EXEPACK,  which  allows  you  to 
pack  executable  files  by  removing 
repetitive  sequences  of  bytes,  and 
EXEMOD,  which  lets  you  modify  the 
stack  size  or  memory  allocation 
fields  of  an  EXE  file  header. 

The  manual  for  the  new  assembler 
and  its  associated  utilities  is  excellent. 
Information  is  well  indexed  and  easy 
to  find.  The  manual  provides  virtual¬ 
ly  no  guidance  on  8086/80286  pro- 
j  gramming,  however,  so  you  will  still 
need  additional  reference  materials 
such  as  Intel's  iAPX  86  User's  Guide  or 
]  Rector  and  Alexy’s  The  8086  Book. 

68000  Feedback 

|  Lee  Robertson  of  Sandy,  Utah, 
j  writes:  "I  found  [the  68000  routines] 
published  in  the  November  1985  16- 
Bit  Toolbox  column  very  interesting 
and  would  like  to  add  some  sugges¬ 
tions.  First  of  all,  Mike  Morten  sug¬ 
gests  using  ADD  instructions  instead 
of  shifts  in  the  square-root  routine.  I 
agree  this  speeds  things  up,  but  only 
by  half  the  amount  he  states.  An 


ADD.L  instruction  requires  eight  time 
states  instead  of  six. 

“Regarding  the  random-number 
routine  of  November’s  Listing  Four, 
the  following  four  lines  above  label 
DIV2: 

LSL.L  1,D6 
LSL  1,D5 

BCC.S  DIV2 
ADDQ.L  1,D6 

can  all  be  replaced  by  two  ADD  in¬ 
structions  as  follows: 

ADD  D5,D5 
ADDX.L  D6,D6 

j  “Not  only  is  this  shorter  but  it  is 
I  also  much  faster.  These  lines  are  in- 
j  side  the  main  loop,  so  any  improve¬ 
ments  that  can  be  made  here  will 
greatly  affect  the  total  run  time  of 
the  program.  The  loop  is  taken  15 
times,  so  that  the  average  time  sav¬ 
ings  are  300  time  states.  Also,  the  con¬ 
stant  127,773  is  used  twice  inside  the 
main  loop.  If  this  is  placed  in  a  regis¬ 
ter  instead,  it  will  save  another  240 
j  time  states. 

|  “I  have  included  a  square-root  rou¬ 
tine  (Listing  One,  page  114)  that  is  fast¬ 
er  than  the  routines  you  previously 
published.  It  works  on  2  bits  at  a  time, 
starting  with  the  highest  bits  in  the 
number.  It  guesses  the  square  root  of 
2  bits  and  keeps  testing  2  bits  at  a  time 
to  see  if  the  guess  is  too  large  for  the 
number;  if  so,  it  divides  the  guess  by  4 
to  move  to  the  next  2  bits  in  the  num¬ 
ber.  It  repeats  this  process  for  each  2- 
bit  combination  in  a  32-bit  number. 

“The  first  loop  in  the  program  is 
used  to  quickly  scale  the  initial  guess 
down  to  the  size  of  the  input  num¬ 
ber.  This  speeds  things  up  greatly  for 
I  smaller  input  values.  The  time  re- 
I  quired  for  best  case  (input =0)  is  650 
time  states;  the  time  increases  as  the 
input  number  gets  larger  up  to  a 
worst  case  (input  =  0FFFFFFFFH)  of 
1,322  time  states. 

"I  have  also  included  a  listing  for  a 
general-purpose  32-bit  divide  rou¬ 
tine.  (See  Listing  Two,  page  114.)  The 
method  requires  that  the  divisor  be 
greater  than  16  bits  (65,535).  If  the  di¬ 
visor  is  65,535  or  less,  the  68000  hard- 
i  ware  divide  instruction  can  be  used 
instead,  because  it  will  be  quite  a  bit 
faster  even  if  it  has  to  handle  over- 
|  flow  from  the  divide.’’ 


8086  Programming  Pearls  1 

Dan  Daetwyler,  a  veteran  correspon¬ 
dent  of  DDJ,  writes:  "Here  is  a  cute 
method  for  binary-to-decimal  ASCII 
conversion  that  might  prompt  a  few 
readers  to  exploit  the  8086’s  instruc¬ 
tion  set  more.  It  assumes  that  register  - 
AL  contains  the  value  to  be  convert¬ 
ed  and  that  DI  contains  the  address 
where  the  ASCII  characters  should  be 
stored.  The  first  variation  can  handle 
any  value  between  0  and  255  and  al¬ 
ways  returns  three  bytes.  The  sec¬ 
ond  variation  assumes  an  input  value 
between  0  and  99  and  always  returns 
two  bytes.  Many  other  variations  on 
this  theme  are  possible.”  Dan's  rou¬ 
tines  are  in  Listing  Three,  page  114. 

Utility  of  the  Month 

The  16-Bit  Toolbox  just  wouldn't  be 
complete  this  month  without  a  nice 
MS  DOS  utility  and  Norman  McIntosh  1 
was  kind  enough  to  supply  one.  His  j 
program,  named  TAIL,  works  much  j 
like  its  Unix  equivalent  and  will  send  I 
the  last  n  lines  of  the  designated  file  to 
the  standard  output  device  (which 
may  be  redirected  to  the  printer  or  a 
file  or  piped  to  another  filter  pro-  j 
gram). 

The  TAIL  program  is  given  in  List¬ 
ing  Four,  page  114.  Instructions  for  j 
use  of  the  program  may  be  found  at 
the  beginning  of  the  source  code. 

DDJ 

(Listings  begin  on  page  114.) 
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Windows 

More  than  half  of  corpo¬ 
rate  personal  computers 
will  use  Microsoft's  Win¬ 
dows  by  1990,  according  to 
David  Ferris,  chairman  of 
Ferin  Corp.,  a  firm  that 
provides  PC  support  for 
Fortune  1000  companies. 
He  predicts  that  Micro¬ 
soft's  product  will  become 
the  industry  standard  over 
such  competitors  as  IBM’s 
TopView,  Digital  Re¬ 
search’s  GEM,  and  Quarter- 
deck's  DESQview. 

The  power  of  Windows 
is  also  expected  to  increase 
over  the  next  three  to  five 
years  for  the  following 
reasons:  other  software  de¬ 
velopers  will  adapt  their 
products  to  it;  and  hard¬ 
ware  will  improve  to  in¬ 
clude  larger  RAM  memory 
faster  processors,  and  bet¬ 
ter  chip  instruction  sets. 

The  latest  release  of 
Windows  from  Syscom 
Software  allows  program¬ 
mers  to  incorporate  on¬ 
line  help,  pop-up  win¬ 
dows,  and  pull-down 
menus  in  new  or  existing 
applications.  Wings,  the 
Window  Generation  Sys¬ 
tem,  lets  programmers  cre¬ 
ate  windows  and  generate 
the  source  code  for  them 
automatically. 

C  Windows  includes 
modules  for  all  memory 
models  of  Computer  Inno¬ 
vations,  Desmet,  Lattice, 
and  Microsoft  C.  BASIC 
Windows  supports  Digital 
Research  CB-86,  Microsoft 
Compiled  BASIC,  Business 
BASIC  and  Quick  BASIC,  and 
the  IBM  BASIC  Compiler 
and  Business  BASIC  Compil¬ 


er.  C  Windows  and  BASIC 
Windows  are  priced  at 
$99.95.  Wings  sells  for 
$49.95. 

Artificial 

Intelligence 

Multibots  is  a  line  of  elec¬ 
tronic-robotic  experiment 
and  construction  sets  from 
Access  Software.  The  foun¬ 
dation  of  the  product  line 
is  a  master  electronics 
module  that  connects  to 
the  user’s  home  computer. 
This  module  contains  all 
the  necessary  circuits  and 
components  to  allow  the 
computer  to  function  as  a 
sophisticated  control  de¬ 
vice  that  can  take  measure¬ 
ments  and  sense  tempera¬ 
ture,  sound,  light,  and 
other  conditions. 

Multibot  sets  teach  the 
principles  and  theory  of 
computer-controlled  ro¬ 
botics,  facilitate  experi¬ 
ments  and  projects  in 
speech  and  audio  digitiza¬ 
tion  and  playback,  and 
permit  users  to  take  pre¬ 
cise  electronic  measure¬ 
ments  with  software  and 
hardware  that  turns  the 
computer  into  a  sensitive 
digital  voltmeter  and/or  a 
digital  storage  oscilloscope. 
The  sets  can  also  sense 
events  and  preprogram 
events.  The  product  line 
operates  on  the  Commo¬ 
dore  64  and  128  computers. 
Versions  are  expected  for 
Amiga,  Apple,  Atari,  and 
IBM  personal  computers. 

Prolog  V-Plus,  a  Prolog 
interpreter  from  Chalced¬ 
ony  Software,  features 
more  than  100  predefined 
predicates  and  operators, 
double-precision  floating 
point  arithmetic,  standard 
arithmetic  functions  plus 
transcendentals  and  trigo¬ 
nometries,  a  large  memory 
model  (up  to  640K  RAM), 
coresidency  (the  ability  to 
call  other  programs),  and 


addressable  cursor  and 
graphics  functions.  It  also 
adheres  to  the  de  facto 
standard  Edinburgh  syn¬ 
tax  and  provides  interac¬ 
tive  debugging  facilities 
and  memory  manage¬ 
ment.  Prolog  V-Plus  re¬ 
quires  PC  DOS  or  MS  DOS, 
Version  2.1,  and  256K  RAM. 
It  is  available  for  $99.95. 

Version  2  of  ESP  Advisor, 
from  Expert  Systems  Inter¬ 
national,  allows  the  con¬ 
struction  of  knowledge 
bases  of  up  to  approxi¬ 
mately  3,000  rules.  Prolog- 
2,  as  a  compiler  and  inter¬ 
preter,  combines  with  ESP 
Advisor.  The  new  version 
includes  the  ability  to  in¬ 
voke  programs  written  in 
Prolog  during  consulta¬ 
tions  using  an  optional  Pro¬ 
log-2  interpreter,  a  virtual 
knowledge  base  that  al¬ 
lows  very  large  knowledge 
bases  to  be  created,  the  ref¬ 
erencing  of  parameters 
from  within  any  text  item 
displayed,  a  set  of  com¬ 
mands,  and  a  full  on-line 
help  facility.  Version  2  is 
priced  at  $895. 

Human  Edge  Software's 
Certified  Developers’  pro¬ 
gram  is  sponsoring  20  au¬ 
thors  to  develop  expert  sys¬ 
tem  applications  using 
Expert  Edge.  The  Certified 
Developers'  program  is  de¬ 
signed  for  users  who  build 
an  expert  system  applica¬ 
tion  for  resale.  Applications 
under  development  range 
from  a  medical  malpractice 
advisor  that  will  provide 
physicians  with  an  edge 
against  possible  medical 
malpractice  suits  to  an  ex¬ 
pert  telephone  consultant 
that  will  advise  users  on 
how  to  reduce  business 
telephone  expenses  based 
on  a  firm's  usage,  needs, 
and  available  alternatives. 

Communications 

Hyper  Access  is  a  software 


program  from  Hilgraeve 
that  runs  on  PC-compatible 
computers  to  allow  com¬ 
munications  through  mo¬ 
dems  or  cable  with  almost 
any  other  computer.  It  can 
transfer  files  at  rates  of 
more  than  IK  per  second 
and  allows  the  computer 
to  act  as  an  unattended 
host  so  it  can  be  run  from 
any  remote  computer  or 
terminal.  Other  programs, 
DOS  commands,  or  DOS 
macros  can  be  used  while 
on-line.  HyperAccess  is 
available  for  use  with  PC 
DOS  or  MS  DOS  on  IBM  PC, 
PC/XT,  PC/AT,  and  PC-com¬ 
patible  or  Z-100  computers. 

With  Polygon’s  poly- 
Share  product,  personal 
computer  and  VAX/VMS  us¬ 
ers  can  build  a  VAX-based  li¬ 
brary  of  personal  comput¬ 
er  applications.  Text  or 
binary  file  entries  can  be 
checked  into  and  out  of  the 
poly-Share  library.  The 
program  features  entries 
organized  by  site-specified 
category  a  menu-interface 
and  automatic  PC  transfers, 
multiple  libraries,  cross-in¬ 
dexing,  and  free-form  li¬ 
brary  searches.  poly-Share 
uses  Polygon's  poly-XFR  file 
transfer  software  on  the 
host  VAX  system  and  either 
poly-COM,  poly-COM/220, 
or  poly-COM/240  terminal 
emulation  and  file  transfer 
products  on  the  personal 
computer. 

A  software-based  net¬ 
working  system  for  com¬ 
puters  based  on  the  68000 
and  6809  processor  fam¬ 
ilies,  the  OS-9  from 
Microware  Systems,  com¬ 
bines  the  file  and  input/ 
output  systems  of  all  con¬ 
nected  computers  into  one 
file  system.  Any  network 
user  can  access  files  and 
I/O  devices  directly  on  any 
other  system  on  the  net¬ 
work  as  if  they  were  local 
files.  The  system  can  be 


Dr.  Dobb's  Journal,  April  1986 


120 

301 


used  with  a  standard  local- 
area  network  or  long-haul 
data  communications 
hardware.  It  is  compatible 
with  Ethernet,  Omninet, 
ARCnet,  and  IEEE-488.  Built- 
in  security  features  are 
also  included. 

Based  on  Motorola  68000 
and  6809  microprocessor 
technologies,  the  Codex 
6740  is  a  midrange  statisti¬ 
cal  multiplexer  that  sup¬ 
ports  interfaces  for  a  mix  of 
asynchronous,  synchro¬ 
nous,  and  bit-oriented  pro¬ 
tocols.  The  6740  nodes  sup¬ 
port  up  to  eight  high-speed 
composite  links  ranging  in 
speed  from  2,400  bps  to 
64,000  bps.  The  system  sup¬ 
ports  up  to  19.2K  bps  and  is 
capable  of  stat  muxing  up 
to  64  channels  onto  one  or 
more  high-speed  links.  It 
also  provides  automatic 
routing  capabilities.  The 


cost  is  approximately 

$6,000. 

Infotron  Systems  has  an¬ 
nounced  that  its  Info- 
Stream  1500  high-speed 
multiplexer  is  compatible 
with  AT&T's  Digital  Access 
and  Cross-Connect  System 
(DACS).  DACS  consists  of  cen¬ 
tral-office  switching  equip¬ 
ment  that  allows  a  T1  carri¬ 
er  facility  of  1.544M  bps  to 
be  switched  or  cross-con¬ 
nected  to  another  T1 
carrier. 

Utilities 

Dogwood  Software  has  an¬ 
nounced  Helping  Hand,  a 
concurrent  productivity 
aid  and  reference  utility 
for  IBM  PC,  XT,  AT,  and 
Type  I  compatibles.  The 
program  runs  in  a  win¬ 
dowing  environment  al¬ 
lowing  users  to  access  a  va¬ 
riety  of  on-line  reference 


files.  Helping  Hand  re¬ 
quires  MS  DOS  1.0  or  later, 
33K  minimum  RAM,  and 
one  floppy  disk  drive. 

Minnow  Bear  Comput¬ 
ers'  CBC  Manager  II  is  a  util¬ 
ity  for  Digital  Research's 
CBASIC  compiler  that  al¬ 
lows  programmers  to  uti¬ 
lize  more  memory.  It  does 
this  by  allowing  functions 
to  be  placed  and  called 
from  areas  normally  inac¬ 
cessible  to  CBASIC  compiler 
programs.  CBC  II  also  has 
options  that  allow  routines 
to  be  called  in  MS  C  or  MS 
Pascal.  The  utility  is  avail¬ 
able  for  MS  DOS  and  re¬ 
quires  MS  DOS  2.1  or  later  to 
run. 

Mastercom,  a  telecom¬ 
munications  utility  from 
The  Software  Store,  is  avail¬ 
able  for  the  IBM  PCjr,  as 
well  as  for  most  computers 
compatible  with  IBM  PC  DOS 


and  CP/M-80.  Mastercom 
supports  Christensen  XMO¬ 
DEM,  XON/XOFF,  line  at  a 
time,  and  no  protocol.  It 
features  auto-dial,  auto-an- 
swer,  host-mode  unattend¬ 
ed  operation,  batch-file 
transfer,  directory  display 
file  erase,  file  rename,  disk 
drive  logging,  stored  re¬ 
sponses,  file  viewing, 
upload  text  throttle,  filter 
or  ASCII  display  options  for 
received  control  parame¬ 
ters,  and  menu-installed 
and  menu-driven 

operation. 

Squeezepak,  an  en¬ 
hanced  disk  compression 
and  optimization  utility 
from  Demac  Software,  is 
intended  for  use  on  the  DEC 
PDP-11  line  of  minicomput¬ 
ers  using  the  RSC  operating 
system.  A  VAX/VMS  version 
is  also  available.  With  the 
system,  users  can  request 
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the  generation  of  statistical 
profiles  describing  a  disk’s 
fragmentation  status 
throughout  the  file  reorga¬ 
nization  process.  This  in¬ 
formation  can  be  dis¬ 
played  on  the  users’s  VDT 
or  directed  to  a  disk  log  file 
during  run  time. 

Security 

Sutton  Designs  is  shipping 
its  sixth-generation  surge 
suppressors  under  the 
original  ZX-5000  label  first 
introduced  in  1981.  Twen¬ 
ty-seven  models  are  avail¬ 
able  in  the  series,  including 
modem  data  line  protec¬ 
tors  and  brownout  protec¬ 
tion  models.  The  sixth-gen¬ 
eration  introduction 
includes  a  five-stage  surge 
and  spike  system  designed 
to  exceed  all  IEEE  587  1980 
Category  A  test 
requirements. 

Everett  Enterprises  has 
released  a  software  en¬ 
cryption  program  called 
the  Private  Line.  It  con¬ 
forms  to  the  Data  Encryp¬ 
tion  Standard  published  by 
the  National  Bureau  of 
Standards.  MS  DOS  and 
CP/M  versions  are  avail¬ 
able.  The  Private  Line  en¬ 
ables  users  to  send  commu¬ 
nications  (program,  data, 
or  text  files)  over  telecom¬ 
munications  networks 
without  fear  of  interfer¬ 
ence  by  third  parties. 

Rainbow  Technologies 
has  released  a  Xenix  ver¬ 
sion  of  its  Software  Senti¬ 
nel  hardware  key  system 
that  prevents  unautho¬ 
rized  access  to  software 
programs.  The  Software 
Sentinel  uses  a  proprietary 
encryption  algorithm.  A 
series  of  locks  are  defined 
by  the  software  developer 
and  are  implemented  as 
part  of  the  program. 

Productivity  Aids 

Lightning  is  a  RAM-resident 


disk-caching  program 
from  the  Portable  Comput¬ 
er  Support  Group  (PCSG) 
that  is  designed  to  antici¬ 
pate  what  disk  accesses  are 
most  likely  to  occur.  Algo¬ 
rithms  enable  the  program 
to  build  a  smart  buffer, 
which  keeps  the  most 
called-for  disk  accesses  in 
RAM  and  is  adjustable  from 
40K  to  300K.  Lightning  is 
intended  to  improve  the 
performance  of  the  IBM  PC, 
XT,  AT,  or  any  compatible 
running  under  MS  DOS.  A 
copy-protected  version 
sells  for  $49.95;  the  unpro¬ 
tected  version  is  $89.95. 

The  RaceCard-286,  a 
plug-in  card  that  is  said  to 
run  software  up  to  six 
times  faster  than  normal 
with  no  modification  to 
the  software,  is  available 
from  Mountain  Computer. 
RaceCard  emulates  the  IBM 
8088  processor  and  is  com¬ 
patible  with  nearly  all  AT 
software,  RAM,  and  pe¬ 
ripheral  cards.  The  half¬ 
card,  which  measures 
5X3.9  inches,  uses  7  watts 
of  power  from  the  com¬ 
puter's  power  supply.  The 
3Com  Ether  Series,  Novell, 
Orchid  PCnet,  and  Starlan 
are  among  the  network 
packages  supported.  Race- 
Card  is  priced  at  $795. 

The  AT  Gizmo  is  a  card 
from  The  Software  Link 
that  allows  PC  DOS  applica¬ 
tions  to  use  4.6  megabytes 
of  extended  memory  in 
the  PC/AT.  The  AT  Gizmo 
with  MultiLink  Advanced 
allows  up  to  nine  parti¬ 
tions  of  up  to  512K  each.  It 
attaches  directly  to  the 
80286  processor  and  oper¬ 
ates  at  up  to  10  megahertz. 
A  separate  slot  in  the  PC/AT 
is  not  required.  The  prod¬ 
uct  sells  for  $295. 

Odin  Research  has  devel¬ 
oped  Otis  decision  support 
software  to  run  on  any  IBM 
PC  or  compatible,  and  on 
any  IBM  mainframe  or 
compatible  using  the  CMS 
operating  system.  Otis  is 


compatible  with  Lotus  1-2- 
3,  Symphony,  and  dBASE. 
All  data  processing  takes 
place  in  an  area  of  memo¬ 
ry  that  automatically  ex¬ 
pands  to  the  size  of  avail¬ 
able  computer  memory. 
Large  groups  of  items  can 
be  handled  as  a  single  item 
using  a  letter  series  of 
names.  Processes  can  be  re¬ 
peated  with  a  built-in  lan¬ 
guage  that  includes  loops 
and  conditional  expres¬ 
sions.  Otis  runs  on  DOS  2.0 
or  later  and  requires  320K 
minimum  memory. 

With  the  ZSTEMpc-4014 
from  KEA  Systems,  users 
can  interactively  zoom  in 
to  display  portions  of  an 
image  that  would  other¬ 
wise  be  hidden  by  the  lim¬ 
ited  resolution  of  the 
screen.  While  zoomed  in, 
users  can  pan  to  different 
portions  of  the  image.  The 
zoom  and  pan  functions 
are  controlled  by  the  cur¬ 
sor  keys  or  a  mouse  and 
are  transparent  to  the  host. 
Images  can  be  saved  and 
recalled  from  disk.  The 
system  emulates  a  Tek¬ 
tronix  4014  terminal  with 
the  enhanced  graphics  op¬ 
tion.  It  requires  ZSTEMpc- 
VT100,  Version  2.0  or  later, 
and  runs  on  IBM  PC,  PCjr, 
XT,  AT,  or  compatible  com¬ 
puters  with  MS  DOS,  Ver¬ 
sion  2.0  or  later.  It  also  re¬ 
quires  192K  of  main 
memory;  a  color/graphics, 
enhanced  graphics,  or  Her¬ 
cules  graphics  adapter;  an 
internal  modem  or  serial 
port;  and  one  floppy  drive. 

Apple 

SoftDesign  has  agreed  to 
act  as  publisher  for  Mac- 
Lightning,  a  RAM-resident 
software  tool  that  allows 
users  to  access  and  manip¬ 
ulate  a  variety  of  data  li¬ 
braries  and  reference 
works.  The  product  is  pub¬ 
lished  jointly  under  an 
agreement  reached  be¬ 
tween  SoftDesign  and  Tar¬ 
get  Software.  MacLight- 


ning,  which  currently  in¬ 
cludes  a  31,000-word  dic¬ 
tionary  and  a  built-in 
grammar  checker,  costs 
$99.95.  It  runs  with  Jazz, 
Excel,  Omnis  3,  Page¬ 
Maker,  Word,  and  Think- 
Tank.  Built-in  “Hot  Keys" 
allow  users  to  correct  er¬ 
rors  within  a  document, 
add  words  to  the  dictio¬ 
nary  or  jump  between  an 
application  and  MacLight- 
ning.  As  words  are 
checked,  they  are  left  in 
RAM  to  speed  up  future 
corrections. 

"subCity  is  a  library  of 
subroutines  and  declara¬ 
tions  for  Apple  Pascal  pro¬ 
grammers  that  includes 
the  source  texts  for  more 
than  100  procedures,  func¬ 
tions,  and  declarations,  as 
well  as  information  on  sev¬ 
eral  hard-to-find  topics. 
Topics  in  ’subCity  include 
character,  number,  and 
string  handling;  input 
prompts;  error  handling; 
and  search  and  sort  algo¬ 
rithms.  A  set  of  routines 
for  disk  use  provides  disk 
directory  lists,  disk  crunch, 
date  set,  file  rename,  and 
compare.  Assembly-lan¬ 
guage  routines  include 
finding  the  memory  ad¬ 
dress  of  any  variable,  a 
string  finder,  and  bit-ma¬ 
nipulation  for  character 
arrays.  ’subCity  is  available 
for  Apple  II  computers 
with  Apple  Pascal. 

Apple  II  Pascal,  Version 
1.3,  supports  UniDisk  3.5, 
Apple's  recently  intro¬ 
duced  3V2-inch  floppy  disk 
drive  that  increases  floppy 
disk  storage  capacity  to 
800K.  It  includes  the  lan¬ 
guage  on  both  3V2-  and  5V<t- 
inch  disk  formats.  The  new 
version  runs  on  any  Apple 
II  Plus,  He,  or  lie  personal 
computer  with  at  least  64K 
of  internal  memory. 

Application 

Development 

Synergy,  a  TopView-com- 
patible,  multitasking  oper- 
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ating  environment  offer¬ 
ing  windows,  icons, 
pull-down  menus,  fonts, 
and  other  graphic  tools  in 
12K  RAM,  allows  develop¬ 
ers  to  create  user  inter¬ 
faces.  Available  from  Ma¬ 
trix  Software,  Synergy  is 
compatible  with  MS  DOS  or 
PC  DOS  (Version  2.0  and  lat¬ 
er)  and  TopView.  Up  to  six 
programs  can  be  run  si¬ 
multaneously  as  multitask¬ 
ing  background  processes 
in  windows. 

On-Line  Software  Inter¬ 
national  has  announced 
that  DataVantage,  a  CICS/ 
IMS  application  testing  and 
development  tool,  has 
been  enhanced  to  support 
the  DOS/DLi  database  envi¬ 
ronment.  DataVantage  fea¬ 
tures  ad  hoc  query,  delete, 
replace,  and  insert  func¬ 
tions  in  the  batch  or  on¬ 
line  modes.  All  accessed 
data  is  automatically  trans¬ 
lated  into  a  display.  Seg¬ 
ments  can  be  selected  for 
processing  based  on  the 
contents  of  one  or  several 
fields  within  the  segment. 

CompuFirm's  Data  Base 
Manager  software  subsys¬ 
tem  enables  writers  of  ap¬ 


plication  programs  to 
store,  update,  and  retrieve 
data  records.  This  can  be 
accomplished  on  micro¬ 
computers  functioning  un¬ 
der  the  DOS,  iRMX-86,  and 
RTX  operating  systems. 
The  Data  Base  Manager 
maintains  data  records 
that  are  accessed  through 
actions  such  as  open/close 
database;  read/write/re- 
write/delete  record;  read 
next  or  previous  record; 
and  purge  or  create  data¬ 
base.  Each  format  is  avail¬ 
able  for  $495. 

StruBAS,  the  structured 
BASIC  Development  System 
for  the  IBM  PC  and  compati¬ 
bles,  provides  structured 
programming  facilities, 
full-screen  handling,  in¬ 
dexed  files,  and  menus.  A 
preprocessor  translates  BA¬ 
SIC,  encased  in  structured 
constructs  without  line 
numbers,  to  Microsoft  BA¬ 
SIC.  Subroutines  and  re¬ 
cord  structures  for  I/O  are 
included,  and  built-in  com¬ 
mands  support  full-screen 
and  indexed  file  features. 
The  system,  from  Laney 
Systems,  also  features  a 
file-maintenance  program 
generator,  development 
menus,  an  ISAM  rebuild 
utility,  a  source  indent  util¬ 


ity  and  utility  subroutines. 

CRI’s  Relate/3000  data¬ 
base  management  system 
now  operates  under  Ada. 
The  Application  Builder 
feature  serves  as  an  inter¬ 
face  between  the  user,  the 
application  being  devel¬ 
oped,  and  Relate  itself.  It 
uses  high-level  commands 
to  access  Relate  commands 
and  constructs,  defining 
screen  layouts  with  page 
images  stored  in  an  appli¬ 
cation  file. 

Services 

Deltak  has  released  JCL 
Fundamentals,  an  eight- 
course  computer-based 
training  series.  An  intro¬ 
duction  to  MVS  Job  Control 
Language  (JCL),  this  series 
covers  topics  ranging  from 
an  overview  of  JCL 
through  common  JCL  state¬ 
ments,  job  streams,  and  de¬ 
bugging  JCL  errors.  The 
courses  deliver  instruction 
on-line  using  Phoenix/DS. 
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About  the  Cover 

Photographer  Tom  Upton  rede¬ 
signed  this  classic  shell. 


This  Issue 

With  Bob  Frankston,  Dan  Brick- 
lin  won  the  1985  ACM  Software 
System  Award  for  inventing  a 
new  software  metaphor  in  Visi- 
Calc.  Bricklin’s  latest  invention  is 
a  tool  for  allowing  software  de¬ 
velopers  to  play  the  what-if 
game  with  their  own  visual  met¬ 
aphors  before  writing  any  code. 
We  asked  Jim  Edlin  to  use  Brick- 
lin's  program  to  demonstrate  the 
process  of  designing  from  the 
outside  in. 


Next  Issue 

In  June,  we'll  present  techniques 
for  ensuring  error-free  telecom¬ 
munications  transmission.  We  ll 
also  take  a  closer  look  at  Jef  Ras¬ 
kin’s  unusual  SwyftCard  for  the 
Apple  lie,  and  introduce  two  new 
columns.  Structured  Program¬ 
ming  will  concentrate  on  Algol- 
derived  languages  such  as  Pascal, 
Modula-2,  and  Ada;  and  our  edi¬ 
tor-in-chief’s  new  column  will 
range  from  a  look  at  Turbo  Prolog 
to  a  satire  on  the  issue's  theme. 
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EDITORIAL 


finally  hired  an 

M  editor.  Now  I 
ML  can  spend  my 
afternoons  on  the 
beach  as  an  editor-in- 
chief  ought  to.  I  can 
also  write  that  back- 
of-the-magazine  col¬ 
umn  I've  been  plan¬ 
ning — it  will  appear 
netf  month.  That's  the 
new  guy  at  the  right. 

I'll  let  him  introduce  himself. 

— Michael  Swaine,  editor-in-chief 

I’m  Nick  Turner,  the  new  editor  of 
DDJ.  I've  been  a  professional  consul¬ 
tant  for  the  last  few  years,  and  before 
that  I  spent  three  and  a  half  years  as  a 
game  designer  at  Atari.  (I  did  Super 
Breakout,  Demons  to  Diamonds,  and 
Frog  Pond,  and  I  worked  with  anoth¬ 
er  programmer  to  create  Snoopy  and 
the  Red  Baron — all  games  for  the  2600 
VCS  machine.)  After  I  left  Atari,  I 
joined  a  start-up  firm  that  promptly 
went  under.  I  have  worked  with 
other  companies  on  a  consulting 
basis. 

Now  that  I'm  the  editor,  I  have  a 
chance  to  help  guide  the  magazine 
and  keep  it  focused.  Always  eclectic 
and  pertinent,  DDJ  is  more  varied  and 
interesting  than  ever.  Professionals 
experienced  in  all  areas  of  computer 
science  submit  articles  that  explain 
their  freshest  and  most  innovative 
ideas.  I  want  to  continue  the  tradition. 
It’s  an  honor  to  be  involved  in  a  maga¬ 
zine  with  such  a  concerned  and  com¬ 
mitted  readership. 

Now,  down  to  work.  We’re  looking 
for  articles  that  feature  elegant, 
clean,  sophisticated  programs.  This  is 
your  chance  to  get  involved.  If 
you've  got  a  program,  utility  or  cod¬ 
ing  technique  that  is  really  nifty,  will 
you  write  it  up  and  share  it  with  the 
rest  of  us?  Don't  forget  to  send  us  a 
disk  containing  everything  that  you 
submit. 

If  you're  in  doubt  about  whether 
your  manuscript  would  be  appropri¬ 
ate  for  DDJ,  why  not  give  me  a  call? 


You  can  reach  me 
during  the  business 
day  (Pacific  time)  at 
(415)  366-3600.  I'll  en¬ 
joy  discussing  our 
upcoming  schedule 
with  you.  Here's  a 
quick  rundown  of 
what's  coming  up: 

Our  September  is¬ 
sue,  with  an  author 
deadline  of  June  1, 
will  deal  with  algorithms.  I'd  particu¬ 
larly  like  to  see  something  on  the  re¬ 
cent  advances  in  linear  program¬ 
ming.  It  would  also  be  nice  to  have 
some  material  on  real-world  algo¬ 
rithms,  for  example,  the  algorithms 
used  by  robots  to  navigate  complex 
spaces. 

October  focuses  on  the  80286  and 
80386  processors.  How  will  they 
compete  with  the  680XX  and  320XX 
lines?  What  makes  them  more  (or 
less)  useful  or  efficient?  How  is  the 
upgrade  from  the  80286  to  the  80386 
being  handled?  In  particular,  I’d  like 
to  see  some  articles  with  tight  ma¬ 
chine-language  code.  October's  dead¬ 
line  is  July  1. 

November  will  be  about  graphics. 
This  should  be  a  really  fun  issue  be¬ 
cause  there's  been  so  much  happen¬ 
ing  recently.  I'd  like  to  get  some  ma¬ 
terial  on  the  recent  advances  in 
surface  depiction,  ray-tracing,  parti¬ 
cle  systems,  or  any  of  the  other 
amazing  breakthroughs  of  the  last 
two  years.  Manuscript  deadline  is 
August  1. 

Finally,  December  will  concen¬ 
trate  on  operating  systems.  I'd  partic¬ 
ularly  like  material  on  the  very  low¬ 
est  levels  of  operating-system 
design — the  central  kernel — where 
the  nuts-and-bolts  task  handling 
takes  place.  Deadline  for  December  is 
September  1. 

Nick  Turner 
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LETTERS 


Columns 

Dear  DDJ, 

I  have  a  few  comments  re¬ 
garding  Cortesi's  article  on 
disk  timings  in  the  Septem¬ 
ber  1985  issue.  I  ran  the  BA¬ 
SIC  timing  program  on 
TESTFILE  installed  on  a 
RAMdisk.  The  time  was  64 
seconds  compared  to  the 
122  for  a  floppy  disk.  Clear¬ 
ly,  BASIC  has  a  considerable 
overhead  in  its  internal 
transfer  of  data,  apart  from 
the  disk  delays.  (The  copy 
command  copied  the  RAM¬ 
disk  file  in  less  than  a 
second.) 

Regarding  the  fast  time 
of  the  copy  command  us¬ 
ing  a  floppy,  it  seems  to  me 
that  PC  DOS  applies  main¬ 
frame  techniques  to  its 
disk  transfers.  The  fastest 
way  to  do  a  file  copy  is  to 
transfer  cylinders  of  data 
at  a  time.  Cylinder  trans¬ 
fers  do  not  have  to  start  at 
the  lowest-numbered  sec¬ 
tor  of  the  cylinder  but  can 
start  at  the  first  available 
sector  and  do  a  wrap¬ 
around.  The  program  that 
reads  the  disk  in  this  way 
simply  maps  the  sector 
onto  the  appropriate  RAM 
address  and  counts  sectors 
until  all  sectors  of  the  cyl¬ 
inder  have  been  read.  This 
is  the  reason  for  the  speed 
of  a  program  such  as  copy. 

I  cannot  let  the  article's 
implication  that  a  freshly 
formatted  disk  has  its  first 
free  data  area  lined  up 
neatly  on  cylinder  1  pass 
without  comment.  The  BA¬ 
SIC  program  and  the  text  of 
the  article  imply  that  to 


conduct  proper  timings  on 
a  physical  device  such  as  a 
disk,  the  transfers  should 
line  up  on  complete  cylin¬ 
ders.  The  first  free  space 
on  a  freshly  formatted  disk 
is  on  track  0,  sector  4,  side 
1.  Thus  the  file  TESTFILE  is 
misaligned  on  cylinders 
and  is  spread  over  17  cylin¬ 
ders,  not  16.  If,  for  exam¬ 
ple,  a  program  were  to 
loop,  reading  the  first  nine 
sectors  of  TESTFILE  in  order 
to  give  timings  of  pure 
reading  without  head 
movement,  there  would  in 
fact  be  a  change  of  cylin¬ 
der,  resulting  in  head 
movement.  In  the  case  of 
the  file  timings,  however, 
the  error  is  very  slight,  and 
the  article  should  be  noted 
carefully  by  anyone  who 
wishes  to  write  a  fast  oper¬ 
ating  system  for  the  IBM  PC. 

Mike  Lawrie 

22  Ilchester  Rd. 

Grahamstown  6140 

South  Africa 


Dear  DDJ, 

I  read  with  interest  Dan 
Daetwyler’s  comments  on 
converting  to  DOS  3.0  (16-Bit 
Software  Toolbox,  Decem¬ 
ber  1985).  As  a  DOS  2.1  hack¬ 
er,  I  have  a  few  comments 
to  make.  In  spite  of  his  stat¬ 
ed  distaste  for  DOS  x.O  bugs, 

I  assume  that  he  is  using 
DOS  2.0  because  the  20-han¬ 
dle  limit  per  process  is  pre¬ 
sent,  and  enforced,  al¬ 
ready  in  DOS  2.1. 

The  limit  is  necessary  be¬ 
cause  at  address  18h  in  the 
Program  Segment  Prefix, 
DOS  keeps  a  20-byte  array 
for  translating  the  user's 
file  handle  into  another 
number  that  DOS  uses  as  an 
index  into  its  array  of  files,  j 
I  doubt  that  this  table  is  I 
longer  in  DOS  2.0  because  ! 
the  segment  address  of  the 
environment  is  kept  at  ad¬ 
dress  2C.  Assuming  the 
mechanism  to  be  the  same 
in  DOS  2.0  as  in  2.1,  he  is 
causing  a  number  of  po¬ 
tential  bugs.  First  of  all, 


these  extra  file  handles 
won’t  be  closed  automati¬ 
cally  when  the  program 
terminates  or  receives  a 
Ctrl-Break.  More  impor¬ 
tant,  those  extra  file  han¬ 
dles  may  have  their  table 
entries  stomped  on  by 
whatever  DOS  does  with 
addresses  2E-5B. 

Assuming  that  DOS  3.1 
uses  this  same  mechanism, 
he  might  be  able  to  get 
around  the  20-handle  limit 
by  maintaining  his  own 
longer  version  of  this  table 
elsewhere.  In  fact,  he  can 
do  everything  with  one 
file  handle.  For  example, 
to  open  a  file,  he  could  first 
set  [18h]=0FFh.  The  OPEN 
function  call  will  return 
file  handle  0,  and  he  can 
move  the  internal  DOS  file 
index  from  18h  to  his  own 
table.  Then  when  he 
wants  to  use  the  file,  he 
can  set  [18h]  to  that  file  in¬ 
dex  and  call  DOS  with  file 
handle  0,  and  the  DOS  func¬ 
tion  will  refer  to  the  de¬ 
sired  file.  I  should  note  that 
he  will  have  to  close  all 
files  himself  upon  pro¬ 
gram  termination  (normal 
or  otherwise).  Also,  I  have 
not  tested  this  approach,  so 
I  give  no  guarantees.  I 
merely  note  that  COM- 
MAND.COM  does  a  similar 
trick  when  bypassing  I/O 
redirection  for  the  "Abort, 
Retry,  Ignore?”  message. 

Paul  Vojta 

591  Orange  St. 

New  Haven,  CT  06511 

Dear  DDJ, 

In  your  July  1985  issue,  16- 
Bit  Software  Toolbox  be¬ 
gan  with  the  line  "One  of 
the  most  novel  features 
added  in  Version  2  of  MS 
DOS  is  the  concept  of  ‘instal¬ 
lable  device  drivers.’  "  I 
would  like  to  say  that  this 
concept  may  be  new  and 
novel  for  Microsoft  and  MS 
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DOS  but  it  is  certainly  not  a 
new  and  novel  concept  for 
other  operating  systems 
available  for  microproces¬ 
sors. 

The  OS-9  operating  sys¬ 
tem  has  had  the  concept  of 
user-installable  device 
drivers  since  its  initial  6809 
Level  1  release  in  1978.  In 
fact,  OS-9  is  totally  modular 
in  nature  and  allows  for 
the  user  addition  of  new 
device  descriptors,  device 
drivers,  and  new  file  man¬ 
agers  if  required.  On  top  of 
supporting  installable  driv¬ 
ers,  OS-9  has  included  the 
''novel”  MS  DOS  concepts  of 
hierarchical  directory 
structures  and  pipes.  OS-9 
also  gives  full  support  to 
I/O  redirection,  multipro¬ 
cessing,  and  multitasking, 
concepts  much  more  akin 
to  Unix. 

OS-9  may  not  be  as  well 
known  as  MS  DOS  is,  but  it 
does  have  a  large  follow¬ 
ing  in  the  6809  and  68XXX 
world  today  and  is  grow¬ 
ing  rapidly.  MS  DOS  has 
added  nothing  novel  to  its 
OS;  it  is  adding  features 
that  are  expected  and  re¬ 
quired  for  an  OS  in  today's 
world.  These  features  have 
been  around  in  OS-9  and 
OS-9/68000  for  some  time. 

Tim  Harris 

Microware  Systems 
Corp. 

1866  N.W.  114th  St. 

Des  Moines,  IA  50322 

Dear  DDJ, 

This  letter  has  a  twofold 
purpose.  The  first  address¬ 
es  the  source  code  LJ.C  giv¬ 
en  in  the  September  1985 
16-Bit  Software  Toolbox, 
and  the  second  addresses  C 
source  code  listings  for  "A 
New  Shell  for  MS  DOS,  Part 
1:  IBM  Cursor  Control  and 
an  Fgets  That  Edits”  in  the 
December  1985  C  Chest. 

When  I  tried  to  run  the 
LJ.C  program,  it  would  al¬ 
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ways  hang  up  on  the  end 
of  the  first  file  to  be  print¬ 
ed.  I  traced  the  problem  to 
the  way  that  the  end  of  file 
is  found  in  the  printpagef  ) 
switch.  K  &  R  states  that 
the  variable  c  should  be  de¬ 
clared  as  type  int  so  that 
the  end  of  file  (EOF)  can  be 
properly  stored  and  tested 
for.  Bringing  the  source 
code  in  line  with  K  &,  R  by 
changing  the  variable  c  to 
type  int  and  changing  \377 
to  EOF,  which  should  be 
defined  in  stdio.h,  cleared 
up  the  problem.  Listing 
One,  page  68),  gives  the  re¬ 
vised  source  code  with  this 
correction  included  and 
modified  to  allow  either 
Lattice’s  C  compiler  or 
Computer  Innovations' 
C86  compiler  to  be  used. 

Also,  a  minor  problem 
occurred  with  the  source 
listing  of  LJ.C.  It  was  hard  to 
distinguish  between  the 
letter  /  (ell)  and  the  number 
1  (one)  in  the  listing.  This 
was  especially  trouble¬ 
some  in  the  escape  codes  to 
the  HP  LaserJet  printer, 
where  these  two  appear 
often  right  next  to  each 
other.  It  would  be  conve¬ 
nient  if  a  typeset  that  dif¬ 
ferentiates  between  these 
two  were  used  in  source 
code  listings. 

There  is  a  problem  with 
the  source  listing  for  the 
new  shell  for  MS  DOS  in  De¬ 
cember's  C  Chest  that  con¬ 
cerns  the  function  scurf ). 
Pagenum  is  passed  as  an  ar¬ 
gument  but  is  not  declared 
in  scurf ).  This  is  a  syntax 
with  which  I  am  not  famil¬ 
iar,  nor  is  it  a  syntax  that  I 
could  find  in  either 
K  &  R  or  several  other 
books  on  C.  An  explanation 
of  this  syntax  in  the  next  C 
Chest  would  be  greatly 
appreciated. 

To  put  the  above  prob¬ 
lems  in  perspective,  I  must 
say  that  DDJ  is  the  best 
magazine  I  have  found  for 
programmers.  I  started 
learning  C  about  three 


years  ago  solely  by  myself 
from  books.  It  was  not  un¬ 
til  a  year  and  a  half  ago 
when  I  discovered  DDJ  that 
my  real  insight  into  pro¬ 
gramming  started  to  sur¬ 
face.  I  attribute  a  lot  of  this 
to  your  fine  magazine  and 
the  quality  of  the  articles 
published.  I  look  forward 
to  each  edition  of  DDJ  more 
than  I  do  to  any  other  com¬ 
puter  magazine. 

Raymond  Moon 

16005  Pointer  Ridge  Dr. 

Bowie,  MD  20716 

Ray  Duncan  replies: 

The  program  as  printed  in 
the  September  1985  DDJ 
works  properly  when 
compiled  with  Lattice  C,  as 
was  stated  in  the  column. 
However,  Mr.  Moon's 
changes  to  the  program  to 
make  it  "standard”  are  cor¬ 
rect,  and  will  be  helpful  to 
DDJ  readers  who  use  other 
C  compilers.  An  updated 
version  of  the  program  is 
available  in  Data  Library  2 
on  the  CompuServe  DDJ 
Forum. 

Allen  Holub  replies: 

Mr.  Moon  is  referring  to: 

scur(  posn,  pagenum ) 
short  posn; 

{ 

} 

Here  posn  is  of  type  short 
int  (the  int  is  implied),  and 
pagenum,  because  it's  not 
declared  explicitly,  is  as¬ 
sumed  to  be  of  type  int. 
That  is,  pagenum  is  de¬ 
clared  implicitly  by  con¬ 
text.  A  formal  argument 
list  is  one  of  two  places  in  C 
where  the  type  of  a  vari¬ 
able  doesn't  have  to  be 
spelled  out.  (The  other  is  a 
subroutine  call:  If  the  type 
of  the  return  value  of  a 
subroutine  isn't  declared 
before  the  subroutine  is 
used,  the  compiler  as¬ 
sumes  that  the  subroutine 
returns  an  int.)  Implicit 
declarations  are  used  in 


the  library  documentation 
of  most  compilers.  I  looked 
for  a  reference  in  K  &,  R, 
and  all  that  I  could  find  is: 
"All  variables  must  be  de¬ 
clared  before  use,  al¬ 
though  certain  declara¬ 
tions  can  be  made 
implicitly  by  context”  [Ker- 
nighan  &  Ritchie,  The  C 
Programming  Language 
(Englewood  Cliffs,  N.J.: 
Prentice  Hall,  1978),  36]. 
This  is  not  really  satisfac¬ 
tory.  I'm  sure  it’s  spelled 
out  in  more  detail  some¬ 
where  in  the  book,  but  I 
couldn't  find  it.  Every  com¬ 
piler  that  I  know  of  sup¬ 
ports  implicit  argument 
declarations  though. 

DDJ 
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Keep  it  Quiet 


The  fact  that  we  can  devel¬ 
op  technology  to  make 
computers  speak  and  un¬ 
derstand  human  speech  is 
not  sufficient  reason  to  let 
them  do  so.  Now  that  pro¬ 
gress  has  been  made  in  the 
fields  of  speech  synthesis 
and  recognition,  a  great 
rush  seems  to  be  on  to  de¬ 
velop  voice  applications  to 
capitalize  on  the  technolo¬ 
gy.  Many,  if  not  most,  of 
these  applications  strike 
me  as  worse  than  useless. 
There  is  a  simple  reason  for 
this:  For  now  and  probably 
for  decades  to  come,  voice 
represents  a  lousy  interface 
between  man  and  ma¬ 
chine. 

Consider  it  from  the  first 
direction — computer  voice 
synthesis.  Computer 
speech  might  be  a  nice 
gimmick  for  a  game,  but  it 
is  totally  inappropriate  for 
most  serious  applications. 
The  purpose  of  a  good  user 
interface  is  to  make  things 
easier  for  the  user.  Let's 
compare  a  computer  voice 
message  with  the  simple 
message  tone  and  text  on 
the  screen  that  is  common 
in  many  of  today's  applica¬ 
tions.  When  the  machine 
must  gain  the  user's  atten¬ 
tion,  a  short  tone  is  more 
than  adequate  for  the  task. 
Such  a  tone  can  register  in 
the  user’s  mind  without 
demanding  instant  atten¬ 
tion,  thus  allowing  the  user 
perhaps  to  complete  a 
train  of  thought.  Series  of 
tones  can  indicate  degrees 


by  Daniel 
Appleman 

®  1986  by  Daniel  Appleman. 
Appleman  is  a  hardware 
and  software  designer  at 
Microlabs,  in  Sunnyvale, 
Calif. 


of  urgency.  The  important 
thing  is  that  such  a  tone 
leaves  the  user  in  control. 
The  user  can  decide  when 
and  how  to  respond  and 
how  much  attention  to 
give  to  the  machine. 

With  a  computer  voice 
message,  the  situation  is 
radically  different.  The 
voice  not  only  interrupts 
whatever  the  user  is  doing 
but  also  demands  that  the 
user  interpret  the  message 
immediately.  Will  it  be¬ 
come  acceptable  in  our  so¬ 
ciety  for  a  computer  to  be 
able  to  interrupt  a  conver¬ 
sation  between  people?  I 
certainly  hope  not. 

A  voice  message  can  also 
be  misunderstood  easily, 
especially  with  many  of  to¬ 
day’s  voice  synthesizers, 
which  are  devoid  of  ex¬ 
pression  and  difficult  to 
comprehend.  Even  the 
good  ones  may  require  sev¬ 
eral  repetitions  of  a  mes¬ 
sage  for  full  understand¬ 
ing — after  all,  even  people 
often  need  to  repeat  them¬ 
selves.  A  screen  message 
can  be  studied  at  leisure. 

Worse  yet,  there  is  a  ten¬ 
dency  to  make  some  ma¬ 
chines  talk  that  were  clear¬ 
ly  meant  to  remain  silent. 
Most  people  do  not  require 
a  lecture  on  purchasing 
stamps  from  the  stamp  ma¬ 
chine  in  the  post  office.  I  do 
not  appreciate  a  hidden 
voice  telling  me  to  put  on 
my  seatbelt,  regardless  of 
how  nice  the  voice 
sounds — a  pleasant  buzzer 
and  light  that  can  be  dis¬ 
connected  easily  are  suffi¬ 
cient. 

The  situation  with  voice 
recognition  is  even  worse. 
Let's  assume  that  such  rec¬ 
ognition  systems  will  be 
perfected  and  will  achieve 
very  high  (say,  more  than 
95  percent)  word  recogni¬ 
tion  rates  with  very  large 
vocabularies  and  speaker 


independence.  Until  that 
time,  voice  recognition  sys¬ 
tems  will  continue  to  re¬ 
quire  significant  discipline 
on  the  part  of  the  user  in 
terms  of  care  in  pronuncia¬ 
tion  and  adaptation  to  the 
machine’s  vocabulary.  Al¬ 
though  a  95  percent  word 
recognition  rate  is  proba¬ 
bly  more  than  adequate 
when  people  speak  with 
each  other,  computers 
with  this  ability  will  still  be 
limited  because  word  rec¬ 
ognition  is  not  sufficient. 
When  people  communi¬ 
cate  with  each  other,  they 
use  many  more  clues  to  fill 
in  where  word  recognition 
leaves  off.  Expression,  tim¬ 
ing,  context,  eye  contact, 
body  language,  and  even 
subconscious  lip  reading 
are  important  parts  of  the 
communication  process. 

Until  computers  can  take 
all  of  these  into  account, 
they  will  be  limited  in  their 
capability  to  understand 
the  user  unless  the  user 
pays  conscious  attention  to 
the  communication  pro¬ 
cess.  This  defeats  the  origi¬ 
nal  goal  of  making  the  user 
interface  “friendly.”  At 
least  with  text  input,  peo¬ 
ple  are  accustomed  to  such 
discipline.  It  is  probably 
possible  for  people  to  learn 
to  communicate  verbally 
without  using  nonverbal 
clues — but  is  this  really  de¬ 
sirable?  Such  discipline 
would  undoubtedly  carry 
over  to  society  as  a  whole.  It 
is  one  thing  to  make  ma¬ 
chines  more  human,  but 
should  we  encourage  a 
process  that  could  make 
communication  between 
people  more  machinelike? 

Several  environmental 
problems  are  created 
when  attempting  to  devel¬ 
op  a  voice  communication 
system,  too.  Such  systems 
are  often  intolerant  of 
background  noise,  requir¬ 


ing  the  user  to  speak  loud¬ 
ly  into  the  microphone  in 
order  to  overcome  the 
noise.  An  office  with  such 
machines  would  also  have 
significant  noise  generated 
just  by  people  talking  to 
their  computers. 

There  are  some  applica¬ 
tions  for  which  even  today 
computer  voice  systems 
can  be  useful.  They  enable 
computers  to  be  used  by 
the  blind.  They  can  allow  a 
degree  of  voice  control  of 
computers  over  the  tele¬ 
phone.  They  allow  voice 
mail  systems  to  be  built. 
Future  applications  should 
include  voice  writers 
(voice-to-text  typewriters) 
and  translating  systems. 

For  now,  though,  the 
mad  rush  to  incorporate 
voice  systems  into  com¬ 
mon  computer  applica¬ 
tions  is  premature.  Enter¬ 
ing  information  into  a 
database  is  much  more  ef¬ 
ficient  via  a  keyboard,  and 
system  control  can  be  han¬ 
dled  very  nicely  using  to¬ 
day's  sophisticated  user-in¬ 
terface  systems  and 
pointing  devices. 

Someday  my  argument 
will  no  longer  be  valid. 
The  HAL  9000  computer  in 
the  movie  2001 — A  Space 
Odyssey  was  capable  of  in¬ 
terpreting  subtle  nonver¬ 
bal  clues  (including  lip 
reading).  It  was  also  capa¬ 
ble  of  learning  politeness, 
signaling  that  it  was  about 
to  speak  with  a  short,  elec¬ 
tronic  "throat  clearing.” 
When  such  computers  are 
possible,  voice  communi¬ 
cation  will  become  both 
convenient  and  neces¬ 
sary — until  then,  let’s  keep 
them  quiet. 

DDJ 
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The  following  is  a  thread  of 
conversation  from  one  of 
the  message  boards  on  the 
DIM  SIG: 

Fm:  Levi  Thomas 
76703.4060 

I  found  a  press  release  in 
the  morning  mail  here  at 
DDJ  which  actually  con¬ 
tains  some  interesting  in¬ 
formation  (rare  indeed). 
Skipping  over  the  fanfare 
and  David  vs.  Goliath  anal¬ 
ogy,  it  says  that  Microstuf 
software  company  has 
filed  suit  against  Softklone 
over  the  “look  and  feel”  of 
a  terminal  program  that 
Softklone  distributes.  The 
program  is  called  Mirror 
and  is  a  clone  of  Micros- 
tuf’s  Crosstalk  XVI. 

There  was  trouble  of  this 
kind  concerning  the  pro¬ 
posed  release  of  GEM  but  it 
was  settled  out  of  court,  so 
no  legal  precedent  was  set 
at  that  time.  Has  this  sort  of 
thing  been  brought  to  court 
before?  Softklone's  press 
release  goes  on  to  say  that 
Microstuf  did  not  contend 
that  its  source  code,  object 
code,  or  user  manual  were 
copied,  but  claimed  copy¬ 
right  infringement  based 
on  a  single  input  screen.  So 
what  do  you  think?  Should 
the  “look  and  feel”  of  a 
computer  program  be 
copyrightable? 

Fm:  Bob  Perez  76003,102 
Hmm.  Well,  this  area  is  cer¬ 
tainly  new,  and  it's  hard  to 
tell  what  the  courts  will  do 
with  it.  Some  observations: 
Close  cases  tend  to  be  de¬ 
cided  on  peripheral  details 
in  order  to  bring  the  bal¬ 
ance  of  evidence  in  align¬ 
ment  with  the  decision 
rendered.  It's  often  said 
(and  the  juridicial  positiv¬ 
ists  have  not  quarreled 
much  with  this)  that  judges 
make  the  law,  not  the  legis¬ 
lature,  and  that  they  do  so 


according  to  their  percep¬ 
tions  of  prevailing  moral 
trends.  Hence  the  liberal¬ 
ization  of  criminal  proce¬ 
dures  by  the  Warren  Court 
during  the  1960s  and  the 
other  end  of  the  spectrum 
currently  underway  by 
the  Burger  Court.  If  this  is 
so,  then  we  can  expect  that 
judges  will  soon  be  bend¬ 
ing  over  backwards  to  try 
and  fashion  some  seat-of- 
the-pants  remedies  for 
what  is  currently  being 
touted  as  "the  threat  of  pi¬ 
racy.”  Expect  to  see  it  hap¬ 
pen  first  in  the  copy-pro¬ 
tection  area  (particularly 
as  the  issues  are  raised  by 
the  Shrinkwrap  licensing 
notion)  and  then  expect  it 
to  expand  in  other,  deeper 
directions.  Perhaps  Apple 
could  have  presented  a 
good  test  case  with  its 
threats  against  DRI. . . . 

I  can  immediately  see  a 
couple  of  major  strikes 
against  Softklone  in  this 
case;  points  that  can  only 
help  Microstuf  in  its  effort 
to  sway  a  judge.  Naming 
their  company  Softklone 
was  stupid.  Period.  But 
then  naming  their  product 
Mirror  was  tantamount  to 
mailing  a  "I  Dare  You  to 
Sue  Me”  bumpersticker  to 
Microstuf’s  corporate 
counsel.  This  reminds  me 
of  the  obscenity  litigation 
that  Al  Goldstein  went 
though  with  his  magazine. 
It  was  bad  enough  calling  it 
Screw,  but  having  it  post¬ 
marked  from  Intercourse, 
Pennsylvania.  .  .  . 

Fm:  Chris  Dunford  (INF) 
76703,2002 

How  is  the  Crosstalk  clone 
conceptually  different 
from,  for  example,  the 
"store  brands”  that  most  of 
the  big  supermarket  chains 
sell?  You’ll  find  that  they 
sell  three  or  four  types  of, 
say  mouthwash:  One  looks 


identical  to  Scope,  one  to 
Listerine,  and  so  on.  They 
really  go  to  a  lot  of  trouble 
to  make  these  things  look 
like  the  original:  same  col¬ 
oring,  same  bottle  shape, 
same  scent,  etc.  My  bet  is 
that,  if  Softklone  has  the 
pockets  to  put  up  a  decent 
fight,  Microstuf  will  fold  its 
tent  quickly.  I’ve  got  a 
hunch  it’s  a  scare  tactic, 
and  that  Les  Freed  and  the 
gang  know  they  can’t  win 
in  court.  Copyrighting 
ideas  is  difficult. 

Fm:  Bob  Perez 
I  think  there  are  major 
conceptual  differences  be¬ 
tween  the  packaging  of 
disposable  consumer  prod¬ 
ucts  and  the  appearance  of 
a  computer  program's 
startup  screen.  Still,  I  think 
the  point’s  worth  noting. 
Maybe  a  better  analogy 
could  be  found  in  the  mov¬ 
ies.  Suppose  I  release  a  film 
that  begins  with  loud  blar¬ 
ing  trumpets  and  a  screen 
that  looks  very  similar  to 
the  opening  screen  in  Star 
Wars?  Suppose  the  movie 
is  called  WarsClone,  and 
suppose  my  company's 
name  is  LucasLike  Films, 
Ltd.  I'd  suspect  that  Lucas’s 
attorneys  could  start  mak¬ 
ing  their  retirement  plans 
at  that  point. 

Fm:  Chris  Dunford 
Hmm,  not  sure  that’s  a  good 
analogy,  either  Scratch¬ 
ing  head>.  Seems  to  me 
that  there’s  a  difference  be¬ 
tween  the  "feel”  of  a  movie 
and  the  "feel”  of  a  pro¬ 
gram.  A  film  has  nothing 
other  than  feel;  it's  an  en¬ 
tirely  visceral  product.  If  I 
"clone”  the  feel  of  a  movie, 
I  have  in  effect  stolen  the 
entire  product.  On  the 
other  hand,  a  program  has 
more  than  visceral  effects: 
it  does  something.  And  I 
have  just  argued  myself 


into  a  corner,  haven't  I? 
The  clone-maker  has 
cloned  both  the  feel  and 
the  tangible  effects  of  the 
program.  Hmm.  I  still  think 
that  mouthwash  provides  a 
good  analogy.  Not  sure  I  see 
how  cloning  mouthwash  is 
conceptually  different 
from  cloning  Crosstalk. 

Fm:  Todd  M.  Roy  70455,140 
...  I  think  what  has  hap¬ 
pened  is  that  DRI  folded  too 
fast  to  Apple  and  that  a  lot 
of  the  big  name  software 
companies  are  coming  out 
of  the  woodwork  now  to 
have  a  try  at  their  imitators. 

Fm:  Dick  Blowers 
71555,361 

I  think  of  a  computer  pro¬ 
gram  as  a  tool  because 
that’s  the  way  I  use  it.  I  find 
it  hard  to  think  of  "using”  a 
novel  or  a  movie. 

Fm:  Todd  M.  Roy  70455,140 
This  sort  of  stuff  doesn't 
really  bother  me.  It  would 
bother  me  if  one  company 
took  another  company  to 
court  over  the  basic  con¬ 
cept  of  a  program,  rather 
than  a  clone-like  look.  For 
example:  Lotus  taking  ev¬ 
erybody  who  ever  made  a 
spreadsheet  program  to 
court. 

Fm:  Robert  Grimble 
75206,2005 

The  problem  is  that  you  are 
not  copyrighting  an  idea. 
You  are  copyrighting  a  giv¬ 
en  display.  The  problem 
with  the  Proctor  and  Gam¬ 
ble  illustration  is  that  bottle 
shapes  are  covered  by  de¬ 
sign  patents,  and  there  are 
a  lot  more  on  file  than 
there  are  copyrights  on 
screen  displays.  Therefore, 
there  is  a  lot  wider  cover¬ 
age  by  the  copyrighted 
screens,  as  a  practical  mat¬ 
ter.  You  are  right  that  the 
deep  pocket  theory  has  a 
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lot  to  do  with  how  cases 
come  out,  but,  when  it 
comes  to  a  user  interface, 
there  is  no  reason  why  a 
software  developer  should 
not  be  protected.  It  costs  a 
lot  of  bucks  and  takes  more 
than  a  little  talent  for  a 
company  to  come  up  with 
a  friendly  and  useful  user 
interface.  That  kind  of  R&D 
is  exactly  what  patents  and 
copyrights  are  supposed  to 
protect. 

Fm:  Bob  Perez 
Well,  these  are  very  tough, 
interesting  issues.  On  the 
one  hand,  I  agree  that  in¬ 
novation  and  creativity  are 
stifled  when  clones  are  let 
loose  upon  the  world.  On 
the  other  hand,  Apple's  po¬ 
sition  on  their  proprietary 
interface  seems  to  assure 
that  the  marketplace  will 
develop  in  many  different, 
necessarily  incompatible 
directions,  at  the  expense 
of  the  very  users  with 
whom  Apple  seeks  solidar¬ 
ity.  Of  course,  it’s  within 
Apple's  rights  to  milk  it 
while  it  can.  I  don’t  think 
it’s  necessarily  in  their  best 
interests  to  do  so,  however. 

Fm:  Jim  Scheef  76505,1351 
Your  comment  on  Apple 
forcing  the  marketplace  to 
develop  many  different 
user  interfaces  is  an  impor¬ 
tant  point.  Sometime  in  the 
future  (probably  counted  in 
weeks  in  this  industry) 
someone  will  realize  that 
people  are  having  a  hard 
time  learning  to  use  micro¬ 
computers.  The  reason 
they  will  surmise  is  that  the 
industry  has  failed  to  pro¬ 
vide  a  standard  interface 
that  people  can  learn  and 
then  use  for  any  computer. 
This  same  person,  because 
he  or  she  is  also  a  member 
of  Congress,  will  then  pro¬ 
pose  legislation  to  correct 
this  obvious  oversight:  You 


have  already  seen  the  re¬ 
sults  of  this  type  of  legisla¬ 
tion  in  many  other  areas. 
Can  you  imagine  the  results 
if  Congress  designed 
icons????!!!  Standardization 
may  not  be  all  that  far  off  as 
many  industry  watchers 
believe  IBM  will  move  the 
TopView  interface  to  VM/ 
CMS  and  then  on  to  all  other 
operating  systems  as  well. 
Since  TopView  doesn't  use 
icons,  it  may  not  be  totally 
germain  to  the  thread,  but 
Apple  and  others  should 
realize  that  no  one  of  them 
is  going  to  get  all  of  the 
graphics  interface  business, 
so  why  not  agree  on  com¬ 
mon  icons  that  everyone 
can  learn  (the  way  rest¬ 
room  signs  have  become  in¬ 
ternationally  standard)  and 
use  regardless  of  language. 

Fm:  Keith  Moore 
73267,1570 

About  this  icon  business:  I 
seem  to  recall  that  when 
Apple  came  out  with  the 
Mac  they  were  talking 
about  all  of  the  symbols 
stamped  into  their  cabinet, 
such  as  the  telephone  re¬ 
ceiver  to  indicate  the  mo¬ 
dem  port.  Wherever  an  in¬ 
ternational  standard  for 
such  a  symbol  existed,  they 
used  it.  Where  there  was 
no  standard  symbol,  they 
hoped  that  theirs  would  be 
adopted.  Why  should  icons 
on  the  screen  be  different? 
Also,  I  seem  to  remember 
seeing  the  trash-can  icon 
on  some  old  Altos  software 
many  years  ago. 

Fm:  Jim  Scheef 
The  interpretation  of  copy¬ 
right  law  is  an  interesting 
issue.  Congress  enacted  the 
original  copyright  law  to 
encourage  authors  to  pub¬ 
lish  their  works;  i.e.,  make 
the  works  public.  In  return, 
the  authors  got  the  rights  to 
publication,  performance, 
etc.  for  a  limited  time.  With 
a  book  it  is  easy  to  deter¬ 
mine  exactly  what  consti¬ 


tutes  the  "work” — it's  the 
words  and  pictures.  What 
is  the  "words  and  pictures” 
of  a  piece  of  software?  Is  it 
the  source  code?  Remem¬ 
ber,  to  obtain  a  copyright, 
the  author  must  "make 
public”  his  work.  Or  is  the 
work  the  program's  output 
(results)?  If  it  is  the  results, 
then  does  that  mean  that 
Lotus  owns  all  of  the  work¬ 
sheets  I  put  together  using 
1-2-3?  After  all,  they  are  the 
results  or  output  of  the  pro¬ 
gram.  Or  have  I,  by  writing 
the  spreadsheet,  modified 
the  program  to  produce  a 
different  result?  I  think 
that's  a  violation  of  the  li¬ 
cense  agreement!  The  is¬ 
sues  aren’t  exactly  clear 
and  I  doubt  we’ll  resolve 
the  issue  here.  Going  back 
to  the  Lotus  example,  does 
a  program's  output  stop 
(for  the  purposes  of  copy¬ 
right)  with  the  intial 
screen(s)  provided  by  the 
publisher?  If  this  is  true, 
then  how  will  anyone  ever 
protect  an  artificial  intelli¬ 
gence  program  that  modi¬ 
fies  it's  output  depending 
on  the  responses  of  the 
user?  How  would  you 
know  if  someone  had 
cloned  such  an  AI  pro¬ 
gram?  Even  the  author 
might  not  know  all  of  the 
program’s  possible  outputs! 

Fm:  Robert  Grimble 
I  recall  that  one  judge  com¬ 
mented  in  a  computer  case 
that  “if  it  looked  the  same 
it  was  the  same.”  There  is 
no  reason  why  you  can't 
copyright  an  input  screen, 
and  game  manufacturers 
shoot  film  of  various  game 
screens  and  copyright 
them.  I’m  not  a  copyright 
expert,  but  I  think  that  to 
win  a  copyright  case  you 
have  to  show  actual  pla- 
garism,  which  is  unlike 
patents,  where  all  you 
have  to  show  is  the  use  of 
the  same  device,  process 
etc. 


Fm:  Ran  Talbott 

(ProgGnosis)  70506,60 
As  I  (mis?)understand  the 
law,  there  are  two  sepa¬ 
rate  issues  here:  The 
source  code  is  clearly  the 
"words  and  pictures”  part. 
You  don't  send  diskettes  or 
PROMs  to  the  copyright  of¬ 
fice:  They  are  considered 
electronic  representations 
of  the  original  source.  The 
appearance  of  the  screen  is 
treated  as  a  separate  work: 
Witness  the  Pac-Person 
clones  that  got  stomped 
even  though  they  ran  on 
different  machines  and 
couldn't  possibly  infringe 
the  source  copyright.  If 
Apple  had  successfully 
sued  over  their  screen 
copyright,  it  could  conceiv¬ 
ably  become  illegal  for 
anyone  to  publish,  say,  a 
book  or  magazine  article 
containing  a  screen  repre¬ 
sentation  of  a  spreadsheet. 
A  win  by  Apple  would  say: 
"Yes,  your  names  (data)  are 
different,  but  overall  it 
looks  like  what  I  sent  to  the 
copyright  office.  Pay  up.” 

Fm:  Todd  M.  Roy 
Another  interesting  point 
would  be  to  make  any 
copying  of  a  program  ille¬ 
gal.  Since  a  program  must 
be  loaded  in  from  a  floppy 
disk  to  computer  memory 
this  is  a  form  of  copying, 
and  hence  if  all  copying 
were  illegal,  running  the 
program  would  be  illegal. 
Don't  laugh,  this  isn’t  even 
a  new  point. 
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Accessing  IBM  Video  Display  Memory  and  a  Microsoft  Bug 


Strictly  speaking,  it’s  a  real  no-no 
to  read  and  write  directly  to  or 
from  the  IBM  PC’s  display  memory. 
You’re  supposed  to  go  through  the 
ROM  BIOS  routines.  Unfortunately, 
though  the  BIOS  is  faster  than  DOS, 
sometimes  it's  still  not  fast  enough. 
This  month  I'm  going  to  look  at  a  set 
of  C  subroutines  that  talk  directly  to 
the  IBM  PC  display  memory.  These 
routines  are  blindingly  fast — blink, 
and  you've  missed  the  action.  They'll 
work  on  all  versions  of  the  PC  that 
exist  now  (at  least  all  versions  that 
use  a  monochrome  adapter  or  equiv¬ 
alent — the  Hercules  graphics  card  is 
an  equivalent),  but  they  may  not 
work  on  future  hardware.  In  the 
process  of  writing  these  routines,  I 
came  across  a  bug  in  the  way  that  the 
Microsoft  compiler  handles  far 
pointers.  I’ll  talk  about  this  as  I  ex¬ 
plain  the  code. 

The  routines  supported  are  all  in 
video. c  (Listing  One,  page  72).  They 
are: 

void  setcur  (  row,  col ) 
int  row,  col; 

which  positions  the  cursor  at  the  in¬ 
dicated  row  and  column; 

void  getcurl  rowp,  colp  ) 

int  *rowp,  "colp; 

which  gets  the  current  cursor  posi¬ 
tion  (notice  that  rowp  and  colp  are 
pointers  to  places  where  the  cursor 
positions  will  be  put; 

void  d_putc(  c,  attrib  ) 
int  c,  attrib; 


by  Allen  Holub 


which  writes  a  single  character  with 
the  indicated  attribute  (more  on  attri¬ 
butes  in  a  moment)  at  the  current 
cursor  position  and  then  advances 
the  cursor.  Wraparound  to  the  next 


line  is  supported;  however,  if  you 
write  past  the  bottom-right  corner  of 
the  screen,  the  cursor  will  roll  up  to 
the  top-left  corner  (that  is,  the  screen 
doesn't  scroll).  Three  control  charac¬ 
ters  are  supported:  \r  gets  you  to  the 
beginning  of  the  current  line,  \n  gets 
you  to  the  same  column  on  the  next 
line,  and  \b  goes  backward  one  char¬ 
acter.  All  other  control  characters 
print  as  funny-looking  IBM  graphics 
characters  of  some  sort  (smiley  faces, 
hearts,  or  whatever). 

The  next  routine 

void  d_puts(  str,  attrib  ) 
char  *str; 
int  attrib; 

writes  out  a  string,  with  the  charac¬ 
ters  having  the  indicated  attribute. 
You  must  use  \r\n  to  get  to  the  left 
edge  of  the  next  line. 

Finally 

void  clrs(  attrib ) 
char  "str; 

clears  the  screen  by  filling  it  with 
blanks  having  the  indicated  attribute 
(that  is,  a  reverse-video  attribute  will 
fill  the  screen  with  a  white  back¬ 
ground  and  nothing  in  the  fore¬ 
ground;  an  underline  attribute  will 
fill  the  screen  with  underscores — 
that  is,  an  underlined  '  ’). 

Part  of  the  header  from  Listing 
One  is  reproduced  in  Table  1,  page 
20.  NUMROWS  and  NUMCOLS  define 
the  screen  size.  VIDBASE  is  the  base 
address  of  the  display  memory  used 
by  the  monochrome  adapter.  The  ad¬ 
dress  is  in  cannonical  form — that  is, 
OybOOOOOO  is  actually  address 
B000:0000. 


Three  basic  attributes  are  support¬ 
ed:  NORMAL  video,  UNDERLINED  char¬ 
acters  and  REVERSE  video.  These  are 
mutually  exclusive  (you  can’t  have 
an  underlined,  reverse-video  charac¬ 
ter).  Two  modifiers  are  supported, 
however:  BLINKING  and  BOLD.  The 
former  causes  the  character  to  blink, 
and  the  latter  causes  it  to  be  printed 
at  high  intensity.  The  modifiers  may 
be  ORed  with  each  other  and  with 
any  of  the  basic  attributes.  For  exam¬ 
ple,  a  blinking,  high-intensity  under¬ 
lined  character  has  the  attribute 
BLINKING  'ROLttUNDERLINED. 

Characters  are  stored  in  memory 
as  16-bit  objects.  The  low  byte  holds 
the  ASCII  code,  and  the  high  byte 
holds  the  attribute.  The  CHARACTER 
type  is  a  structure  that  lets  you  access 
the  ASCII  code  and  attribute  indepen¬ 
dently,  without  doing  a  shift  and 
mask  operation.  If  p  is  a  pointer  to  a 
CHARACTER,  then  p->letter 
changes  the  ASCII  field  and  p  —  >attri- 
bute  changes  the  attribute  field. 

DISPLAY  (on  line  26)  is  a  25  X  80  ar¬ 
ray  of  characters;  it’s  the  entire  dis¬ 
play  area.  Screen  is  a  pointer  to  a  DIS¬ 
PLAY.  The  far  keyword  is  supported 
by  the  Microsoft  compiler  to  ease 
mixed-model  programming.  Screen 
is  declared  here  as  a  far  pointer  to  an 
array — that  is,  the  array  can  be  any¬ 
where  in  memory  and  Screen  is  a  32- 
bit  wide  pointer  to  that  array.  If 
you're  using  the  Lattice  compiler, 
dispense  with  the  far  keyword  and 
compile  the  module  using  the  large 
data  model. 

Note  that  Screen  is  a  pointer  to  the 
entire  array  not  to  one  element  of  it. 
Consequently  individual  elements  of 
the  array  must  be  accessed  with 
square  brackets.  For  example,  a  bold¬ 
face  character  can  be  written  at  row 
5,  column  10  with: 

(*Screen)[5][10]. letter  =  ‘c’; 
(*Screen)[5][10]. attribute  = 

NORMALBOLD; 
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The  parentheses  are  required  be¬ 
cause  the  dot  (.)  has  higher  prece¬ 
dence  than  the  ».  Without  the  paren¬ 
theses,  the  expression  evaluates  to: 

*(  Screen[5][10], letter  )  =  'c'; 

which  is  meaningless  given  the  de¬ 
clared  type  of  Screen  (the  compiler 
should  kick  out  an  error  message). 

Because  Screen  is  never  modified, 
it  should  be  possible  to  replace  it 
with  a  constant.  The  procedure  can 
be  explained  more  easily  by  looking 
at  8080  code  rather  than  8086  code.  If 
you  want  to  modify  memory  loca¬ 
tion  OylOO  in  an  8080,  you  can  say: 

^define  MEM  ((char  *)  0x100) 
x  =  *MEM; 

Here,  you're  saying  treat  the  number 
OylOO  as  if  it  were  the  contents  of  a 
character  pointer,  so  * MEM  is  the 
thing  pointed  to  by  the  implied  char¬ 
acter  pointer.  The  problem  is  more 
complicated  with  an  8086  because  of 
memory  segmentation,  but  the  syn¬ 
tax  is  more  or  less  the  same.  Instead 
of  saying: 


DISPLAY  far  ‘Screen  = 

(DISPLAY  far  *)  VIDBASE; 
(*Screen)[5][10]. letter  =  'c'; 

you  should  be  able  to  say: 

^define  SCREEN  ( (DISPLAY  far  *)  / 

VIDBASE ) 

(*SCREEN)[5][10]. letter  =  'c’; 

SCREEN  is  treated  as  if  it  were  the 
contents  of  a  variable  of  type  (DIS¬ 
PLAY  far  *).  You  can  also  move  the  * 
that  precedes  the  use  of  SCREEN  into 
the  macro: 

^define  SCREEN  (  *(  (DISPLAY  far  *) 

VIDBASE) ) 

SCREEN[5][10], letter  =  ‘c’; 

As  it  turns  out,  the  foregoing  works 
fine  on  the  Microsoft  compiler  pro¬ 
vided  that  the  indexes  are  constants. 
That  is: 

SCR  EEN[5][10].  letter  = 

causes  the  following  code  to  be 
generated: 

mov  bx,  — 20480 
mov  es,bx 
mov  bx,820 
mov  BYTE  PTR  es:[bx],42 


where  —20480  is  OybOOO,  820  is  the 
offset  to  row  5,  column  10: 
2*((5*80)+10)  and  42  is  the  *.  Unfor¬ 
tunately,  strange  things  happen 
when  you  try  to  replace  the  con¬ 
stants  with  variables: 

int  Row  =  5; 
int  Col  =  10; 

SCREEN!  Row  ][  Col  l.letter  = 

generates  the  following: 

mov  _Row,5 
mov  _Col,10 

mov  ax, 160 
imul  _Row 
mov  si, ax 
mov  bx,_Col 
shl  bx,l 
mov  BYTE  PTR 

[bx  -  1342177280][si],42 

I  don’t  know  where  that 
—  1342177280  came  from,  but  it’s 
wrong.  When  you  use  the  Screen 
variable  rather  than  the  SCREEN  con¬ 
stant,  everything  works  fine,  though. 

The  final  thing  worth  mentioning 
here  is  the  clrs(  )  routine  (on  line  114 
of  Listing  One).  Here,  rather  than  use 
Screen,  I’ve  speeded  up  the  code  by 
declaring  a  pointer  to  an  individual 
CHARACTER  and  then  cleared  the 
Screen  array  as  if  it  were  linear,  rath¬ 
er  than  two-dimensional.  This  saves 
all  the  multiplies  implicit  in  an  oper¬ 
ation  involving  square  brackets. 

Note  that  redirection  obviously 
won’t  work  when  you  use  these  rou¬ 
tines  for  output,  but  redirection 
doesn't  work  when  you  use  the  BIOS 
routines  either.  Also,  be  careful 
about  mixing  these  routines  with 
normal  BIOS  calls.  If  the  cursor  is  up¬ 
dated  by  the  BIOS,  then  the  variables 
Row  and  Col  used  in  video. c  won’t 
correspond  to  the  real  cursor  posi¬ 
tion  any  more  (the  BIOS  won’t  update 
them  for  you)  and  strange  things  will 
start  happening  on  your  screen.  In 
spite  of  these  problems  and  the  lack 
of  portability  direct  screen  writes 
are  very  nice  to  have,  especially  if 
you're  creating  a  full-screen  editor  or 
similar  program,  in  which  you  have 
to  update  the  screen  fast. 

Beating  Dead  Horses 

At  the  risk  of  being  tedious,  I'm  bring- 
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#define  NUMROWS 

25 

5 

#define  NUMCOLS 

80 

6 

#define  VIDBASE 

OxbOOOOOOO  /*  Base  address  of  video  screen 

7 

*  in  canonical  form. 

8 

9 

V 

10 

#define  NORMAL 

0x07 

/*  Basic  attributes.  Only  one 

*/ 

11 

#define  UNDERLINED 

0x01 

/*  of  these  may  be  present. 

V 

12 

#define  REVERSE 

0x70 

13 

14 

#define  BLINKING 

0x80 

/*  May  be  ORed  with  the  above 

*/ 

15 

#define  BOLD 

0x08 

/*  and  with  each  other 

V 

16 

17 

/* - 

-  V 

18 

19 

typedef  struct 

20 

19 

typedef  struct 

20 

{ 

21 

char  letter; 

22 

char  attribute; 

23 

) 

24 

CHARACTER; 

25 

26 

typedef  CHARACTER 

DISPLAY!  NUMROWS  ][  NUMCOLS  ]; 

27 

28 

static  DISPLAY  far  ‘Screen 

=  (DISPLAY  far  *)  VIDBASE; 

Table  1 
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ing  up  the  subject  of  lvalues  and 
pointers  once  more  (this  is  the  last  of 
it,  I  promise).  Steve  Hersee  (VP  of  mar¬ 
keting  at  Lattice  and  chair  of  the  ISO 
working  group  in  C)  sent  me  the  fol¬ 
lowing  paper.  It  was  written  by  Gary 
Merrill  and  Francis  Lynch,  also  of  Lat¬ 
tice.  Steve  points  out  that  the  letter 
was  submitted  to,  and  adopted  by  the 
ANSI  comittee,  so  I  guess  the  other  side 
wins.  1  hate  to  give  up  *(  (TIP  )++, 
though.  If  you  haven’t  already  you 
should  read  last  month's  column  for 
background.  The  letter  refers  to  sec¬ 
tions  in  an  early  draft  of  the  standard 
that  I  don’t  have  a  copy  of.  It’s  pretty 
understandable,  though,  even  with¬ 
out  the  standard  in  front  of  you,  and  it 
makes  some  good  points  about 
lvalues. 

Consequences  of  the 
Proposed  Standard 

The  decision  to  allow  an  ex¬ 
pression  of  the  form  (T)P  to  be 
an  lvalue  “for  purposes  of  addi¬ 
tive  operations  on  P"  (when  P  is 
an  lvalue  of  pointer  type  and  T 
is  the  name  of  a  pointer  type) 
appears  to  preclude  the  devel¬ 
opment  of  any  coherent  se¬ 
mantics  for  the  C  language  and 
to  prevent  its  implementation 
on  a  significant  class  of  ma¬ 
chine  architectures.  It  has  the 
virtue,  however,  of  bringing  to 
light  a  number  of  places  in  the 
proposed  standard  where  a 
lack  of  rigor  and  precision  tend 
to  leave  the  reader  in  a  state  of 
confusion.  While  this  decision 
may  initially  appear  plausible 
and  even  intuitively  correct, 
the  price  one  must  pay  for  it 
quickly  begins  to  seem  exces¬ 
sively  high,  if  not  prohibitive. 

Consider  the  following:  As¬ 
sume  that  P  is  an  lvalue  of 
pointer  type  and  T  is  the  name 
of  a  pointer  type.  Then  we 
know  by  the  above  principle 
(see  Section  4.2.4)  that,  within 
the  context  ++(T)P  (and  also 
within  the  context  (T)P+  +  ), 
the  expression  (TIP  is  an  lvalue. 

On  the  other  hand,  we  know 
from  Section  4.2.1  that  +  +(T)P 
is  equivalent  to  ((TIP  +=  1).  So, 
if  +  +(T)P  is  syntactically  (and 
semantically)  acceptable,  then 
so  is  ((TIP  +=  1).  We  also 
know  (Section  4.14)  that  +  =  re¬ 


quires  an  lvalue  as  its  left  oper¬ 
and,  so  everything  appears  to 
be  OK  so  far,  so  long  as  we 
agree  that  in  the  context  ((TIP 
+  =  1)  the  subexpression  (TIP 
is  being  used  “for  purposes  of 
additive  operations  on  P." 

Now  we  also  know  (Section 
4.14.2)  that  ((TIP  +=  1)  differs 
from  ((TIP  =  (TIP  +  1)  “only 
in  that”  (TIP  “is  evaluated  only 
once,”  and  if  this  is  the  only  dif¬ 
ference,  then  since  the  former 
is  acceptable  syntax,  so  is  the 
latter.  That  is,  we  have  just 
been  forced  to  regard 


(1)  (T)P  =  (TIP  +  1; 

as  a  perfectly  acceptable  C  ex¬ 
pression.  This  requires  us,  of 
course,  to  agree  that  the  first 
occurrence  of  (TIP  in  this  ex¬ 
pression  is  an  lvalue. 

Now  come  the  interesting 
questions:  if  (1)  is  correct,  then 
on  what  grounds  can  we  possi¬ 
ble  forbid 

(2)  (T)P  =  1  +  1; 
or,  in  general, 


Dr.  Dobb  s  Journal,  May  1986 


317 


C  CHEST 

(continued  from  page  21) 


(3)  (T)P  =  x; 

Our  only  hope  is  to  argue  that 
in  (2)  and  (3)  there  is  no  "pur¬ 
pose”  for  an  additive  operation 
on  P.  So  we  have  to  be  willing 
to  say  that  (1)  involves  an  addi¬ 
tive  operation  on  P  while  (2) 
does  not. 

But  this  does  not  really  make 
things  any  clearer.  How,  for  ex¬ 
ample,  do  we  tell  in  general 
whether  an  expression  is  being 
used  "for  the  purposes  of  addi¬ 
tive  operations  on  P?"  The  con¬ 
text  of  (1)  is  particularly  simple. 
Shall  we  impose  the  arbitrary 
condition  that,  in  order  for  (T)P 
to  be  considered  an  lvalue  in 
the  expression 

(4)  (TIP  =  E 

that  it  occur  as  a  subexpression 
in  E ?  What  is  the  possible  justi¬ 
fication  for  this  ad  hoc  excep¬ 
tion  to  an  otherwise  elegant 
and  uniform  grammar?  Cer¬ 
tainly  it  is  counterintuitive  and 
terribly  confusing  to  a  user  of 
the  language  to  insist  that  the 
left  occurrence  of  (T)P  in  (1)  is 
an  lvalue  but  its  left  occur¬ 
rences  in  (2)  and  (3)  are  not.  Is 
what  we  gain  worth  the  impo¬ 
sition  of  such  an  arbitrary  ex¬ 
ception  to  our  grammar  and 
the  resulting  confusion? 

Note,  incidentally,  that  the 
simple  approach  just  suggested 
will  not  work,  for  the  mere  oc¬ 
currence  of  (T)P  within  E  does 
not  ensure  that  it  is  used  "for 
the  purposes  of  additive  opera¬ 
tions  onP.”  It  may  occur  in  E  in 
such  a  way  that  its  value  is  nev¬ 
er  used  or  is  never  used  in  as¬ 
signing  the  new  value  of  (T)P. 

There  is  another  reason  that 
the  simple  approach  of  requir¬ 
ing  (T)P  to  occur  within  E  will 
not  work.  Suppose  that  P  is  a 
global  variable  and  we  have  de¬ 
fined  a  function/ such  that: 

(T)  f( ) 

( 

return!  (TIP  +  1 1; 

} 


Now  consider  the  expression 

(5)  (TIP  =  f(  I; 

Certainly  we  are  using  (5)  "for 
the  purposes  of”  an  additive 
operation  on  P.  Can  a  compiler 
be  expected  to  detect  this  pur¬ 
pose?  Even  if  the  definition  of 
f()  and  (5)  occur  in  different 
source  files?  To  answer  yes  to 
these  questions  is  to  demand  se¬ 
rious  revision  in  the  way  we 
conceive  of  C. 

The  Semantic  Problem 

Now  exactly  what  is  the  prob¬ 
lem  in  all  of  these  cases?  It  is 
that  an  attempt  has  been  made 
to  make  a  single  exception  to  an 
otherwise  general  and  formally 
correct  rule:  that  a  cast  expres¬ 
sion  (such  as  (T)P)  is  never  an 
lvalue.  There  are  very  good  and 
well-known  reasons  for  this 
rule,  and  they  follow  directly 
from  the  semantics  for  C. 

The  motivation  for  this  at¬ 
tempt  appears  only  to  be  a  de¬ 
sire  to  ensure  that  certain  dubi¬ 
ous  (at  best)  coding  practices 
[Humph! — AH]  will  be  tolerat¬ 
ed  by  any  compiler  conform¬ 
ing  to  the  proposed  standard.  It 
may  be  argued,  for  example, 
that  if  the  exception  is  not 
made,  then  a  certain  amount  of 
existing  code  will  fail  to  com¬ 
pile  under  a  standardized  com¬ 
piler.  This  may  be  true,  but  in 
light  of  the  consequences  of 
embracing  the  exception,  it  can 
hardly  be  looked  upon  as  a 
compelling  argument. 

The  totally  misguided  nature 
of  this  attempt  at  construing 
(T)P  as  an  lvalue  in  a  context- 
dependent  way  can  be  seen  in 
the  examples  described  above. 
The  most  immediate  problem  is 
the  appeal  to  "purposes”  in  a 
description  of  the  exception. 
Expressions  of  a  programming 
language  do  not  possess  intrin¬ 
sic  "purposes”  (though  those 
who  write  them  may  have  a 
purpose  in  doing  so,  of  course). 
An  appeal  to  "purposes”  has  no 
place  in  the  definition  of  a  pro¬ 
gramming  language  or  in  the 
document  purportedly  describ¬ 
ing  its  standard.  As  it  now 


stands,  the  proposed  attitude  to¬ 
ward  considering  (T)P  an  1- 
value  is  very  close  to  saying  that 
"(T)P  will  be  considered  an  lva¬ 
lue  when  the  programmer 
wishes  it  to  be  (ie.,  when  it  is  his 
or  her  purpose  to  use  it  as  an 
lvalue),  and  otherwise  it  will 
not  be  an  lvalue.”  Given  the  use 
of  "purposes,”  there  can  be  no 
pretense  at  creating  a  formally 
precise  standard  for  the  lan¬ 
guage  that  will  enable  compiler 
writers  to  implement  the  stan¬ 
dard  in  an  objective  manner. 

The  Machine  Problem 

Another  difficulty  with  consid¬ 
ering  (T)P  an  lvalue  (for  any 
purpose)  is  that  some  machine 
architectures  require  different 
representations  for  pointers  to 
different  classes  of  objects. 
Clearly  if  (T)P  forces  a  conver¬ 
sion  of  P  to  a  different  repre¬ 
sentation,  there  is  no  justifica¬ 
tion  whatever  for  regarding 
the  result  as  an  lvalue.  On 
word-addressed  machines,  the 
example  shown  in  4.2.4  cannot 
be  implemented  because  char¬ 
acter  pointers  are  simply  not 
congruent  with  pointers  to 
long  integers.  [A  better  exam¬ 
ple  is  the  8086  where,  in  the 
medium  model,  a  pointer  to 
data  can  be  32  bits  when  a 
pointer  to  a  subroutine  is  16 
bits. — AH]  Is  it  the  intention  of 
the  proposed  standard  to  pre¬ 
vent  the  implementation  of  its 
definition  of  C  on  such  ma¬ 
chines?  The  usefulness  of  C  is 
such  that  we  should  make  ev¬ 
ery  attempt  to  allow  its  imple¬ 
mentation  on  as  many  ma¬ 
chines  as  possible;  indeed,  one 
of  the  principal  purposes  of  a 
high-level  language  is  to  insu¬ 
late  programmers  from  the  id¬ 
iosyncrasies  of  the  underlying 
hardware.  While  no  attempt  to 
embrace  the  entire  spectrum 
of  existing  architectures  is  like¬ 
ly  to  be  successful,  surely  C 
should  not  be  limited  to  those 
machines  that  use  a  single 
pointer  representation  for  all 
objects?  It  is  true  that  word-ad¬ 
dressed  machines  present  seri¬ 
ous  problems  for  the  large 
body  of  existing  code  that  as- 
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sumes  a  single  pointer  type. 
The  standard,  however,  should 
be  sufficiently  general  that  it  is 
independent  of  any  assump¬ 
tions  of  this  kind. 

Possible  Solutions 

What  is  needed? 

1.  Replace  the  clause  "for 
purposes  of  additive  operations 
on  P"  with  a  formally  precise 
description  of  cases  in  which 
(T)P  is  an  lvalue.  We  do  not  be¬ 
lieve  this  can  be  done  without 
doing  violence  to  a  large  por¬ 
tion  of  the  sematics  of  C.  The 
price  is  simply  too  high. 

2.  Treat  (T)L  (where  L  is  an 
lvalue)  as  always  being  an  lva¬ 
lue.  The  arguments  are  well 
known  and  appear  to  be 
compelling. 

3.  Give  up  the  equivalences 
between  (++E)  and  (E  +  =l) 
and  between  (E  +  =l)  and 
(E=E  +  1)  that  allowed  us  to 
generate  the  problematic  ex¬ 
amples  above.  But  we  cannot 
simply  "give  up"  these  equiva¬ 
lences  since  they  are  a  conse¬ 
quence  of  the  semantics  for 
+  +,  +  =,  +,  and  =.  To  give 
them  up  would  not  only  be 
counterintuitive  but  also  would 
require  a  gross  revision  of  the 
semantics  of  the  operators  of  C. 
This  route  is  impossible. 

4.  Conform  to  the  currently 
accepted  principle  that  (T)L  is 
never  an  lvalue.  This  now  ap¬ 
pears  to  be  the  only  reasonable 
course,  and  our  strong  recom¬ 
mendation.  The  price  we  pay 
for  it  is  that  some  previously 
existing  code  that  has  been  ac¬ 
cepted  by  some  compilers  will 
no  longer  be  accepted  by  a 
standardized  compiler.  But  it  is 
hopeless  and  pointless  for  a 
standard  to  seek  to  preserve 
the  acceptability  of  all  previ¬ 
ously  existing  code.  The  price 
we  must  pay  for  embracing 
this  alternative  is  insignificant 
in  comparison  to  what  we 
would  have  to  pay  for  any  of 
the  others. 

June  8, 1984 

Gary  H.  Merrill  and 

Francis  L.  Lynch 


Putting  the  Shell  Level  into 
the  Unix  Prompt. 

The  MS  DOS  shell  presented  in  the  Jan- 
uary-March  C  Chests  makes  the  cur¬ 
rent  shell  level  available  in  an  envi¬ 
ronment  variable.  Unix  doesn’t. 
Nonetheless,  in  Unix  it's  possible  to 
create  an  almost  infinite  number  of 
nested  shells,  and  it’s  occasionally 
useful  to  know  the  current  level  of 
shell  nesting.  The  current  shell  level 
can  be  printed  by  the  Unix  C  Shell. 


This  is  done  using  the  program  in  List¬ 
ing  Two,  page  74,  in  conjunction  with 
the  shell  script  in  Listing  Three,  page 
74.  Listing  Three  shows  additions  you 
should  make  to  your  .cshrc  file. 

DDJ 

(Listings  begin  on  page  72.) 
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ARTICLES 


Human 

Interface 

Design: 

From  the  Outside  In 


Igot  into  the  user- 
interface  design 
business  by  acci¬ 
dent.  Early  in  1980, 
while  searching  for  a 
word  processing  pro¬ 
gram  for  my  own  use, 

I  came  across  one  that 
stood  well  out  from 
the  herd.  Naturally,  I  arranged  to  get  a  copy.  I  wanted  it 
for  drafting  a  sizable  manuscript  I  had  just  contracted  to 
do.  What  I  didn't  understand  in  making  my  impulsive 
commitment  to  this  program  was  that  it  was  still  under 
development.  I  became  an  unwitting  beta  tester. 

I  also  soon  discovered  that  this  thing  that  looked  so 
beautiful  and  seductive  on  first  meeting  revealed  some 
disagreeable  imperfections  at  a  closer  view.  The  develop¬ 
ers  offered  to  correct  some  of  the  design  flaws.  Soon  I 
became  their  impromptu  adviser  on  design  improve¬ 
ments — for  example,  in  the  case  of  a  tab-stop  setting  se¬ 
quence  that  came  up  with  a  “Column  Number? _ " 

prompt,  I  told  them:  "When  someone  wants  to  set  a  tab 
stop,  he  may  have  no  idea  of  what  column  number  he 
wants  it  in.  What  he  knows  is  that  he  wants  the  tab  stop 
here,”  and  I  pointed.  The  tab-stop  interface  was  changed 
to  one  where  the  user  pointed  via  cursor  to  the  desired 
column  for  the  tab  stop. 

Since  then,  my  involvement  in  user-interface  design 
has  become  more  formal.  For  one  thing,  I  started  a  soft¬ 
ware  company — Bruce  &  James  Inc.  My  big  design  effort 
so  far  has  been  B&J’s  flagship  product,  the  Wordvision 
word  processor  (actually  a  descendant  of  that  program  I 
volunteered  suggestions  for  earlier).  The  design  work  for 


The  Softer  Interface  Inc.,  2355  Leavenworth,  Ste.  103 
San  Francisco,  CA  94133 


Wordvision  extended 
throughout  the  pro¬ 
gram’s  15-month  de¬ 
velopment  cycle  and 
has  recently  resumed 
in  preparation  for  a 
new  edition. 

I  have  also  wrestled 
with  interface  designs 
for  several  other  Bruce  &  James  products,  released  and 
unreleased,  and  have  evaluated  interfaces  for  many 
other  companies'  products  in  the  Course  of  considering 
them  for  publication,  writing  about  them,  or  informally 
advising  their  developers. 

Most  recently  I  have  organized  a  company  with  the 
explicit  mission  of  assisting  others  with  user-interface  de¬ 
sign.  During  all  my  work  with  user  interfaces,  I  have 
been  seeking  tools  and  techniques  to  help  with  the  job. 
I’ve  wanted  to  find  things  that  would  enhance  my  cre¬ 
ativity  and  productivity  just  as  a  word  processor  has  aid¬ 
ed  my  writing.  I  have  tried  out  numerous  possibilities. 
Until  recently,  I  have  found  them  all  wanting. 

Pretenders 

My  first  tool  was  the  BASIC  language.  I  wrote  BASIC  pro¬ 
grams  to  make  prototype  screen  designs  and  to  change 
the  display  in  response  to  keystrokes.  This  was  laborious, 
particularly  when  the  screen  used  display  features  be¬ 
yond  simple  printing  of  text  and  when  it  needed  a  lot  of 
color  and  attribute  painting.  BASIC  (particularly  earlier 
versions)  just  isn’t  built  for  such  jobs. 

The  next  approach  was  inspired  when  I  showed  one  of 
my  BASIC  prototypes  to  Peter  Jennings,  a  founder  of  the 
former  software  giant  VisiCorp.  He  suggested  I  use  "sto¬ 
ryboards.”  The  idea  seemed  an  obvious  fit  because  I  had 
worked  in  TV  advertising,  where  the  storyboard — a  se¬ 
ries  of  drawings  sketching  out  the  sequence  of  key  im- 


by  Jim  Edlin 


DEMO  gives  you  a  chance  to 
noodle  through  a  dozen  different 
approaches  before  the 
programming  meter  starts  ticking. 
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ages  in  a  commercial — is  one  of  the  fundamental  tools  of 
the  trade. 

Eventually  I  used  the  storyboard  approach  to  develop 
many  of  the  preliminary  designs  for  Wordvision.  At  first, 
however,  I  found  storyboards  unsatisfactory  for  the 
same  reason  that,  after  adapting  to  word  processing,  I 
now  find  writing  on  paper  unpleasant.  Furthermore,  ad¬ 
vertising  storyboards  portray  generalities  of  visual  con¬ 
cepts;  in  software  I  wanted  to  work  down  to  the  level  of 
fine  detail.  Ink  on  paper  was  not  malleable  enough.  It 
also  didn't  have  a  useful  dimension  for  portraying  and 
experimenting  with  flow  of  control — that  part  of  the  in¬ 
terface  dealing  with  how  the  parts  relate  and  how  users 
move  among  them. 

The  flow-of-control  question  forced  me  to  my  next  ap¬ 
proach — a  repeatedly  reinvented  series  of  forms  on  pa¬ 
per.  These  contained  spaces  for  writing  in  a  description 
of  the  screen  display;  an  explanation  of  what  events 
could  cause  the  display  of  that  screen;  a  list  of  user  op¬ 
tions  while  on  that  screen;  a  description  of  other  screens 
or  actions  to  which  these  choices  would  lead;  and  a  space 
to  describe  audio,  animation,  and  other  happenings,  such 
as  use  of  peripheral  devices. 

The  form  kept  getting  revised  because  I  continued  to 
run  up  against  situations  that  demanded  entry  of  infor¬ 
mation  for  which  there  were  no  spaces  on  the  current 
version  of  the  form.  Nevertheless,  the  forms  acted  as  a 
sort  of  linked  list  and  furnished  fairly  definitive  instruc¬ 
tions  for  programming.  But  they  failed  to  give  an  overall 
sense  of  how  the  program  would  actually  operate  and 
"feel.” 

Eventually  the  forms  gave  way  to  a  system  of  diagrams 
and  notation  formalized  by  a  coworker.  We  maintained 
these  in  pencil  to  allow  for  the  inevitable  frequent  revi¬ 
sions.  The  resulting  binder  became  the  essence  of  a  user- 
interface  specification.  It  did  the  recording  job;  but  as  a 
designer's  tool,  it  was  as  cumbersome  as  the  intricate  no¬ 
tation  used  to  record  dance  compositions.  It’s  difficult  for 
me  to  imagine  a  choreographer  finding  it  more  produc¬ 
tive  and  rewarding  to  scribble  pages  of  intricate  nota¬ 
tions  than  to  observe  action  on  a  stage  as  he  instructs 
dancers  to  try  different  moves  and  sequences.  Likewise 
with  interface  design. 

In  1984,  I  finally  found  a  software  tool  for  designing 
interfaces — Window  Panes  by  Jim  Canright  ($160  from 
Softright,  P.O.  Box  132,  Beaverton,  OR  97075;  (503)  641- 
4072).  Window  Panes  added  a  lot  of  leverage  to  my  design 
toolbox.  It  consists  of  two  subprograms:  a  display  editor 
to  create  screen  designs  as  either  full  or  partial  windows, 
and  a  “walker"  to  create  and  edit  sequences  for  the  win¬ 
dows  created  with  the  editor.  The  sequences  can  be 
based  on  keystrokes,  on  elapsed  timings,  and  so  forth. 
With  Window  Panes,  it  is  possible  to  develop  prototypes 
of  both  screen  designs  and  flow  of  control  in  reasonable 
detail. 

Window  Panes  had  its  drawbacks,  though.  First,  be¬ 
cause  it  was  difficult  to  use,  I  never  did  quite  master  its 
intricacies.  Second,  every  screen  or  window  overlay  dis¬ 
play  called  for  a  separate  disk  access.  Although  it  operat¬ 
ed  speedily  with  a  RAMdisk,  the  business  of  getting  it  set 
up  with  access  to  the  right  files  every  time  was  an  annoy¬ 
ance.  I  don’t  want  to  downgrade  the  value  of  Window 


Panes;  I  considered  it  a  true  boon  when  it  arrived,  but  in 
actual  use  I  found  it  frustrating. 

The  version  of  Window  Panes  I  used  is  two  years  old. 
There  is  a  new  version  out  that  probably  has  improve¬ 
ments,  and  Canright  tells  me  a  still-newer  version  should 
be  out  by  the  time  this  article  is  published. 

After  Window  Panes,  the  next  tool  I  adopted  was  Say- 
what  ($39.95  from  The  Research  Group,  88  S.  Linden  Ave., 
South  San  Francisco,  CA  94080;  (415)  571-5019).  Saywhat  is 
a  screen  generator  originally  designed  for  building  dis¬ 
plays  for  dBASE  II  applications.  Later  The  Research 
Group  expanded  it  to  offer  the  same  abilities  for  Turbo 
Pascal  and  BASIC  programs  and  for  stand-alone  screens 
that  could  be  displayed  from  the  DOS  prompt  with  a  sup¬ 
plied  utility  program. 

For  designing  single  text-mode  screens,  Saywhat  is  im¬ 
pressive.  You  can  learn  it  easily  and  appreciate  its  ease  of 
use.  The  drawback  to  Saywhat  is  in  prototyping  for  flow 
of  control.  The  only  options  are  to  create  a  program  in 
one  of  the  languages  Saywhat  works  with  or  to  create  a 
DOS  batch  file  that  calls  up  one  screen  after  another  in 
sequence,  with  little  opportunity  to  explore  branching 
paths  or  go  backward.  And  every  screen  is  a  file,  no  mat¬ 
ter  what  program  you  use  it  with.  Once  again,  operation 
is  fast  only  if  you  use  a  RAMdisk,  and  even  then  it  clutters 
your  disk  with  files. 

Dan  Bricklin ’s  DEMO  Program 

Now  I  have  set  my  previous  tools  aside  in  favor  of  Dan 
Bricklin's  DEMO  Program,  the  new  prototyping  software 
by  the  well-known  co-creator  of  VisiCalc.  DEMO  ($74.95 
from  Software  Garden  Inc.,  P.O.  Box  238,  West  Newton, 
MA  02165;  (617)  332-2240)  is  the  outgrowth  of  a  tool  Brick¬ 
lin  developed  originally  for  his  own  use.  It  goes  a  long 
way  toward  the  tool  I  have  been  seeking — especially  at 
the  inexpensive  price,  which  I  applaud.  Had  DEMO  been 
available  when  we  began  work  on  Wordvision,  I  bet  we 
would  have  shipped  it  at  least  three  (financially  very  sig¬ 
nificant)  months  sooner. 

I  am  a  believer  in  the  "artistic,”  as  opposed  to  "engi¬ 
neering,”  model  of  program  design.  I  think  good  pro¬ 
grams  evolve  as  their  structure  fills  and  you  have  a 
chance  to  see  what  works  and  what  doesn’t.  But  some 
programmers  I  know  prefer  to  work  under  the  engineer¬ 
ing  model.  ("You  don’t  want  to  redesign  the  bridge  after  it 
is  halfway  built.”)  In  particular,  it  seems  to  me  program¬ 
mers  don’t  like  coding  interface  changes.  One  I  often 
work  with  refers  to  this  as  “shoelace  tying’’ 
programming. 

DEMO  gives  an  interface  designer  the  chance  to  noodle 
through  a  dozen  different  approaches  before  the  pro¬ 
gramming  meter  starts  ticking  and  before  any  expensive 
data  or  control  structures  get  built  that  would  be  expen¬ 
sive  to  revise.  Incidentally  DEMO  in  no  way  imposes  a 
user-interface  viewpoint  of  its  own,  except  for  the  im¬ 
plicit  one  of  the  choices  Bricklin  himself  has  made.  To 
illustrate  this,  the  sample  files  included  with  DEMO  show 
how  to  implement  the  interface  for  a  sample  task  in 
three  significantly  different  ways. 

A  Hot  Program 

Trip  Hawkins,  founder  of  Electronic  Arts,  has  enunciated 
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a  trinity  of  desirable  qualities  for  a  program:  hot,  simple, 
and  deep.  By  this  standard  I  rate  DEMO  in  the  high  per¬ 
centiles  for  both  hot  and  deep  and  a  bit  lower  but  still 
good  on  simple. 

Hawkins'  hot  criterion  can  be  interpreted  in  a  couple 
of  ways.  You  can  take  it  to  mean  raw  performance — jet- 
propelled  accomplishment  of  a  task  at  hand.  DEMO  cer¬ 
tainly  fits  that  bill;  for  one  thing,  it  can  jump  through  a 
series  of  full-screen  displays  as  fast  as  you  can  press  the 
keys  to  call  them  up.  Hot  can  also  mean  topical — filling  a 
need.  Some  work  is  not  worth  doing  at  all  until  the  prop¬ 
er  tools  exist  to  bring  the  job  down  to  reasonable  propor¬ 
tions — many  of  the  "what  if”  evaluations  now  done  with 
spreadsheets  probably  fall  into  this  category.  "What  if” 
experimentation  with  user-interface  approaches,  and 
fine  tuning  of  them,  may  also  have  fallen  in  this  catego¬ 
ry — until  DEMO. 

Now  let’s  talk  deep.  Frankly,  I  am  astonished  at  the 
depth  of  detail  and  refinement  Bricklin  has  worked  into 
his  first  release  of  DEMO.  On  occasion  after  occasion,  as 
the  words  “Wouldn't  it  be  nice  if . . started  to  take  form 
in  my  mind,  DEMO  provided  just  what  I  was  looking  for. 
(I  suppose  it  helps  to  have  beta  testers  of  the  ilk  of  Lotus’ 
Mitch  Kapor.) 

Suppose,  for  example,  you  want  to  print  faithful  im¬ 
ages  of  screen  designs  that  make  generous  use  of  line 
drawing  and  symbols  from  IBM’s  extended  character  set. 
And  suppose  your  printer  doesn't  have  a  character  set  to 
match.  DEMO  gives  you  a  mapping  feature  to  translate 
screen  characters  to  other  printer  characters  of  your 
choice.  You  can  even  map  individual  screen  characters  to 
character  sequences  on  the  printer,  using  a  backspace  to 
overprint  two  standard  characters  and  make  up  a  com¬ 
posite  that  approximates  to  one  of  the  special  IBM  set 
(such  as  a  caret  and  vertical  bar  to  make  an  up  arrow). 

A  variation  of  the  same  feature  lets  you  translate  your 
screen  designs  into  a  useful  form  for  inclusion  in  pro¬ 
gram  code.  You  can  direct  your  mapped  output  to  a  text 
file  instead  of  the  printer  and  specify  a  C  language  or 
Pascal  language  mapping,  which  turns  characters  out¬ 
side  the  normal  printable  set  into  syntactically  correct 
octal  or  hexadecimal  representations.  (A  hex  format  for 
assembly  language  is  curiously  absent.) 

The  fundamentally  right  thing  about  DEMO  is  that  it 
combines  rich  sets  of  tools  for  protyping  both  screen  de¬ 
signs  and  flow-of-control  structures  and  integrates  them 
into  a  conceptually  consistent  frame  of  reference  in 
which  it  is  easy  to  move  around.  There  is  no  perceptible 
border  to  cross  in  going  between  these  two  areas. 

User  Caring 

Beyond  this,  DEMO  possesses  a  caring  attitude  toward  the 
user  that  shows  throughout  the  program  in  such  touches 
as  allowing  you  to  rearrange  the  order  of  most  program 
lists  (macros,  save  areas,  and  slides).  When  you  are  draw¬ 
ing  lines,  DEMO  knows  what  characters  to  put  in  to  make 
a  proper  junction  when  you  draw  one  line  to  join  or  cross 
another. 

There  is  also  a  familiar  element  from  VisiCalc  that  con¬ 


tributes  mightily  to  this  program — one  you  might  call 
"point  and  shoot.”  In  the  same  way  as  you  might  build  a 
spreadsheet  formula  by  pointing  to  various  cells,  in  effect 
saying  "multiply  this  times  ( .  .  .  scroll,  scroll,  scroll,  point 
. .  .  )  that,”  you  can  build  a  screen  sequence  in  DEMO  by 
flipping  through  the  screens  until  you  see  the  one  you 
want  and  pressing  a  key  to  say  "that  one.” 

Two  other  things  Bricklin  does  right  are  to  make  it  easy 
to  get  maximum  mileage  out  of  your  work  by  reusing  it 
as  often  as  is  applicable  and  to  conserve  your  resources 
with  this  program’s  analog  to  the  “sparse  matrix”  ap¬ 
proach  for  spreadsheet  data  storage  (where  no  memory 
is  used  by  cell  addresses  that  have  no  real  contents).  The 
power  to  reuse  work  grows  out  of  the  Overlay  features, 
which  allow  you  to  design  only  one  or  a  few  basic 
screens,  then  modify  them  with  overlays  that  can  have 
areas  with  both  “opaque”  and  "transparent”  areas.  (In 
the  former,  the  underlying  display  is  blocked  out;  in  the 
latter  it  shows  through.) 

My  company's  programs  typically  use  a  menu-tree 
structure  in  which  soft  function  key  legends  across  the 
bottom  of  the  screen  change  as  the  user  travels  through  a 
set  of  menu  options.  For  a  sequence  such  as  this,  I  can 
paint  in  the  basic  screen  and  then  create  half  a  dozen 
overlays  that  pop  into  place  in  the  function  key  display 
area  when  activated  by  my  specified  keypresses. 

I  don’t  want  to  give  the  impression  that  there  is  nothing 
wrong  with  DEMO.  Befinements  and  extensions  could 
keep  Bricklin  busy  for  a  long  time.  Perhaps  the  major 
limitation  at  the  moment  is  that  DEMO  is  restricted  to  text 
mode.  For  people  working  primarily  or  exclusively  with¬ 
in  text  mode,  this  is  not  really  a  limitation  at  all.  As  pow¬ 
erful  graphics  displays  grow  more  common,  however, 
and  to  the  extent  that  windowing  environments  play  an 
increasing  role,  it  will  become  more  important  for  this  or 
a  similar  tool  to  address  the  graphics  universe.  (I  sure 
would  love  to  see  DEMO  ported  to  the  Mac  and  Atari  ST!) 

I  think  DEMO  is  weaker  than  it  could  be  in  the  area  of 
screen  painting,  particularly  attributes  but  also  ease  of 
putting  in  line  and  symbol  characters.  Macros  (both  built- 
in  and  from  a  RAM-resident  key  macro  product)  can  help 
this,  but  the  basic  weakness  remains. 

Although  DEMO  is  fairly  "modeless”  (that  is,  key  com¬ 
binations  usually  do  what  you  expect  regardless  of  what 
phase  of  the  program  you  are  in),  there  is  still  cleanup  to 
be  done.  An  example  is  after  pressing  Esc-B  to  bring  up 
the  Block  menu,  you  can’t  move  the  cursor  before  press¬ 
ing  B  again  to  begin  the  block. 

Also,  the  Handler  capabilities  (which  let  you  specify 
which  keystrokes  or  events  produce  which  displays  or 
actions)  aren't  comprehensive  yet — for  example,  many 
programs  use  soft  function  key  displays  that  change 
when  you  press  the  Shift  (or  Ctrl  or  Alt)  key.  So  far,  DEMO 
can’t  do  handlers  responding  to  these  and  other  signifi¬ 
cant  key  actions.  It  also  can't  do  much  in  the  sound  area 
beside  beep  and  do  simple  note  sequences. 

Law-Rent  Documentation 

DEMO’s  documentation  and  packaging  is  self-consciously 
plain  and  low-  rent.  The  manual  is  30  pages  of  8V2  X  11- 
inch,  corner-stapled  and  instant-printed  output  from 
Bricklin's  NLQ  dot-matrix  printer.  Its  contents  are  orga- 
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nized  to  mirror  the  menus  and  submenus  of  the  pro¬ 
gram’s  command  structure. 

This  documentation  approach  is  one  that  is  often  used, 
particularly  in  lower-priced  programs.  It  is  essentially  an 
extension  of  the  Kapor/Lotus-style  on-screen  interface 
that  displays  a  set  of  command  words  in  a  menu  and 
offers  the  ability  to  scroll  through  sentence-length  expla¬ 
nations  for  the  significance  of  each  command  word.  The 
paper  documentation  in  this  scheme  takes  the  same  idea 
one  level  further;  each  command  gets  from  one  to  sever¬ 
al  paragraphs  of  elaboration,  noting  all  the  dos,  don’ts, 
and  special  cases.  This  approach  works  for  getting  the 
detail  into  a  place  where  it  is  accessible  for  reference,  but 
I  have  always  found  it  lacking  in  the  ability  to  explain 
how  to  use  the  program  to  achieve  a  user's  goals.  Bricklin 
is  blunt  about  saying  his  program  is  designed,  aimed,  and 
packaged  for  those  with  the  knowledge  and  motivation 
to  make  proper  use  of  it.  At  least  the  documentation  is 
clearly  and  simply  written  and  seems  not  to  miss  much 
necessary  detail. 

Incongrously,  whereas  DEMO’s  packaging  and  posi¬ 
tioning  is  aimed  squarely  at  programmers,  Bricklin 
seems  to  harbor  ambitions  of  also  selling  it  in  the  slide- 
show  and  training-system  market.  DEMO’s  capabilities 
certainly  make  it  appropriate  there,  but  users  who  want 
to  use  it  for  such  purposes  will  have  to  overcome  docu¬ 
mentation  not  aimed  at  them.  To  accommodate  custom¬ 
ers  in  this  market,  Bricklin  is  considering  some  new  pric¬ 
ing  options.  One  possibility  is  an  unlimited  license  to 
include  RUNDEMO  with  a  single  slide  show  for  a  flat  fee 
of  $1,000. 

A  Little  Taste  of  DEMO 

To  give  some  flavor  of  what  DEMO  can  do  and  how  it 
works,  I  used  it  for  a  small  project  and  noted  my  steps  as  1 
went.  Rather  than  building  something  from  scratch,  I  ex¬ 
perimented  with  possible  refinements  to  an  existing  pro¬ 
gram.  For  fun,  I  picked  Zoomracks,  a  program  designed 
by  Paul  Heckel,  author  of  The  Elements  of  Friendly  Soft¬ 
ware  Design  (New  York:  Warner  Books,  1984)  and  some¬ 
thing  of  a  guru  on  the  subject  of  user  interfaces. 

Zoomracks  (described  in  DDJ ,  November  1985)  uses  a 
card-rack  metaphor.  A  main  feature  of  the  program  is  its 
ability,  when  you  depress  one  key,  to  switch  its  view 
(zoom)  between  compressed  views  of  several  informa¬ 
tion  racks  and  a  full  view  of  a  selected  rack.  Within  a 
given  rack,  a  similar  feature  lets  you  zoom  between  a 
summary  top-line  view  of  all  cards  in  the  rack  and  a  full 
view  of  a  selected  card.  I  like  these  concepts  but  suspect¬ 
ed  the  screen  visuals  Heckel  uses  to  present  them  might 
benefit  from  some  refinement.  I  used  DEMO  to  test  my 
theory. 

First  I  loaded  the  Capture  utility  provided  on  the  DEMO 
disk.  This  remains  resident  in  memory  and  lets  you  im¬ 
port  screens  from  other  programs  into  DEMO.  When 
Capture  returned  me  to  the  DOS  prompt,  1  loaded  Zoom- 
racks,  manipulated  it  to  show  the  first  example  screen  I 
wanted  to  tinker  with,  and  pressed  both  Shift  keys  at 
once.  Capture  beeped  to  acknowledge  it  had  taken  a 


snapshot  of  the  screen.  I  then  ran  Zoomracks  through  the 
other  three  screens  1  wanted  to  work  with  (one  view 
each  way  of  both  the  card  zoom  and  rack  zoom),  captur¬ 
ing  each  in  the  same  way. 

Exiting  from  Zoomracks  to  DOS,  I  then  started  DEMO 
itself.  From  DEMO’s  opening  screen,  I  pressed  Esc  for  the 
main  command  menu,  I  for  the  I/O  menu,  and  R  for  Re¬ 
trieve.  Immediately,  the  first  of  my  four  screens — the 
multicard,  multirack  display — popped  into  view.  In  DE¬ 
MO’s  terminology,  this  screen  was  my  first  slide. 

The  sequence  Esc-R-H  led  me  through  the  Run  menu  to 
the  Handlers  menu  for  my  first  slide.  Handlers  specify 
what  DEMO  should  do  from  a  given  slide  upon  the  occur¬ 
rence  of  various  events.  Pressing  the  I  key  told  DEMO  to 
insert  a  new  handler  for  that  slide.  A  new  menu  display¬ 
ing  possible  events  popped  on-screen;  from  it  I  chose 
pressing  the  FI  key  as  the  event  that  would  define  a 
handler. 

A  menu  of  possible  actions  popped  up.  The  V  key  told 
DEMO  that  I  wanted  to  view  another  slide  if  FI  was 
pressed  while  the  current  slide  was  showing.  DEMO, 
guessing  I  might  want  the  next  slide  in  the  series,  showed 
it  to  me  with  a  small  menu  overlaid  on  one  corner.  My 
options  were  to  press  Return  if  that  was  the  slide  I  want¬ 
ed  brought  up,  or  to  use  FI,  F2,  or  other  search  options  to 
bring  my  choice  into  view.  Because  I  wanted  the  third 
slide  in  my  sequence — the  multicard,  single-rack  view — I 
used  F2  to  bring  it  up  and  Return  to  select  it. 

Back  on  my  starting  slide,  I  pressed  Esc-R-R  (the  Run 
option  from  the  Run  menu)  to  try  out  my  new  handler. 
The  first  slide  showed,  I  pressed  FI,  and,  zap — there  was 
my  zoomed-out  view. 

Ctrl-Break  put  me  back  in  Edit  mode,  and  I  ran  through 
the  handler  sequence  again  to  say  that,  if  FI  were  pressed 
while  viewing  this  slide,  the  earlier  slide  should  be 
shown.  I  then  went  into  the  Run  mode  again  to  try  it  out. 
Success!  Pressing  FI  now  bounced  me  back  and  forth  be¬ 
tween  the  zoomed-in  and  zoomed-out  views,  just  like  in 
the  real  Zoomracks  program.  After  three  minutes  of 
work,  I  had  a  simulation  duplicating  a  main  feature  of 
Zoomracks.  It  took  me  another  couple  of  minutes  set  up 
the  handlers  to  simulate  the  card  zoom  features  of  Zoom- 
racks’  F2  key. 

Then  I  went  back  to  the  original  slide  to  try  my  hand  at 
visual  redesign.  I  thought  1  would  change  Heckel’s  menu 
line  at  the  bottom  into  a  pull-down  menu  from  the  top 
instead.  Moving  the  cursor  to  the  menu  line,  I  pressed 
Esc-B-B  for  the  Begin  choice  from  the  Block  menu.  A  one- 
character-size  box  appeared,  and  I  used  cursor  keys  to 
expand  it  around  the  whole  menu  line,  then  pressed  Re¬ 
turn  to  complete  the  selection  and  pressed  S  for  save.  I 
used  this  Named  Save  Area  feature  rather  than  just  cut¬ 
ting  and  holding  the  menu  in  the  normal  cut/paste  buff¬ 
er  because  I  would  need  to  do  another  block  operation  to 
make  space  where  I  wanted  the  menu  to  go.  A  short  se¬ 
ries  of  keystrokes  let  me  create  a  new  save  area,  name  it 
Menu,  and  put  the  menu  line  into  it. 

Using  the  Block  feature  again,  I  selected  the  top  three- 
quarters  of  the  screen  and  used  the  Move  option  to  push 
it  down  a  few  lines,  making  room  for  the  menu  at  the 
top.  Then  I  pasted  the  menu  into  the  new  space.  Next,  a 
flurry  of  editing  and  attribute  painting  restyled  the  menu 
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to  my  taste.  For  the  last  step  on  the  menu,  I  wanted  to  use 
a  graphics  character  for  visual  separation  between  each 
selection.  Pressing  Esc-T-C  (for  Typing,  Characters) 
brought  up  a  menu  displaying  special  characters,  and  a 
few  more  keystrokes  selected  my  choice. 

I  needed  to  use  the  graphics  character  several  times  for 
the  menu  and  found  the  keystroke  sequence  for  getting 
one  character  to  be  excessive.  The  second  time,  before 
starting,  I  pressed  Shift-F6  to  turn  on  the  Macro  Learn 
mode.  Responding  to  a  prompt,  1  assigned  the  sequence 
to  the  Alt-1  key  then  typed  the  usual  sequence  to  get  my 
graphics  character.  Ctrl-Break  ended  the  macro  defini¬ 
tion.  Thereafter,  I  could  get  my  graphics  character  just  by 
pressing  Alt-1. 

The  final  experiment  I  wanted  to  try  was  to  give  more 
visual  impact  to  the  zoom  process.  I  wanted  to  keep  some 
reminder  of  the  unzoomed  racks  even  when  a  selected 
rack  was  zoomed  out  to  occupy  the  whole  width  of  the 
screen.  Using  Block  functions  and  editing,  I  did  some  sur¬ 
gery  on  the  lines  at  the  top  of  the  multirack  screen  that 
showed  the  rack  structure.  Then  I  copied  these  lines  into 
the  paste  buffer,  switched  the  view  to  the  single-rack 
screen,  and  pasted  the  new  lines  in  place.  A  little  more 
tinkering  and  I  had  the  visual  effect  I  wanted. 

I  gave  some  thought  to  prototyping  a  little  animation 
instead  of  just  flipping  instantly  from  the  multirack 
screen  to  the  single-rack  screen.  It  would  have  been  easy, 
starting  with  the  two  slides  I  had  and  using  DEMO's  over¬ 
lay  and  handler  features.  But  I  suspected  the  15  minutes 
of  work  I  had  already  done,  if  actually  implemented  for 
Zoomracks,  would  cost  hours  or  days  of  coding  to  accom¬ 
plish;  so  I  decided  to  let  well  enough  alone. 

With  an  Esc,  an  I,  and  an  S,  my  work  so  far  was  saved  to 
a  disk  file.  Included  in  the  file  were  my  macro  for  typing 
the  graphics  character  and  the  named  save  area  for  the 
menu  line. 

If  I  so  desired,  I  could  then  have  made  up  a  disk  for 
Heckel  with  that  file  and  with  one  of  my  50  alloted  copies 
of  the  RUNDEMO  program  that  comes  with  DEMO.  Al¬ 
though  Heckel  could  not  modify  any  of  my  prototype 
work  without  having  his  own  copy  of  DEMO,  RUNDEMO 
would  allow  him  to  view  my  suggestions  on  his  comput¬ 
er  and  to  run  as  often  as  he  liked  through  all  the  se¬ 
quences  I  had  defined  for  the  FI  and  F2  keys. 
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J'ef  Raskin's  involvement  with 
personal  computer  user-inter- 
face  design  is  hardly  recent.  In 
early  issues  of  DDJ,  he  inveighed 
against  needlessly  complex  systems. 
At  Apple  Computer,  he  wrote  many  of 
the  company 's  product  manuals.  Later 
he  was  a  member  of  the  original  Mac¬ 
intosh  design  team.  Today  he  is  the 
founder  of  Information  Appliance  of 
Menlo  Park,  California,  which  cur¬ 
rently  offers  a  product  called  Swyft- 
Cardfor  the  Apple  lie  and  lie.  DDJ  will 
review  SwyftCard  next  month. 

Raskin  cares  tremendously  about 
user-interface  design,  on  computers 
and  elsewhere.  During  our  discussion 
he  said,  "As  a  person  I'm  easily  frus¬ 
trated.  I'm  very  annoyed  at  the  little 
things  that  most  people  put  up  with." 
He  got  up  and  walked  out  of  the  door, 
shutting  it  behind  him,  and  immedi¬ 
ately  opened  it  and  reentered  the 
room.  "What  a  nuisance!  If  I  had  two 
bags  of  groceries  and  a  locked  door! 
The  door  is  a  very,  very  bad  design! 
Someone  will  have  to  improve  it.  But 
we're  so  accustomed  to  it  that  we 
don 't  think  about  it. " 

If  Raskin  doesn't  like  doors  in  build¬ 
ings,  does  that  mean  windows  on  com¬ 
puters  are  also  unacceptable ?  In  the 
following  interview  with  DDJ,  he  dis¬ 
cusses  a  wide  range  of  issues  concern¬ 
ing  user-interface  design. 

DDJ:  For  how  long  have  you  been 
thinking  along  human-interface  de¬ 
sign  lines? 

Raskin:  When  I  was  a  computer  cen¬ 
ter  director  at  UC  San  Diego,  there 
was  a  major  computer  center  with  a 
huge  machine.  I  built  another  center. 
It  didn't  have  fluorescent  lights.  It 
used  minicomputers — the  very  early 
Data  General  Nova — and  it  was  time 
sharing.  Instead  of  submitting  things 


by  DDJ  Editors 


When  I  go  to  a 
conference  and  tell 
people  why  I  hate  a 
mouse  I  get  applause. 


on  punch  cards  in  the  big  computer 
center,  you  could  come  over  to  this 
little  computer  center  I  had  built, 
and  there  were  32  terminals,  bean- 
bag  chairs,  and  incandescent  lighting 
with  Japanese  globes.  You  had  indi¬ 
vidual  terminals  to  work  on.  Stu¬ 
dents  loved  it.  Even  people  from  the 
big  center  would  come  over  to  use  it. 

We  also  had  a  language  called 
FLOW,  which  had  only  six  or  seven 
commands  and  was  very  good  for 
teaching  programming.  So  working 
on  better  language  design  and  the 
whole  ergonomic  question  dates 
back  to  the  60s,  when  everyone  else 
was  looking  at  anything  but  that. 

DDJ:  Can  you  identify  some  of  the 
important  criteria  in  the  design  of 
user  interfaces? 

Raskin:  In  any  user  interface  there's 
an  almost  unquantifiable  factor  of 
feel.  And  this  is  something  I  find  so 
hard  to  explain.  You  can  only 
achieve  it  by  massive  testing  on  hu¬ 
man  beings. 

DDJ:  Like  with  SwyftCard? 

Raskin:  SwyftCard  is  a  little  product 
for  the  Apple  II,  and  we  tested  it  on 
1,500  people.  There  were  focus 
group  tests,  one-on-one  tests.  There 


were  small-group  tests.  There  were 
tests  in  schools.  We  learned  a  lot.  We 
made  a  lot  of  changes  and  did  a  lot  of 
fine-tuning. 

DDJ:  But  you  started  with  something 
close  to  the  product's  current  user  in¬ 
terface.  You  had  a  preconception  of 
what  would  work,  didn't  you? 
Raskin:  I’ve  been  concentrating  on 
the  question  of  how  to  make  systems 
feel  good  for  18  years  now.  Some¬ 
times  that  kind  of  concentration  pro¬ 
duces  ingrown,  moribund  ideas,  and 
sometimes  it  produces  results.  I  think 
in  this  case  it  has  produced  results. 

DDJ:  Besides  feel? 

Raskin:  There’s  habit,  and  here 
we’re  on  better  theoretical  ground.  A 
system  should  allow  a  person  to 
form  habits.  There  are  two  funda¬ 
mental  principles  that  help  people 
form  habits.  One  of  them  is  well 
known  in  this  industry,  and  that  is 
making  things  modeless.  It’s  just  a 
fact  of  life  that  people  can't  keep 
track  of  modes.  You  make  mode  er¬ 
rors  when  you  think  you’re  doing 
one  thing  and  you  press  a  key  but 
because  you’re  in  the  operating  sys¬ 
tem  and  not  the  editor,  the  system 
does  something  else.  I  remember  in 
the  old  UCSD  Pascal  system,  I  would 
sometimes  press  E  for  exiting,  and  in 
some  other  place,  it  meant  execute — 
it  would  try  to  execute  a  letter  to  my 
mother  or  something.  You  can  imag¬ 
ine  the  kinds  of  Pascal  syntax  errors 
you  get  from  a  letter  to  your  mother! 

DDJ:  No  modes.  That  sounds  like  an 
underlying  rule. 

Raskin:  If  a  system  is  modeless,  then 
you  develop  habits.  If  you  want  to  do 
something,  you  just  reach  and  do  it 
that  way — you  don’t  get  frustrated. 


32 


Dr.  Dobb's  Journal,  May  1986 

325 


Modelessness  has  never  been  de¬ 
fined  satisfactorily.  It  means  that  a 
given  action  has  one  and  only  one  re¬ 
sult.  When  you  put  the  definition  in 
that  form,  you  can  easily  form  a  con¬ 
verse:  To  get  a  particular  result,  you 
want  one  and  only  one  action.  If 
that’s  the  case  then  you  don't  have 
these  branches.  If  you  read  Stewart 
Card’s  book  The  Psychology  of  Hu¬ 
man  Computer  Interaction  (Hillsdale, 
N.J.:  Lawrence  Erlbaum  Associates), 
one  of  the  better  books  in  the  field, 
you  find  a  lot  of  the  time  you  take 
isn't  the  doing  time  but  the  thinking 
time — working  out  a  path.  How  am  I 
going  to  get  there  from  here?  If  you 
have  only  one  way  to  do  something, 
then  you  don’t  have  to  think  about 
that.  You  can  form  habits  even  faster. 
If  it’s  modeless  your  habits  won’t  trip 
you  up.  In  the  industry  we  call  this 
other  property  monotony  for  lack  of 
any  other  name.  It  means  for  a  par¬ 
ticular  action,  we  try  to  have  one  and 
only  one  way  to  do  it.  If  a  system  is 
modeless  and  monotonous,  then  you 
can  form  habits  because  whenever 
you  want  to  do  something  you  al¬ 
ways  do  the  same  thing.  It’s  like  tying 
your  shoe.  Imagine  if  every  Thurs¬ 
day  your  shoes  exploded  if  you  tied 
them  in  the  usual  way.  This  happens 
to  us  all  the  time  with  computers, 
and  nobody  thinks  of  complaining. 

DDJ:  So  you  have  no  modes,  plain 
and  simple? 

Raskin:  We  actually  did  deliberately 
introduce  one  mode.  We’re  not  so 
doctrinaire  that  we  won’t  do  some¬ 
thing  when  it  does  make  sense.  But 
our  system  is  largely  monotonous. 
There’s  generally  only  one  way  to  do 
things.  I  remember  reading  a  de¬ 
scription  of  a  system  where  the  de¬ 
velopers  said,  whenever  they  had  a 
disagreement  about  how  something 
should  be  done,  they  did  it  both 
ways.  That’s  not  a  design  decision. 

DDJ:  As  in  whether  to  use  a  mouse  or 
command  keys? 

Raskin:  Usually  if  you  can’t  decide 
which  way  is  better,  it  means  you 
haven't  found  a  good  way  to  do  it.  On 
the  Macintosh  there’s  almost  always 
a  way  of  getting  around  the  mouse 
by  using  the  keyboard.  This  should 
have  given  the  designers,  after  I  left, 
the  hint  that  maybe  the  mouse  was 
not  the  right  way  to  do  it.  If  you’re 


always  looking  for  a  way  around  it, 
you've  obviously  got  some  kind  of 
problem. 

DDJ:  Documentation  has  always 
been  a  specialty  of  yours.  Does  it  en¬ 
ter  into  your  definition  of  the  user 
interface? 

Raskin:  Our  user  manual  has  some¬ 
thing  interesting  in  it;  aside  from 
having  schematics  and  the  usual  the¬ 
ory  of  operation,  here’s  something 
I’ve  never  seen  in  any  other  manual 
that  I've  ever  looked  at — the  user-in¬ 
terface  theory  of  operation,  or  how 


we  designed  the  user  interface. 

DDJ:  You  believe  the  user  must  un¬ 
derstand  the  theory? 

Raskin:  No,  I  don’t  feel  the  user 
needs  to  know.  I  know,  as  a  reader  of 
manuals,  I  often  wonder:  Why  do 
they  do  this?  How  did  this  come 
about?  You  can  use  the  system  with¬ 
out  reading  any  of  the  theories  of  op¬ 
eration.  You  can  learn  the  system  by 
reading  about  40  pages.  Some  people 
learn  it  from  a  reference  card.  We 
have  only  five  commands.  We  could 
have  had  a  manual  that  just  ex- 
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plained  the  five  commands.  But  this 
manual  is  part  of  our  user  interface. 

Let’s  talk  about  manuals.  We  have 
a  long,  cross-referenced,  handmade 
index.  A  lot  of  work  went  into  this. 
Before  we  did  this  we  typeset  the 
manual  for  testing  because  we  want¬ 
ed  people  to  feel  they  had  a  finished 
product.  Then  we  got  feedback  not 
only  on  the  product  but  also  on  the 
manual,  so  what  people  get  as  our 
first-edition  manual  is  a  tested  man¬ 
ual.  Manuals  are  an  integral  part  of 
the  product,  not  an  afterthought. 
This  whole  product  was  designed 
from  the  very  beginning  with  the 
manual  in  mind.  In  fact,  the  very 
first  thing  I  did  when  I  started  the 
company  was  write  my  dream  man¬ 
ual  for  this  product.  Then  I  built  it 
and  finally  wrote  a  real  manual. 

DDJ:  That  brings  to  mind  Apple's  ad 
that  boasts  of  the  minute  amount  of 
documentation  needed  to  learn  the 
Mac  compared  to  an  IBM  computer. 


Raskin:  Our  first  idea  was  to  have  a 
thin  manual.  We  tried  that — experts 
said,  "Wonderful,”  but  beginners 
said,  “I  don’t  know  what  I'm  doing.” 
If  you  say  that  an  insert  command 
undoes  the  latest  block  delete,  people 
may  have  forgotten  what  a  block  de¬ 
lete  is  and  insert  is  a  funny  word.  We 
wrote  the  manual  so  we  explained 
everything.  If  we  had  to  explain 
something  five  times,  we  explained  it 
five  times.  Don’t  get  lazy  in  the 
manual! 

DDJ:  Beyond  modelessness  and  mo¬ 
notony  what  else  do  you  have  in 
mind  as  you  develop  a  product? 
Raskin:  One  of  the  most  important 
concepts  is  that  things  you  do  fre¬ 
quently  must  be  fast.  Things  that  you 
do  infrequently  can  be  slower.  Peo¬ 
ple  have  critiqued  our  way  of  setting 
the  widths  of  paragraphs,  saying  it 
seems  a  little  baroque,  but  you  hard¬ 
ly  ever  do  it.  One  thing  you  do  very 
often  is  move  the  cursor,  and  one  of 
the  big  advances  of  this  product  is 
the  cursor-moving  mechanism.  This 
was  not  theoretical.  It  hit  me  while 


driving  through  Marin  with  my 
wife.  No  amount  of  theoretical  analy¬ 
sis  will  give  you  a  better  system  with¬ 
out  inspiration.  I  know  of  no  way  of 
automating  that  process. 

DDJ:  But  you  began  with  an  antipa¬ 
thy  toward  the  mouse? 

Raskin:  I  happen  to  hate  mice,  and  I 
have  since  1973  when  I  first  started 
using  them  at  Xerox  PARC.  I  always 
preferred  joysticks.  I  did  want  a  dif¬ 
ferent  cursor-moving  mechanism  on 
the  Macintosh.  That  was  designed  as 
a  graphic  machine,  and  you  do  need 
a  graphic  cursor-moving  device. 
SwyftCard  is  nongraphic  and  doesn't 
need  a  graphic  device.  (At  this  point 
Raskin  started  to  demonstrate  the 
SwyftCard  while  he  talked. ) 

First  of  all,  it  does  not  require  you 
to  move  your  fingers  from  home 
row,  and  it  uses  your  thumbs,  which 
are  under-utilized  fingers.  Even  in 
touch-typing  the  right  thumb  is  used 
for  the  space  bar  only;  the  left  thumb 
does  nothing.  Strangely  enough,  the 
Dvorak  keyboard,  for  all  its  supposed 
efficiencies,  doesn’t  use  the  thumbs 
either. 

To  get  anywhere  in  about  20  pages 
of  text,  you  have  to  type  an  average 
of  3V2  characters.  Research  has 
shown  that  with  cursor-moving  keys 
the  average  time  is  around  ten  sec¬ 
onds,  and  with  the  mouse  it  drops  to 
around  four  seconds.  Here  it  drops  to 
around  a  second.  So  it’s  somewhere 
between  two  and  four  times  faster 
than  a  mouse,  and  it’s  a  heck  of  a  lot 
less  expensive  to  manufacture. 

DDJ:  Had  you  seen  anything  like  this 
that  helped  you  in  the  early  stages  of 
development? 

Raskin:  No,  after  I  designed  this  I 
learned  about  the  Find  command  in 
EMAX,  which  is  also  an  incremental 
search.  It  has  a  few  problems:  First  of 
all,  you  have  to  go  into  Find  mode; 
and  second,  it  ends  up  on  the  last 
character  of  the  pattern,  which  is  a 
big  mistake.  The  other  thing  with 
EMAX  is,  when  you  leap  somewhere 
and  you  start  typing,  you're  still  add¬ 
ing  into  the  pattern.  So  it's  modal, 
and  it  puts  you  on  the  last  character. 
It's  only  one  direction. 

Let  me  make  a  typical  error.  I  want 
to  move  the  cursor  to  the  word  good, 
so  I  should  press  the  left  Leap  key 
and  type  "good.”  I'll  press  the  right 


34 


Dr.  Dobb's  Journal,  May  1986 

327 


HUMAN  INTERFACE 

(continued  from  page  34) 


Leap  key  and  type.  It  found  it  any¬ 
way.  The  system  does  one  thing  that 
all  systems  should  have  done  from 
day  1:  If  you  tell  it  to  search  one  way 
for  something  and  it  doesn't  find  it,  it 
searches  the  other  way  in  case  you 
made  a  mistake.  Most  systems  didn’t 
do  this  because  if  you  did  find  it  then 
you've  lost  your  place.  In  this  system 
if  you  want  to  go  back,  you  just  bang 
on  the  keyboard.  (Raskin  slams  both 
hands  on  the  keyboard,  and  the  cur¬ 
sor  returns  to  the  point  in  the  docu¬ 
ment  at  which  his  search  began. ) 

The  other  thing  about  this  system 
that  allows  us  to  use  this  paradigm  is 
that  the  longest  search  and  display 
through  all  the  text  takes  300  milise- 
conds.  Cursor  motion  is  very  impor¬ 
tant,  and  we’ve  got  it  better  than  any¬ 
one.  Speed  is  very  important,  and 
here  on  a  stupid  old  6502  running  at  1 
megahertz,  we  re  moving  the  screen 
and  doing  things  faster  than  you  will 
see  on  any  computer  from  any  man¬ 
ufacturer  at  any  price  with  any¬ 
body’s  software. 

DDJ:  On  the  Mac  development  team, 
was  there  an  absence  of  theoretical 
drive? 

Raskin:  The  original  team  was  Bud 
Tribble  and  myself  for  software  de¬ 
velopment.  When  Steve  took  over, 
Bud  Tribble  left.  And  I  left.  He  then 
brought  in  a  group  of  people  who  es¬ 
sentially  implemented  a  standard  op¬ 
erating  system  and  just  put  a  differ¬ 
ent  appearance  on  the  front  of  it. 
There  was  a  strong  theoretical  drive 
initially;  all  the  people  who  were  do¬ 
ing  that  left.  Our  name  for  the  word- 
processing  program  you  get  with  the 
Macintosh  is  Macwait.  If  a  little  clock 
ever  appears  on  a  computer  of  mine, 
I’ll  shoot  it.  A  computer  is  supposed 
to  be  fast. 

DDJ:  Could  you  talk  about  the  cursor 
design  on  SwyftCard? 

Raskin:  One  of  the  things  we’ve 
done  is  we’ve  paid  a  lot  of  attention 
to  details  people  have  taken  for 
granted  for  years.  The  way  I've  got¬ 
ten  out  of  my  ruts  is  by  watching 
people  try  to  learn  to  use  our  own 
systems.  The  cursor  is  in  two  parts. 
There  is  the  blinking  part,  which  we 
call  the  cursor,  and  the  other  part, 


which  we  call  the  highlight.  The  rule 
is,  when  you  type  a  character,  it  will 
always  appear  where  a  blinking  cur¬ 
sor  is,  and  whatever  character  was 
underneath  it  gets  moved  out  of  its 
way.  Always.  It  will  never  happen  to 
the  right  or  left  of  the  cursor.  The 
highlight  is  where  the  next  character 
to  be  deleted  will  be  deleted  when 
you  press  the  Del  key.  When  you’re 
typing  it  shows  exactly  what’s  hap¬ 
pening.  I  don't  know  how  many 
times  I’ve  made  the  mistake  of  mis- 
positioning  a  cursor  on  a  system  that 
deletes  to  the  left  and  inserts  to  the 
right,  like  on  the  Macintosh.  That 
causes  a  lot  of  confusion. 

We  spent  six  months  before  we  re¬ 
alized  a  cursor  has  to  be  in  two  parts. 
We  played  with  cursors  between  the 
letters,  on  the  letters,  cursors  that 
flickered  back  and  forth — dozens  of 
designs.  You  always  want  to  use  a 
left  delete  after  you’ve  been  typing. 
If  you  move  the  cursor  somewhere, 
you  always  think  of  words  from  the 
beginning  of  the  words.  You  move 
there,  and  you  always  want  to  delete 
the  other  way  after  you've  moved 
the  cursor.  We  observed  that  to  be  a 
99  percent  phenomenon.  So  we  have 
it  automatically.  Whenever  you  leap, 
the  cursor  knows  to  delete  to  the 
right,  and  whenever  you’re  typing,  it 
automatically  backspaces.  This  is  def¬ 
initely  modal,  and  once  in  a  blue 
moon  you  will  make  a  mode  error. 
You  will  press  Delete  and  take  out 
the  wrong  character.  But  it’s  so  much 
gain. 

DDJ:  So  you've  eliminated  many 
commands  normally  found  in  an  ap¬ 
plication,  especially  in  a  program 
with  several  applications. 

Raskin:  Throwing  out  commands  is 
a  very  big  thing.  This  system  does 
word  processing,  information  re¬ 
trieval,  telecommunications,  and  cal¬ 
culations,  and  it  has  five  commands. 
Any  other  word  processor  has  more 
than  five. 

DDJ:  You've  complained  that  the  Mac 
ended  up  with  a  traditional  operat¬ 
ing  system.  How  does  your  system 
differ? 

Raskin:  We  threw  out  the  whole 
concept  of  an  operating  system.  By 
definition,  an  operating  system  is  the 
program  you  have  to  fight  with  be¬ 
fore  you  can  fight  with  an  applica¬ 


tion.  For  a  single-user  system  on 
which  you’re  not  developing  soft¬ 
ware,  who  needs  an  operating  sys¬ 
tem?  There  is  no  operating  system 
running  underneath  this.  The  editor 
runs  right  on  the  bedrock  of  the  sili¬ 
con.  There  are  no  menus.  You  know 
that  people  like  broad,  flat  menus 
rather  than  deep  menus.  What  is  the 
broadest  and  flatest  menu  you  can 
imagine?  A  few  things  labeled  on  the 
fronts  of  keys.  Everything  is  avail¬ 
able  instantaneously  and  simulta¬ 
neously.  If  I  want  to  look  up  a  tele¬ 
phone  number,  I  don’t  have  to  get 
into  Information  Retrieval  mode,  I 
just  use  the  Leap  command.  Leap  is 
information  retrieval.  If  I  want  to  do 
a  calculation,  do  I  say  “Calculation 
mode”  or  pull  down  the  calculator? 
No,  I  simply  type  the  equation  and 
press  the  Calc  button.  That’s  the  way 
it  should  always  have  been. 

DDJ:  The  most  basic  concept  to  most 
interfaces  is  the  separation  between 
applications. 

Raskin:  In  today's  world!  In  tomor¬ 
row’s  world,  interfaces  like  this  will 
clobber  the  usual  present  kind,  and 
in  a  few  years  many  kinds  of  prod¬ 
ucts  will  have  this  kind  of  interface. 

DDJ:  What’s  held  people  up  from  see¬ 
ing  this  sort  of  integration? 

Raskin:  We  already  have  integrated 
software,  and  that's  integration  by  a 
menu.  We  call  this  homogenized. 
Why  didn’t  I  see  this  years  ago?  I 
have  no  idea. 

DDJ:  Can  any  application  be 
homogenized? 

Raskin:  Yes.  You  name  it,  and  I  can 
homogenize  it.  The  basic  principle 
can  be  applied  to  all  applications  that 
I  know  of  on  computers.  The  work 
we’ve  done  here  can  be  applied  to 
any  computer,  small  or  large,  and 
any  application. 

DDJ:  Given  the  right  hardware? 
Raskin:  Given  the  right  software. 
Most  people  think  the  Apple  II  is  the 
wrong  hardware  for  any  spiffy  hu¬ 
man  interface.  Part  of  the  problem  is 
this  doesn't  show  up  on  television. 
All  you  see  is  your  work.  But  isn't 
that  what  you  want  to  see?  Do  you 
want  to  see  the  computer  mecha¬ 
nism,  or  do  you  want  to  see  your 
work?  We  don’t  waste  any  of  the 
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screen  with  indicators  or  messages. 
It’s  all  yours.  On  a  64K  Apple  II  with 
our  system,  the  user  gets  40K.  If  you 
buy  a  128K  Mac  and  MacWrite,  you 
get  20K  out  of  128K.  Our  entire  code 
for  this  product  is  14. 5K.  Nobody 
even  thinks  you  can  write  an  appli¬ 
cation,  much  less  four  or  five  appli¬ 
cations,  in  under  16K  bytes.  Those 
numbers  have  not  been  heard  for 
years.  Go  back  to  the  early  days  of 
DDJ\ 

DDJ:  But  you  must  feel  some  frustra¬ 
tion  with  this  product  on  the  Apple 
II? 

Raskin:  Sure.  The  keyboard  layout 
isn’t  optimal.  The  Leap  keys  should 
be  larger.  They  weren't  designed  for 
leaping  use.  There  are  many  applica¬ 
tions  on  other  hardware  that  we  sim¬ 
ply  don't  do  here.  For  one  thing,  we 
don’t  have  the  spreadsheet  integrat¬ 
ed  because  the  Apple  finally  ran  out 
of  power  at  a  certain  point.  But  the 
hardware  is  not  so  important.  And 
the  amount  of  stuff  you  can  do  with 
an  8-bit  processor  and  even  16K  bytes 
of  memory  have  not  been  exhausted 
by  humanity  and  will  never  be. 

People  like  Steve  Jobs  say  that  the 
way  to  get  simplicity  is  greater  com¬ 
plexity.  Well,  they  don’t  put  it  quite 
that  boldly.  What  they  say  is,  if  we 
have  intelligent  enough  systems  and 
big  enough  systems,  we  can  make 
them  very  easy  to  use.  I  have  this  stu¬ 
pid  idea  of  simplicity  via  simplicity — 
and  for  many  applications  it  works. 
I’m  not  denigrating  all  of  AI  and  that 
stuff.  I  think  there’s  a  lot  to  be  gained 
from  it  but  not  for  little  things  that 
people  are  going  to  use  on  an  every¬ 
day  basis. 

I  was  a  visiting  scholar  in  the  artifi¬ 
cial  intelligence  lab  at  Stanford,  and  I 
had  an  office  at  PARC.  I  was  never  an 
employee  at  PARC. 

DDJ:  So  you  think  the  mouse  created 
a  barrier  toward  designing  better 
user  interfaces.  What’s  better  for 
graphics? 

Raskin:  My  favorite  graphic  input 
device  is  a  tablet.  That’s  what  I  find 
easiest  to  use.  It  feels  like  a  pencil.  I 
spent  years  practicing,  using  pencils. 
I’ve  thought  the  mouse  was  a  mistake 
for  a  decade  and  a  half  now.  I  think 


it's  being  foisted  on  a  lot  of  people. 
When  I  go  to  a  conference  and  I  tell 
people  why  I  hate  a  mouse,  I  usually 
get  applause. 

DDJ:  Specific  applications  create  cer¬ 
tain  needs  in  interface  design.  What's 
an  example  of  this? 

Raskin:  Most  people  who  do  a  lot  of 
heavy  telecommunications  end  up 
having  two  computers  because,  if 
you  want  to  receive  messages  at  an 
arbitrary  time,  you  have  to  leave 
your  telecom  package  up.  With  your 
telecom  package  up,  you  can't  do 
anything  else.  On  this  system,  it’s  al¬ 
ways  in  Telecom  mode.  If  you  send 
me  a  message,  whether  I'm  working 
or  not,  I  won’t  be  interrupted.  If  I’m 
not  there,  it'll  just  accept  it;  if  I  am 
there,  I  can  finish  my  thought  and 
then  read  your  message.  So  here's  a 
place  where  modelessness  buys  you 
a  whole  computer. 

DDJ:  Have  the  main  issues  changed  in 
terms  of  what  a  programmer  wants 
and  a  user  needs? 

Raskin:  I  think  so.  There  are  some 
programmers  I  haven’t  hired  here 
because  they  say  "Hey  I’m  not  going 
to  get  a  chance  to  hack  at  systems  or 
Unix  or  anything  like  that  here.”  The 
programmers  we  do  have  here  have 
as  their  first  priority  making  things 
work  well  with  people.  That  means 
you  can't  have  an  interest  in  develop¬ 
ing  a  new  and  better  operating  sys¬ 
tem.  In  a  few  years  all  computer-sci¬ 
ence  departments  will  have 
user-interface  courses;  some  do  now. 
And  that  will  become  more  and 
more  recognized  as  legitimate  and 
worthy.  We  have  to  have  a  stronger 
theory  of  human  interfaces.  Part  of 
what  I'm  doing  is  developing  such  a 
theory  in  my  spare  time. 

DDJ:  What  would  you  concentrate 
on  in  a  user-interface  class? 

Raskin:  First  of  all,  you've  got  to  get 
people  to  recognize  when  they're 
having  trouble.  People  always  say, 
"It's  me,”  but  it’s  the  computer  de¬ 
sign  that's  so  dumb.  So  first,  you  have 
to  get  programmers  out  of  the  cocky 
position  of  believing  they  know  how 
to  design  stuff  and  to  a  humble  posi¬ 
tion  that  if  a  person  is  having  a  prob¬ 
lem,  it’s  not  the  person  who’s  dumb, 
it's  a  dumb  design.  That’s  the  start. 
And  have  them  learn  statistics  and 


experimental  design.  And  then  un¬ 
derstanding  how  human  beings 
learn  and  work — cognitive  psycholo¬ 
gy  and  learning  theory. 

DDJ:  Will  different  languages  help  in 
the  creation  of  better  interfaces? 
Raskin:  Definitely.  We  used  Forth. 
That  helped  us  here  because  it  was 
small  and  runs  like  a  bat  out  of  hell. 
You  don't  have  many  compunctions 
about  dropping  down  to  assembly 
language  if  you  really  need  speed.  So 
for  sheer  performance,  it  was  a  good 
choice.  For  human-interface  design, 
most  of  the  languages  like  PROLOG 
and  LISP  or  APL  are  totally  inappro¬ 
priate.  I’ve  been  reading  some  arti¬ 
cles  about  people  writing  simulators 
on  which  you  can  test  human  design 
interfaces.  They  say  it’s  very  slow, 
which  invalidates  it.  Unless  they  can 
simulate  the  real  speed,  they’re  not 
getting  any  useful  data.  There’s  no 
language  per  se. 

DDJ:  What  thoughts  did  you  have 
along  these  lines  while  you  were  do¬ 
ing  things  for  DDJ? 

Raskin:  Go  back  and  read  the  very 
first  article  I  ever  published  in  1976 
in  DDJ.  Read  Jim  Warren’s  little  com¬ 
ment  about  me  at  the  bottom.  ["Jef 
Raskin  is  well  known  for  his  heretical 
belief  that  people  are  more  important 
than  computers  and  that  computer 
systems  should  be  designed  to  allevi¬ 
ate  human  frailties,  rather  than  have 
the  human  succumb  to  the  needs  of 
the  machine.")  It’s  still  true,  word  for 
word.  I’ve  been  trying  to  fulfill  that 
belief  ever  since. 

DDJ 
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Simple  Plots  with  the 
Enhanced  Graphics  Adapter 


Recently  I  needed  to  generate 
some  engineering  graphs  on 
an  IBM  Enhanced  Color  Dis¬ 
play  with  the  Enhanced  Graphics 
Adapter  (EGA).  I  was  using  a  program 
written  in  Lattice  C  Version  2.14  to  do 
the  computations,  and  all  I  needed 
was  the  capability  to  draw  a  simple 
x-y  plot,  taking  advantage  of  the 
EGA's  640-by-350  pixel  high-resolu- 
tion  mode.  An  obvious  solution 
would  have  been  to  use  IBM’s  Graph¬ 
ics  Development  Toolkit,  but  it 
seemed  to  be  the  wrong  tool  for  the 
job  I  had  in  mind. 

I  assembled  my  resources.  The 
ROM  BIOS  video  functions  (interrupt 
lOh)  came  to  mind;  a  quick  search  of 
the  Lattice  C  reference  manual  pro¬ 
duced  the  int86(  )  utility  function. 
Armed  with  these  tools,  I  wrote  a  set 
of  graphics  functions  to  do  my  job. 
Here  I  present  the  most  interesting  of 
these  modules,  which  set  the  display 
in  high-resolution  graphics  mode 
and  perform  line  drawings. 

The  EGA  can  be  set  up  to  operate  at 
its  highest  resolution  mode  by  using 
the  mode  number  16  in  the  ROM  BIOS 
video  interrupt.  In  its  basic  configu¬ 
ration  with  64K  RAM,  this  mode  al¬ 
lows  four  colors.  The  640-by-200 
pixel  resolution  of  the  Color  Graphics 
Adaptor  (CGA)  can  be  emulated  by  us¬ 
ing  mode  number  14. 

The  BIOS  provides  a  function  that 
allows  you  to  write  a  pixel;  I  needed 
a  module  that  could  join  two  points 
on  the  screen.  This  meant  that  I  had 
to  brighten  up  a  lot  of  pixels  that  are 
close  to  an  imaginary  line  drawn  be¬ 
tween  the  two  end  points.  A  tool  to 
help  me  do  this  was  close  at  hand — 
in  DDJ,  in  fact. 

The  May  1985  issue  (#103)  con¬ 
tained  the  article  "Using  Decision 
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I  needed  a  module 
that  could  join  two 
points  on  the  screen. 


Variables  in  Graphics  Primitives"  by 
Tom  Hogan,  in  which  the  author 
generalized  Bresenham’s  decision 
variable  method.  Bresenham's  origi¬ 
nal  algorithm  for  line  drawing  is  de¬ 
scribed  in  the  book  Fundamentals  of 
Interactive  Computer  Graphics  by 
James  D.  Foley  and  Andries  Van  Dam 
(Reading,  Mass.:  Addison-Wesley, 
1982).  The  algorithm  in  the  book 
works  for  lines  with  slopes  between 
0  and  1,  but  can  be  easily  modified  to 
work  with  lines  of  arbitrary  slope.  I 
have  made  such  modifications  in  my 
line  drawing  function.  (See  v_j draw 
in  Listing  Two,  page  74.)  Note  that  I 
have  chosen  to  represent  the  lower 
left  corner  of  the  screen  as  the  pixel 
(0,0),  though  the  upper  left  corner  is 
considered  to  be  the  origin  in  IBM's 
ROM  BIOS. 

In  Listing  One,  page  74,  I  show  a 
sample  program  that  plots  sin(x)  vs.  x 
on  the  screen.  It’s  a  simple  demon¬ 
stration  of  the  use  of  graphics  primi¬ 
tives.  A  better  way  to  use  the  capabil¬ 
ity  would  be  to  write  a  module  that 
would  nicely  map  the  arrays  y  and  x 
of  size  n  onto  the  screen.  It  would 
first  find  the  true  maxima  and  mini¬ 
ma  of  the  data,  pick  a  nicer  set  of 
numbers  for  these  extremes,  then 
scale  each  point  onto  screen  coordi¬ 
nates  and  use  V—draw  to  draw  linear 
segments  on  the  screen  to  make  the 
plot.  A  coordinate  grid  under  the  plot 


would  make  the  output  even  more 
attractive.  But  all  this  follows  natu¬ 
rally  once  you  can  connect  any  two 
points  on  the  screen,  which  is  what 
the  code  presented  here  permits.  I'm 
sure  you  wouldn't  want  me  to  take 
away  all  the  fun  of  setting  up  your 
own  customized  plotting  package. 

Bresenham 's  decision  variable 
method,  as  Hogan  explained  in  his  ar¬ 
ticle,  can  be  used  to  generate  any  well- 
behaved  curve  of  the  form  G(x,y)=0. 
Hogan's  implementation  of  the  algo¬ 
rithm  was  intended  for  medium-reso¬ 
lution  graphics;  Barkakati 's  interest  is 
with  the  considerably  higher  resolu¬ 
tion  EGA  affords. 

What  Bresenham's  method  gains 
you  is  chiefly  speed,  an  important  con¬ 
sideration  when  doing  high-resolution 
curve  drawing.  Rather  than  comput¬ 
ing  square  roots  for  every  point,  it  de¬ 
pends  heavily  on  integer  math.  It  also 
creates  curved  line  segments  without 
gaps,  a  feature  that  leads  to  smoother¬ 
looking  curves.  Based  on  the  value  of 
the  slope  of  the  tangent  line  and  the 
direction  of  its  change,  the  method  de¬ 
cides  where,  in  relation  to  the  last 
point,  the  neyt  point  goes.  The  slope 
doesn't  have  to  be  calculated  for  each 
point;  key  inflection  points  merely 
need  to  be  identified.  The  slope  and 
how  it  is  changing  can  be  used  to  select 
from  all  possible  neyt  points  a  pair  of 
candidate  points  and  to  choose  be¬ 
tween  these — the  decision  variable 
part  of  the  approach.  At  any  given  lo¬ 
cation  only  two  neyt  points  are  reason¬ 
able,  and  the  method  finds  them  and 
chooses  between  them. — ed. 

DDJ 
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A  68000  Cross 
Assembler — Part 


ast  month  I  introduced  a  Mo¬ 
dula-2  cross  assembler  for  the 
Motorola  68000  16/32-bit  mi¬ 
croprocessor.  In  that  first  install¬ 
ment,  I  looked  at  the  overall  struc¬ 
ture  of  the  program  from  a  data  flow 
perspective  and  presented  all  defini¬ 
tion  modules  as  well  as  the  main  pro¬ 
gram  module. 

This  month,  I  will  discuss  some  of 
the  algorithms  used  and  present  all  of 
the  implementation  modules  along 
with  a  stand-alone  program  to  initial¬ 
ize  the  mnemonic  lookup  table. 

Although  this  project  was  devel¬ 
oped  on  a  Z80  system  using  the  Mo¬ 
dula-2  System  for  Z80  CP/M  from 
Hochstrasser  Computing  AG,  the 
source  code  should  compile  and  run 
on  most  other  small-computer  imple¬ 
mentations  of  Modula-2.  I  will  try  to 
identify  those  areas  that  may  be  im¬ 
pediments  to  portability.  The  only 
true  machine  dependency  is  because 
of  the  assumption  that  INTEGERS, 
CARDINALS,  and  BITSETs  all  occupy  16 
bits  in  memory.  Although  not  all  Mo¬ 
dula-2  libraries  are  equivalent,  I  have 
tried  to  restrict  myself  to  library  rou¬ 
tines  that  are  common  to  both  the 
Hochstrasser  and  the  popular  Voli¬ 
tion  Systems  compilers.  That  should 
allow  a  fair  degree  of  portability 
across  many  different  compiler  sys¬ 
tems. 

In  Modula-2,  the  definition  module 
is  like  a  contract.  It  tells  the  users  of 
the  module  (that  is,  programmers) 
what  tasks  will  be  performed  with¬ 
out  saying  anything  about  the  meth¬ 
ods  used.  Definition  modules  are  com¬ 
piled  separately  and  provide  the  only 
interface  to  other  modules  or  to  the 
main  program  module.  The  defini¬ 
tion  modules  presented  last  month  in- 
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definition  module  is 
like  a  contrast.  It  says 
what  tasks  will  be 
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about  the  methods. 


dicated  the  tasks  that  are  to  be  per¬ 
formed  during  the  execution  of 
X68000;  the  implementations  present¬ 
ed  this  month  describe  the  algorithms 
used  to  accomplish  those  tasks. 

LonglVumbers 

The  data  type  LONG  (an  array  of  inte¬ 
gers')  simulates  32-bit  hexadecimal 
numbers;  the  implementation  mod¬ 
ule  for  LongNumbers  (Listing  Eleven, 
page  80)  provides  procedures  that  in¬ 
put,  manipulate,  and  output  the 
LONG  data  type. 

LongClear  simply  clears  all  ele¬ 
ments  of  the  array  to  0.  LongAdd 
( LongSub )  is  a  multiple  precision  rou¬ 
tine  that  uses  an  integer  for  a  carry 
borrow! )  flag.  The  idea  is  to  index 
through  the  array  calculating  the 
sum  (difference)  while  checking  for 
any  overflow  (underflow);  such  an 
overflow  (underflow)  causes  the  car¬ 
ry  borrow! )  flag  to  be  set  and  the  re¬ 
sult  to  be  adjusted.  This  carry  bor- 
row( )  is  then  figured  into  the  next 
digit's  calculation. 

The  conversion  routines  Card- 
ToHLLong  and  LongToCard  use  the 
standard  hexadecimal/decimal  con¬ 
version  algorithms,  with  the  addition 
of  range  checking.  LongToCard 


checks  the  range  of  the  LONG  and  re¬ 
turns  FALSE  if  any  of  the  four  most 
significant  digits  are  anything  but  0. 
LongToInt  is  a  bit  more  complicated 
because  there  are  two  possible  in- 
range  conditions:  either  all  unused 
bits  must  be  Os  (positive  integer),  or 
all  must  be  Is  (negative  integer). 

Longlnc  and  LongDec  use  LongAdd 
and  LongSub  respectively  as  well  as 
CardToLong,  to  increment  or  decre¬ 
ment  a  LONG  data  type  by  any  value 
in  the  CARDINAL  range.  LongCompare 
uses  the  standard  comparison  algo¬ 
rithm  often  used  to  compare  strings. 

LongPut  and  LongWrite  cause  out¬ 
put  of  an  array  of  integers  as  hexa¬ 
decimal  numbers.  They  both  use  an 
internal  filter  routine  called  GetDigit 
to  trap  integers  outside  the  hexadeci¬ 
mal  range.  The  Size  parameter  is 
used  to  allow  LongPut  and  LongWrite 
to  output  only  a  portion  of  the  num¬ 
ber  in  cases  where  a  small  hexadeci¬ 
mal  number  is  stored  as  a  LONG  or  to 
output  extra  long  strings  of  hex  digits 
for  the  S-records. 

StringToLong  converts  an  array  of 
characters  into  a  variable  of  type 
LONG.  Error  checking  is  done  by  the 
IsHEX  routine,  and  GetHEX  handles 
the  digit-by-digit  conversion.  The 
two  address-bounds  routines  use  the 
set  operator  IN  to  force  a  LONG  to  spe¬ 
cific  address  boundaries. 

CmdLinZ 

I  wrote  the  command  line  parser 
(Listing  Twelve,  page  80)  as  an  ex¬ 
periment:  I  wanted  to  see  just  how 
flexible  the  Modula-2  pointer  struc¬ 
ture  really  was.  My  conclusion  is  that 
it  is  just  as  flexible  and  powerful  as 
the  pointer  structure  in  C  and  much 
easier  to  understand. 

This  module  could  not  have  been 
written  in  Pascal  because  Pascal 
pointers  can  reference  only  vari- 
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ables  dynamically  created  by  the 
standard  procedure  NEW.  Modula-2 
pointers  can  be  made  to  point  to  any 
data  type. 

This  routine  parses  the  command  j 
line  buffer  of  the  operating  system, 
which  is  referenced  by  an  absolute 
variable  at  80H,  into  an  array  of 
pointers  to  strings.  (Absolute  vari¬ 
ables  are  another  new  feature  of  Mo¬ 
dula-2  and  allow  any  variable  to  be  j 
placed  at  a  specific  location  in  memo¬ 
ry.)  The  parsing  is  done  without  even 
recopying  the  buffer  by  setting  a 
pointer  to  the  beginning  of  each  ar¬ 
gument  and  a  null  terminator  at  the 
end  (replacing  the  space  that  normal¬ 
ly  separates  command  line  argu¬ 
ments).  After  all  arguments  have 
been  so  processed,  ArgV  is  set  to 
point  to  the  pointers.  (See  Part  1  of 
this  series  of  articles  for  a  description  j 
of  how  the  pointer  is  used  to  retrieve  | 
the  arguments — C  programmers  will 
feel  right  at  home.) 

The  CmdLin2  implementation  uses 
a  looping  construct  that  is  new  to  Mo¬ 
dula-2:  LOOP  .  .  .  END.  This  construct 
has  two  useful  variations:  the  first  is  | 
an  infinite  loop;  the  other,  by  using  j 
the  optional  EXIT  statement,  allows  ! 
termination  anywhere  in  the  loop — 
even  allowing  multiple  termina¬ 
tions.  I  know  of  one  university  in¬ 
structor  who  asks  his  students  to 
prove  that  WHILE  or  REPEAT  are  inap¬ 
propriate  before  they  are  given  leave 
to  use  the  LOOP.  Some  authors  refer 
to  it  as  an  unstructured  loop.  1  tend  to 
agree,  instead,  with  Donald  Knuth,  j 
who  feels  that  all  constructs — even  j 
the  lowly  GOTO — have  an  inherent 
structure;  if  that  structure  matches 
|  the  structure  of  the  problem,  that’s 
the  one  to  use. 

In  CmdLin2,  there  are  three  EXIT 
statements  in  the  LOOP  . . .  END  state¬ 
ment.  I  went  through  many  trials  us¬ 
ing  WHILE  and  REPEAT,  extra  Boolean 
variables,  and  all  the  usual  so  called 
structured  "tricks,”  but  none  were  as 
clear  and  simple  as  the  LOOP  (yet  still 
reliable  under  all  conditions  of  input). 

While  reading  through  a  Modula-2 
|  textbook  recently  I  came  across  sev¬ 
eral  examples  of  a  small  program 
fragment  that  was  supposed  to  read 
integers  and  add  them  to  a  sum  and 
then  stop  when  something  other 
than  an  integer  was  read.  All  three  of 
the  examples  given  either  used  two 
read  statements,  tested  the  same  con¬ 


dition  twice,  or  both.  These  were 
supposed  to  be  examples  of  the  cor¬ 
rect  way  to  use  WHILE  and  REPEAT 
loops  but  were  a  perfect  example  of 
trying  to  shoehorn  the  problem  to  fit 
the  structure.  Such  examples  appear 
repeatedly  in  programming  texts. 

Modula-2's  LOOP  .  .  .  EXIT  .  .  .  END 
construct  provides  a  simple  and  ele¬ 
gant  solution: 

(*  Readlnt  and  Done  are  imported  *) 
(*  from  the  standard  module  InOut  *) 
(*  Done  is  set  TRUE  if  Readlnt  *) 

(*  is  successful.  *) 

sum  :=  0; 

LOOP 

Readlnt  (num); 

IF  Done  THEN 

sum  :=  sum  +  num; 

ELSE 

EXIT; 

END; 

END; 

Parser 

The  name  for  this  module  is  really  a 
bit  of  a  misnomer  because  all  it  does 
is  split  up  the  68000  source  code  into 
its  components:  LABEL,  OPCODE, 
SOURCE-OPERAND,  and  DESTINATION- 
OPERAND  (Listing  Thirteen,  page  80). 
The  algorithm  is  quite  primitive  in 
that  it  merely  scans  the  line  from  left 
to  right  looking  for  the  various  parts 
and  transfers  them  into  variables 
called  Label,  OpCode,  SrcOp,  and  Des- 
tOp.  These  variables  are  arrays  of 
characters  defined  in  the  definition 
part  of  this  module.  The  location  of 
each  item  is  noted  for  later  use  in  the 
error  handling  module  so  that  the  ex¬ 
act  location  of  any  error  can  be 
pointed  out. 

The  most  convoluted  part  of  the 
scanning  process  is  picking  out  de¬ 
limiters,  especially  when  the  normal 
delimiter  characters  get  imbedded 
within  parentheses  or  quotes.  The 
problem  is  handled  by  a  couple  of 
flags.  ParCnt  keeps  track  of  (possibly 
nested)  parentheses  counts,  and  In- 
Quotes  becomes  TRUE  inside  quotes; 
both  are  used  to  prevent  incorrect 
detection  of  delimiters.  Parser  will 


flag  an  error  if  any  identifier  or  ex¬ 
pression  is  too  long.  Labels  and  op¬ 
codes  are  limited  to  eight  characters, 
and  operands  (including  expressions) 
are  limited  to  20  characters. 

SymbolTable 

The  implementation  of  this  module 
(Listing  Fourteen,  page  84)  hides  a 
data  type  called  SYMBOL  and  vari¬ 
ables  called  SymTab,  Top,  and  Next. 
This  is  an  excellent  example  of  the 
way  Modula-2  allows  you  to  separate 
lifetime  and  scope.  These  variables 
must  exist  during  the  entire  time  that 
the  program  is  running,  as  they  pass 
on  information  gathered  in  assembly 
pass  1  to  assembly  pass  2.  Yet,  at  the 
same  time,  you  don't  want  any  ac¬ 
cess  to  these  variables  except 
through  the  symbol  table  routines. 
To  allow  Pascal  variables  to  exist  for 
the  life  of  the  program,  they  would 
have  to  be  declared  as  global,  at  the 
risk  of  side  effects  from  unplanned 
access.  Modules  provide  a  visibility 
wall  between  their  contents  and  the 
rest  of  the  program.  SymTab,  Neyt, 
and  Top  cannot  be  accessed  from 
outside  SymbolTable  (limited  scope), 
but  they  exist  for  the  life  of  the  pro¬ 
gram  (global  lifetime). 

The  FillSymTab  routine  simply 
adds  a  SYMBOL  (a  record  consisting  of 
an  identifier  and  a  LONG  number)  to 
the  next  open  position  in  SymTab 
and  returns  an  error  if  no  room  exists. 
SortSymTab  uses  a  Shell  sort  to  place 
the  identifiers  in  alphabetical  order 
for  easy  access.  Notice  in  the  Swap 
routine  that  entire  records  can  be  as¬ 
signed  in  one  statement  in  Modula-2. 
Not  only  is  this  more  convenient  than 
assignment  one  element  at  a  time,  but 
it  is  also  more  efficient:  The  compiler 
is  able  to  use  fast  and  compact  assem¬ 
bly-language  routines  to  copy  the 
data  into  the  new  variable. 

ReadSymTab  uses  a  binary  search 
to  find  quickly  the  value  associated 
with  any  identifier.  If  the  symbol  is 
not  found,  ReadSymTab  returns 
FALSE  to  the  calling  program.  It  is 
here,  also,  that  duplicate  symbol  ta¬ 
ble  entries  are  flagged  (to  do  it  in  Fill¬ 
SymTab  would  require  sorting  and 
searching  the  table  after  each  en¬ 
try — which  is  hardly  worth  the  ex¬ 
tra  time!). 

ListSymTab  really  only  returns 
one  entry  in  the  table  and  is  used  by 
the  Listing  module  to  provide  a  sym- 
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bolic  reference  table  of  identifiers  at 
the  end  of  the  program. 

OperationCodes 

X68000  is  a  "sort  of”  table-driven  as¬ 
sembler  (I'm  gonna  get  lots  of  objec¬ 
tion  to  this  one!).  The  mnemonics  and 
data  that  are  used  to  derive  the  op¬ 
code  bit  patterns  and  all  addressing 
mode  information  come  from  a  file 
called  OPCODE.DAT.  This  file  must  ex¬ 
ist  on  the  default  disk  any  time 
X68000  is  run  because  the  data  must 
be  read  into  the  lookup  table  used  in 
the  binary  search  routine  to  find  the 
instructions.  X68000  is  not  a  true  ta¬ 
ble-driven  assembler  because  it  lacks 
the  flexibility  to  accept  tables  of  vari¬ 
ous  processors  and  the  table  (OPCODE¬ 
.DAT)  is  not  a  text  file. 

In  Modula-2,  implementation  mod¬ 
ules  may  optionally  specify  an  ini¬ 
tialization  part.  This  initialization  is 
run  on  program  start-up,  before  the 
main  program  runs.  The  purpose  is 
to  set  initial  conditions  within  the 
module.  The  initialization  for  Opera¬ 
tionCodes  (Listing  Fifteen,  page  86) 
opens  the  file  OPCODE.DAT,  and  reads 
the  data  into  an  array  called  Tab- 
le68K.  This  data  file  is  stored  in  com¬ 
pact  binary  format.  Instructions  is 
the  only  routine  in  OperationCodes; 
it  uses  a  binary  search  routine  to  find 
the  correct  mnemonic  opcode  in 
Table68K.  If  found,  its  bit  pattern,  as 
well  as  two  SETs  consisting  of  (enu¬ 
merated)  addressing  modes,  are  re¬ 
turned  to  the  calling  program.  If  the 
opcode  mnemonic  is  illegal  (that  is, 
not  found),  an  error  is  flagged  by  the 
error  handling  routine  in  ErrorX68. 

InitOperationCodes 

This  program  module  (Listing  Six¬ 
teen,  page  86)  is  not  actually  part  of 
X68000  but  merely  creates  the  data 
file  OPCODE.DAT  described  above.  It 
contains  most  of  the  same  declara¬ 
tions  and  definitions  that  Operation- 
Codes  contains  as  their  data  types 
and  variable  have  to  match  exactly. 

The  lookup  table  for  the  mnemon¬ 
ics  is  created  by  this  program  one 
mnemonic,  bit  pattern,  and  address¬ 
ing  mode  at  a  time.  There  are  118 
mnemonics  (ABCD  to  UNLK),  and  each 
is  assigned  one  element  of  an  array. 
Each  element  of  the  array  is  a  four- 
field  record.  After  data  is  assigned  to 
the  array  properly  it  is  written  to  a 
disk  file  using  the  WriteRec  proce¬ 


dure. 

Note:  The  WriteRec  procedure 
may  not  be  available  on  all  imple¬ 
mentations  of  Modula-2  but  may  be 
added  easily  by  the  programmer.  It 
makes  use  of  the  generic  parameter 
type  WORD.  Two  possible  implemen¬ 
tations  are: 

For  machines,  such  as  the  PDP-11  and 
many  microcomputers,  in  which 
TSIZE  (WORD)  =  2: 

WriteRec  (f :  FILE;  Rec  :  ARRAY  OF 

WORD); 

VAR 

i  :  CARDINAL; 

ptr  :  POINTER  TO  CHAR; 

BEGIN 

ptr  :  =  ADR  (Rec); 

FOR  i :  =  0  TO  HIGH  (Rec)  DO 
Write  (f,  ptr"); 

INC  (ptr);  (*  move 

pointer  to  next  byte  *) 

END; 

END  WriteRec; 

For  machines  where  TSIZE  (WORD)  = 
1  and  a  WriteWord  procedure  exists: 

WriteRec  (f  :  FILE;  Rec  :  ARRAY  OF 

WORD); 

VAR 

i :  CARDINAL; 

BEGIN 

FOR  i :  =  0  TO  HIGH  (Rec)  DO 
WriteWord  (f,  Rec); 

END; 

END  WriteRec; 

Similar  routines  can  be  developed 
for  reading  records,  as  required  by 
the  OperationCodes  initialization. 

Some  libraries  provide  procedures 
to  read  or  write  multiple  bytes  to  a 
file.  These  usually  require  the  loca¬ 
tion  (an  address)  and  size  (in  bytes)  of 
the  record.  In  this  case,  Modula-2's 
low-level  facilities  may  be  used  to 
read  or  write  the  record: 

WriteNBytes  (f,  ADR  (rec),  SIZE  (rec)); 

CodeGenerator 

This  module  (Listing  Seventeen,  next 
month)  does  more  than  is  suggested 
by  its  name.  The  definition  module 
of  CodeGenerator  lists  three  proce¬ 
dures:  BuildSymTable ,  which  "gen¬ 
erates  the  code”  for  pass  1  (that  is, 
feeds  the  symbol  table);  AdvAddrCnt, 
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68K  ASSEMBLER  main  program  as  three  LONGs.  I  will  it  is  involved  with  creating  the  sym- 

( continued  from  page  47)  (as  far  as  possible)  try  to  present  the  bol  table.  It  does  nothing  (returns  im- 

_  procedures  in  the  order  that  the  code  mediately)  if  there  is  no  opcode.  The 

which  increments  the  address  count-  would  pass  through  them  during  as-  cascaded  IF  ELSIF  ELSE  statement  de¬ 
er  after  each  instruction  is  analyzed  sembly.  This  will  mean  some  refer-  termines,  first,  if  any  assembler  di- 
(used  in  both  passes);  and  GetObject-  ences  to  SyntaxAnalyzer,  as  these  rective  is  present,  and  if  so,  specifies 
Code,  which  (with  the  help  of  many  modules  are  tightly  coupled  and  are  the  amount  of  memory  reserved 
other  procedures  in  CodeGenerator  used  in  both  passes.  (that  will  vary — EQU  reserves  no 

and  SyntaxAnalyzer)  figures  out  the  BuildSymTable  is  used  only  during  memory  whereas  DS  may  reserve 
machine  code  and  returns  it  to  the  pass  1,  and,  as  was  mentioned  above,  any  amount).  Next,  if  there  is  any  la- 

Modula-2  Porting  Experience 

(MS  DOS) 

Hochstrasser  supplies  several  file- 

Bachground  Society  (MODUS)  has  been  working  on  handling  modules  with  its  compiler.  I 

Modula-2  is  a  relatively  young  lan-  what  it  hopes  will  be  a  universal  li-  chose  to  use  the  one  called  Files  be- 
guage,  and  efforts  to  standardize  brary.  cause  I  knew  it  to  be  nearly  identical 

both  the  basic  language  and  the  li-  to  a  module  of  the  same  name  sup- 

brary  are  still  underway.  Modula-2  Porting  Among  Systems  plied  by  Volition  Systems.  The  Files 

was  developed  at  the  Swiss  Federal  By  and  large,  the  compilers  them-  module  is  flexible  and  powerful  in 
Technical  Institute  (ETH)  in  the  late  selves  are  pretty  much  compatible  that  it  allows  random  or  sequential 
70s  by  a  team  headed  by  Niklaus  (despite  the  amendments  mentioned  access;  it  also  provides  methods  to 
Wirth,  the  creator  of  Pascal.  above).  Virtually  all  microcomputer  read  or  write  complete  data  struc- 

The  original  language  definition  implementations  use  16  bits  for  CAR-  tures.  LogiTech  supplies  one  file-han- 
was  contained  in  Programming  in  D1NAL,  INTEGER,  and  BITSET  data  dling  module — FileSystem,  which  is 
Modula-2  by  Niklaus  Wirth,  2d  ed.  types;  most  implement  strings  as  capable  of  all  the  same  operations  as 
(New  York:  Springer- Verlag,  1983).  NULL  terminated  ARRAY  OF  CHAR.  (In-  is  Files,  along  with  text-oriented 
On  March  3,  1984,  Wirth  released  a  terface  Technologies'  is  the  only  streams  (supplied  as  a  separate  mod- 
brief  entitled  “Revisions  and  Amend-  product  I  know  of  that  implements  ule  called  Texts  in  the  Hochstrasser 
ments  to  Modula-2,”  which  outlined  strings  Pascal-style — presenting  a  se-  and  Volition  Systems  libraries), 
several  clarifications,  revisions,  and  rious  impediment  to  portability.)  All  The  first  (and  easiest)  step  in  porting 
extensions  to  the  language  itself.  This  the  standard  data  types,  structures,  to  a  new  compiler  is  to  change  the 
brief  was  published  more  recently  in  loop  constructs,  and  operators  are  in-  names  of  the  various  procedures  to 
the  January/February  1985  issue  of  variably  provided.  Some  compilers  match  the  new  library.  In  this  in- 
The  Journal  of  Pascal,  Ada,  &  Mo-  omit  or  alter  the  low-level  facilities  stance,  for  example,  Read  became 
dula-2;  the  changes  have  also  been  in-  for  concurrent  processing,  but  most  ReadChar,  whereas  WriteRec  (f  Re- 
corporated  into  the  third  edition  of  programmers  will  have  limited  use  cordVariable )  had  to  be  converted  to 
Wirth's  book.  Most  microcomputer  for  these  advanced  features.  WriteNBytes  (f  ADR  (RecordVari- 

compilers  have  not  yet  implemented  Differences  in  the  library,  particu-  able),  TSIZE  (RecordVariable),  Writ- 
these  changes  or  have  implemented  larly  in  file  handling,  are  where  ten ).  All  these  kinds  of  changes  are  ob- 
only  some  of  them.  most  of  the  problems  lie.  The  four  vious  from  reading  through  the 

The  library  too,  exists  in  several  systems  I  am  familiar  with  (those  documentation  of  the  compiler  sys- 
versions.  In  his  original  work,  Wirth  from  Hochstrasser,  Volition  Systems,  terns,  and  they  present  few  problems, 
postulated  a  standard  minimum  li-  Interface  Technologies,  and  Logi-  Several  of  the  necessary  changes 
brary — much  of  it  for  the  DEC  PDP-11  Tech)  have  three  significantly  differ-  are  not  so  obvious.  Both  systems  sup- 
minicomputer.  Since  then,  a  much  ent  approaches  to  files.  Hoch-  ply  a  Create  procedure,  which  (as  the 
more  extensive  library  has  been  de-  strasser's  and  Volition  Systems’  are  name  suggests)  is  for  creating  a  new 
veloped  for  the  Lilith,  the  Modula-2  essentially  similar  and  follow  the  file.  LogiTech’s  system,  however,  cre- 
bit-slice  microcomputer  developed  earlier  (PDP-11)  work  at  ETH;  Logi-  ates  only  a  temporary  file,  which  dis- 
at  ETH.  One  of  the  earliest  (popular)  Tech's  follows  that  for  the  Lilith  appears  as  soon  as  the  file  is  closed.  To 
microcomputer  implementations  of  quite  closely;  whereas  Interface  open  an  existing  file,  Hochstrasser 
Modula-2  was  by  Volition  Systems,  Technologies'  seems  to  go  its  own  supplies  the  procedure  Open  and  Lo- 
which  produced  compilers  for  sever-  way.  On  the  plus  side,  all  implemen-  giTech  supplies  Lookup.  Lookup  is  a 
al  computers  including  the  Apple  II,  tations  provide  the  high-level  I/O  general-purpose  procedure  that,  de- 
IBM  PC,  and  Sage.  Several  textbooks  modules  suggested  by  Wirth  (Termi-  pending  on  a  BOOLEAN  parameter, 
have  been  based  on  Volition  Systems'  nal  and  InOut)  as  well  as  the  the  float-  will  either  open  an  existing  file  or  cre- 
compiler  and  library,  including  ing-point  library  (MathLibO).  Most  ate  a  new  one.  Because  the  assembler 
those  by  Gleaves,  Wiener  and  Sinco-  provide  essentially  similar  conver-  must  often  create  a  new  version  of  an 
vec,  Wiener  and  Ford,  and  Knepley  sion  libraries  for  changing  strings  to  existing  object  file,  I  found  it  neces- 
and  Platt.  Finally,  the  Modula  User's  numbers  and  vice  versa.  sary  to  call  Delete  before  using  Look- 


Dr.  Dobb 's  Journal,  May  1986 

334 


48 


bel  present  (whether  there  was  an 
assembler  directive  or  not),  an  entry 
is  made  in  the  symbol  table.  That  en¬ 
try  will  consist  of  the  current  value 
of  the  address  counter  except  in  the 
case  of  the  EQJJ  assembler  directive. 

Notice  that  an  error  due  to  a  full 
symbol  table  will  be  detected  here — 
this  is  a  fatal  error  and  will  cause  the 
assembler  to  abort.  You  must  then 

split  up  your  program  into  two  or 
more  modules.  If  there  was  no  as¬ 
sembler  directive  (pseudo-op),  Get- 
Operand  and  GetlnstModeSize  (pro¬ 
cedures  from  the  SyntaxAnalyzer 
module)  help  to  determine  the  size  of 
the  operands.  The  special  QUICK 
mode  instructions  must  be  taken  into 
account  before  determining  how  far 
the  address  is  going  to  have  to  be  ad- 

vanced  by  this  instruction. 

During  pass  2,  GetObjectCode  first 
checks  if  there  is  any  opcode,  and  it 
returns  without  doing  anything  if 
there  is  none.  After  making  note  of 
the  size  extension  of  the  opcode,  con¬ 
trol  is  passed  to  ObjDir,  which  han¬ 
dles  code  generation  for  assembler 
directives  (see  detailed  description  lat¬ 
er).  Phase  errors  are  checked  by  com- 

up  to  create  a  new  file. 

The  Hochstrasser  Files  module  im¬ 
plements  the  type  FILE  as  an  opaque 
(hidden)  type  (that  is,  as  a  pointer  to 
some  structure  defined  in  the  imple¬ 
mentation  module).  The  opaque  type 
FILE  allows  the  programmer  to  use 
files  with  no  knowledge  of  their  un¬ 
derlying  structure.  LogiTech's  sys¬ 
tem,  taking  the  same  approach  as  that 
for  the  Lilith,  implements  type  FILE  as 
a  record  that  is  specified  in  the  defini¬ 
tion  module.  This  forces  the  program¬ 
mer  to  know  the  intimate  details  of 
the  file  structure  and  also  has  one 
very  (for  me  at  least)  unexpected  and 
disturbing  consequence:  The  type 
FILE  must  always  be  passed  as  a  VAR 
parameter.  If  it  is  passed  as  an  ordi¬ 
nary  value  parameter  (as  can  be  done 
with  the  opaque  pointer  type),  the 
calling  program  is  unable  to  get  infor¬ 
mation  back  to  the  FileSystem  mod¬ 
ule,  resulting  in  rather  odd  run-time 
errors.  It  took  quite  a  bit  of  head 
scratching  to  puzzle  that  one  out. 
With  all  the  changes  in  place,  the  file 
systems  on  the  two  versions  of  X68000 
produce  outwardly  identical  results. 

LogiTech's  compiler  passes  all  com¬ 
mand-line  parameters  to  the  first 
ReadString  call  in  the  main  program, 
which  obviates  the  need  for  my 
CmdLinZ  procedure.  From  the  user's 
perspective,  the  effect  created  is  . 
essentially  similar:  The  assembly 
file  name  can  be  entered  either  as  the 
program  is  invoked  or  in  response  to 
a  prompt  once  the  program  has  start¬ 
ed. 

The  number  conversion  routines 
supplied  by  the  two  compilers  differ 
both  in  name  and  in  behavior.  In  one 
case  ( CARDINAL  to  STRING ),  I  had  to 
add  an  extra  parameter  (specifying 
length),  whereas  in  another  ( STRING 
to  CARDINAL),  the  behavior  of  the 
equivalent  LogiTech  procedure  was 
sufficiently  different  that  I  had  to 
write  a  new  conversion  routine. 

Other  Factors  Not  Related  to 
Portability 

At  the  college  where  I  work,  one  of 
my  colleagues  has  dubbed  the  IBM  PC 
"Miss  Piggy”  for  its  propensity  to 
gobble  up  memory.  It  seems  that 
with  every  application  you  care  to 
name,  the  PC  requires  much  more 
memory  than  does  any  other  com¬ 
puter.  Compilers  are  no  different  in 
this  regard. 

The  original  work  on  X68000  was 
done  on  a  standard  CP/M  system  with 
64K  of  memory  and  two  1.2-mega¬ 
byte  floppy-disk  drives.  When  I  start¬ 
ed  work  on  the  port  to  the  MS  DOS 
environment,  I  tried  using  a  standard 
IBM  PC  with  256K  of  memory  and 
two  360K  floppy-disk  drives.  I  soon 
found  that  the  standard  PC  was  not 
up  to  the  task. 

Upon  moving  to  a  machine 
equipped  with  a  20-megabyte  hard¬ 
disk  drive,  I  was  able  to  start  compil¬ 
ing,  and  all  but  two  of  the  modules 
would  compile.  On  the  InitOpera- 
tionCodes  module,  the  compiler 
aborted  with  an  "out  of  memory”  er¬ 
ror.  This  was  the  program  module 
that  initialized  the  mnemonic  lookup 
table,  and  then  wrote  it  to  a  file — it 
was  impractical  to  split  it  into  several 
modules.  The  only  solution  was  to 
expand  the  memory  to  512K.  Even 
with  the  extra  memory,  however,  an 
implementation  restriction  still  pre¬ 
vented  several  of  the  procedures 
from  compiling  because  they  were 
too  long.  Remember,  this  is  the  same 
code  that  compiled  without  a  whim¬ 
per  on  a  64K  CP/M  system.  Eventually 

I  had  to  split  the  InitOperationCodes 
main  program  into  four  procedures 
and  also  split  the  MergeModes  proce¬ 
dure  (from  the  CodeGenerator  mod¬ 
ule)  into  four.  Despite  the  length  of 
these  procedures,  splitting  them 
made  no  sense  from  the  point  of 
view  of  program  logic. 

The  Hochstrasser  compiler  does  no 

error  checking  at  run  time,  whereas 
LogiTech’s  checks  for  integer/cardi¬ 
nal  overflow,  array  range  errors, 
CASE  out  of  range,  and  so  on.  It  seems 
that  all  the  type  transfers  used  in 
X68000  cause  some  range  errors  be¬ 
cause,  before  I  could  get  the  program 
to  work,  all  the  error  checking  had  to 
be  turned  off.  This  is  easily  done 
with  the  LogiTech  compiler  (via 
compile-time  option  switches),  and  it 
causes  no  problem  whatever  to  the 
accuracy  or  internal  error  checking 
done  by  X68000. 

Just  out  of  curiosity,  I  timed  the 
compilers  on  several  large  modules. 
Both  compilers  use  four  passes, 
which  are  overlayed  from  the  disk. 
The  Hochstrasser  linker  produces  an 
executable  file  directly  whereas  Lo¬ 
giTech’s  requires  an  additional  step 
for  this.  Even  with  the  hard  disk  and 
512K  installed  on  the  IBM  PC,  the  Logi¬ 
Tech  compiler  was  only  about  20 
percent  faster  than  was  the  Hoch¬ 
strasser  compiler. 

The  Verdict 

Porting  X68000  to  the  IBM  PC  using 
the  LogiTech  compiler  was  a  rela¬ 
tively  painless  and  quick  process. 
The  total  time  expended  was  rough¬ 
ly  15  hours — much  of  which  was 
spent  getting  used  to  a  new  compiler. 

If  you  are  already  familiar  with  your 
compiler,  you  should  have  little  trou¬ 
ble  making  the  conversion  in  a  single 
afternoon. 

True  to  form,  the  compiled  code 
is  47  percent  larger  on  "Miss  Piggy” 
than  it  is  on  the  CP/M  system.  Execu¬ 
tion  speed  (of  X68000)  is  essentially 
the  same  on  the  CP/M  and  MS  DOS  ver¬ 
sions. 
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paring  the  pass  1  address  count  (from 
the  symbol  table)  with  the  pass  2  ad¬ 
dress  count  for  any  line  that  has  a  la¬ 
bel.  The  two  instruction  types  that 
use  relative  addressing  modes  are 
handled  as  a  special  case  because  of 
the  odd  requirements  placed  on 
them.  (There  is  no  automatic  selection 
of  the  most  efficient  branch  length. 
The  assembler  assumes  the  worst 
case  and  produces  long  branches  un¬ 
less  explicitly  told  to  use  the  short 


form.  Full  range  checking  is  done  for 
either  long  or  short  branches,  howev¬ 
er.)  Object  code  for  the  balance  of  the 
instructions  is  produced  in  Merge- 
Modes  (described  next). 

Although  the  68000  instruction  set 
is  very  orthogonal  (regular),  there  are 
a  few  instructions  that  have  to  be 
handled  as  special  cases.  That  is  the 
purpose  of  the  CONST  definitions  at 
the  top  of  the  module:  they  are  BIT- 
SET  constants  representing  several 
operation  codes.  These  are  used 
within  the  MergeModes  procedure 
to  take  care  of  the  special  cases  be¬ 


fore  the  more  common  addressing 
modes  are  handled. 

MergeModes  is  not  exported  from 
the  definition  module  of  CodeGenera- 
tor  but  is  used  by  the  GetObjectCode 
procedure  to  combine  information 
from  several  sources  to  produce  the 
hexadecimal  machine  code.  Merge¬ 
Modes  is  at  the  heart  of  the  code  gen¬ 
eration  process.  Many  68000  instruc¬ 
tions  use  a  format  that  is  some 
variation  on  ADD  Dn,<ea>.  The  ef¬ 
fective  address  <ea>  may  be  any  of 
12  addressing  modes,  although  few 
instructions  use  all  12  modes.  There 
are  four  basic  groupings  of  these 
modes — Data,  Memory,  Control,  and 
Alterable — which  may  be  combined 
in  various  ways.  The  local  procedures 
EffAdr  and  QperEyt  determine  the 
bit  patterns  needed  for  the  effective 
addressing  mode  being  used  along 
with  any  operand  extension  needed- 
for  that  addressing  mode.  (For  exam¬ 
ple,  MOVE  D3,600(A2)  requires  that  bit 
patterns  of  000011  and  101010  be  in¬ 
serted  into  the  opcode  for  the  source 
and  destination  operands,  and  an  ex¬ 
tension  word  of  0000001001011000 
needs  to  be  tagged  on  after  the  op¬ 
code  for  the  600  offset.) 

The  bulk  of  MergeModes  cross¬ 
checks  the  addressing  mode  found 
by  GetOperand  with  the  modes  that 
are  allowed  for  the  current  instruc¬ 
tion  (information  from  OPCODE.DAT 
and  the  OperationCodes  module). 
Any  errors  are  passed  onto  the  Er- 
rorX68  module,  where  verbal  error 
messages  are  displayed  on  the  con¬ 
sole.  If  no  errors  are  detected,  vari¬ 
ous  bits  and  pieces  of  information  are 
combined  to  produce  the  machine 
code  for  the  instruction. 

An  example  will  illustrate  typical 
operation  for  the  complete  sequence 
needed  for  code  generation.  This 
comprises  two  steps:  first  converting 
the  source  code  to  an  intermediate 
language  consisting  of  sets,  enumera¬ 
tions,  and  various  integral  values; 
and  then  combining  the  elements  of 
this  intermediate  language  into  Mo¬ 
torola  68000  machine  language. 

ADD  (A2),D6  ;Add  the  data  word 

addressed  by  A2 
;to  data  register  D6 

When  the  Parser  module  is  finished 
with  this  instruction,  you  are  left 
with  three  character  strings:  ADD, 
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(A2),  and  D6.  Parser  passes  ADD  to 
OperationCodes,  which  returns  three 
sets:  {15,  14,  12}  — >  1101  0000  0000 
0000,  ModeA{OpM68D},  and  Mode - 
B(EA05y).  The  first  set  is  the  raw  bit 
pattern  for  this  instruction — that  is, 
the  bit  pattern  without  operand-size 
bits  and  operand  addressing-mode 
bits  added.  The  other  two  sets  specify 
the  addressing  modes  that  the  ADD  in¬ 
struction  can  use  and  are  designations 
internal  and  unique  to  X68000. 

The  Parser  passes  (A2)  and  D6  to  the 
GetOperand  procedure  in  SyntaxAn- 
alyzer  (through  CodeGenerator), 
where  they  are  analyzed.  A  record 
of  type  OpConfig,  which  contains  the 
mode,  value,  size,  and  various  other 
information,  is  provided  for  each  op¬ 
erand.  In  this  example,  those  records 
would  contain  the  following  data: 

(A2)  Mode  — >  ARlnd 

; register  indirect 
Value  — >  none 
Loc  — >  location  on  source  line 
Rn  -->  2 
Xn  — >  none 
Xsize  — >  none 
Xtype  — >  none 

D6  Mode  —  ->  DReg  ;data  register 

Value  — >  none 
Loc  — >  location  on  source  line 
Rn  — >  6 
Xn  — >  none 
Xsize  — >  none 
Xtype  -->  none 

MergeModes  will  take  all  pertinent 
information  from  the  above  to  pro¬ 
duce  the  machine  code  or,  if  there 
are  inconsistencies,  produce  error 
messages. 

An  IF  statement  checks  for  each  of 
the  possible  addressing  modes.  For 
example,  the  IF  OpM68D  IN  AddrMo- 
deA  statement  would  be  used  for  the 
ADD  (A2),D6  instruction  because  ADD 
resulted  in  ModeA{OpM68D}  being 
returned  from  OperationCodes.  The 
Dest.Mode  is  checked  to  see  that  it  is 
DReg  (it  is),  so  the  Dest.Rn  (6)  is  shifted 
left  by  9  and  ORe d  with  Op.  Because 
shift  left  is  not  provided  in  Modula-2, 
I  used  multiplication  to  accomplish 
the  same  thing  (multiplication  by  2  is 
the  same  as  shift  left  1).  Because  of  a 
principle  called  strength  reduction, 
this  multiplication  (by  a  power  of  2)  is 


not  nearly  as  inefficient  as  you  might 
think.  As  part  of  this  same  IF  state¬ 
ment,  the  size  bits  are  Ofied  into  place 
depending  on  the  size  suffix  placed 
on  the  instruction. 

Because  there  is  no  size  suffix  on 
ADD  (A2),D6,  size  WORD  is  assumed. 
The  IF  EA05y  IN  AddrModeB  will  fill 
out  the  operation  with  more  error 
checking  and  a  call  to  the  EffAdr  lo¬ 
cal  procedure  mentioned  above.  This 
procedure  checks  that  the  mode 
used  is  consistent  with  the  instruc¬ 
tion,  then  uses  bitwise  AND/OR  to  ap¬ 
pend  the  correct  bits.  OperEyt  would 
have  nothing  to  do  on  this  instruction 
because  neither  ARlnd  or  DReg  re¬ 
quire  an  operand  extension. 

All  instructions  follow  a  similar 
format:  source  line  — >  line  parts  (la¬ 
bel,  opcode,  operands)  — >  interme¬ 
diate  language  (bitsets,  enumera¬ 
tions,  and  so  on)  — >  machine  code. 
Any  or  all  of  the  processes  involved 
in  reaching  these  states  can  result  in 
error  messages  if  the  source  line  does 
not  conform  to  correct  68000  syntax. 

The  hidden  procedure  ObjDir  is 
the  assembler  directive  equivalent  to 
MergeModes — it  produces  the  code 
for  the  directives.  It  is  essentially  sim¬ 
ilar  to  the  cascaded  IF  ELS1F  ELSE 
statement  that  handles  pseudo-ops  in 
the  BuildSymTable  routine  except 
that  it  has  to  generate  the  code, 
which  means  determining  values 
and  setting  object  code  lengths.  This 
procedure  also  handles  ASCII  strings. 
I’m  not  at  all  satisfied  with  this  sec¬ 
tion  of  code,  and  if  you  think  it  looks 
like  an  afterthought,  you're  right! 
The  awkwardness  results  from  hav¬ 
ing  to  pass  the  string  (which  is  con¬ 
verted  to  LONG )  to  the  output  mod¬ 
ules  as  a  2-byte  opcode  and  two 
4-byte  operands.  The  other  alterna¬ 
tive  was  a  major  rewrite,  which  will 
have  to  wait  until  Version  2  (when  I 
will  have  to  rewrite  some  of  the  code 
to  accommodate  a  linker,  anyway). 

SyntancAnalyzer 

The  procedures  within  SyntaxAna- 
lyzer  (Listing  Eighteen,  next  month) 
are  not  visible  to  any  other  module 
except  CodeGenerator  (it  was  origi¬ 
nally  part  of  the  same  module).  Its 
purpose  is  mainly  to  analyze  the 
operands  of  the  instructions  and  to 
determine  their  value  and  their 
mode. 

CalcValue  and  GetValue  work  to¬ 


gether,  as  their  names  suggest,  to  de¬ 
termine  the  value  of  any  operands 
that  have  a  value.  These  include  deci¬ 
mal  numbers  (0  —  65535);  hexadecimal 
numbers  (0  — SFFFFFFFF);  single 
quoted  ASCII  literals;  the  symbol  for 
the  current  value  of  the  program 
counter  (*);  and  identifiers,  which 
may  represent  any  value.  GetValue 
contains  a  simple  left-to-right  expres¬ 
sion  evaluation  loop  that  recognizes 
only  addition  and  subtraction  opera¬ 
tions.  It  hardly  has  the  elegance  of  a 
recursive  descent  expression  parser, 
but  it  is  simple  and  compact.  GetValue 
uses  the  LOOP . . .  END  construct  with 
three  conditional  EXIT  statements.  Al¬ 
though  this  could  have  been  done 
with  a  REPEAT  loop,  the  termination 
condition  would  have  been  awk¬ 
ward,  with  six  terms,  three  ANDs,  and 
three  ORs.  I  rest  my  case! 

Two  procedures,  called  GetSize 
and  GetAbsSize,  determine  the  size 
of  operands  (BYTE,  WORD,  or  LONG) 
by  looking  for  a  suffix  of  .B,  .W,  or  .L. 
If  no  suffix  is  present,  size  WORD  is 
assumed,  as  required  by  the  Motor¬ 
ola  syntax.  The  GetAbsSize  proce¬ 
dure  actually  creates  a  slightly  non¬ 
standard  syntax  for  this  assembler. 
Most  68000  assemblers  will  automati¬ 
cally  choose  the  WORD  absolute  ad¬ 
dressing  mode  for  addresses  in  the 
ranges  of  8000—0  and  0  — $7FFF  and 
LONG  absolute  addressing  for  higher 
addresses.  X68000  will  always  use 
full  32-bit  addressing  unless  specifi¬ 
cally  instructed  to  do  otherwise.  The 
nonstandard  syntax  is  MOVE 
DO,  $6000.  W. 

The  GetlnstModeSize  uses  a  CASE 
statement  to  return  the  size  of  the  ob¬ 
ject  code,  both  in  terms  of  address 
count  and  in  terms  of  number  of 
hexadecimal  digits  required. 

GetOperand  is  the  workhorse  of 
SyntaxAnalyzer,  as  it  is  responsible 
for  performing  lexical  analysis  on 
the  rather  complex  and  varied  oper¬ 
ands  used  in  68000  assembly  lan¬ 
guage.  Not  much  elegance  here — this 
routine  simply  looks  for  all  the  possi¬ 
ble  addressing  modes.  When  it  finds 
a  good  one,  it  returns  all  necessary 
information  in  the  form  of  the  re¬ 
cord  described  above  under  Code- 
Generator.  If  GetOperand  finds  an 
impossible  addressing  mode  or  an 
out  of  range  register  number,  it  uses 
Error X68  to  report  the  error  to  the 
user  console. 
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GetMultHeg  is  a  routine  that  sorts 
out  the  MOV  EM  instructions.  This  in¬ 
struction  is  like  a  multiple  PUSH  or  j 
multiple  PULL  operation.  MOV  EM  D0- 
D7/A0-A6,-(SP),  for  example,  will 
push  all  68000  address  and  data  regis¬ 
ters  onto  the  stack  with  one  instruc¬ 
tion.  This  is  accomplished  by  a  mask 
that  follows  the  actual  instruction, 
where  each  bit  in  the  mask  repre¬ 
sents  a  register;  if  the  bit  is  set,  that 
register  gets  moved.  The  job  of  Get- 
MultReg  is  to  produce  that  mask  from 
the  register  list.  The  —  indicates  a 
range:  DO— D7  means  all  registers  be¬ 
tween  DO  and  D7  inclusive,  and  the  / 
is  just  a  separator.  My  strategy  was  to 
use  a  flag  and  an  enumeration  type 
along  with  nested  IFs  to  keep  track  of 
what  state  the  calculations  were  in. 
That  made  it  easy  to  detect  errors  be¬ 
cause  it  would  cause  a  transition  to 
j  an  illegal  state.  Just  to  complicate 
j  matters,  the  mask  has  to  be  inverted 
in  certain  cases.  That  function  is  tak¬ 
en  care  of  by  a  conditional  subtrac¬ 
tion  as  the  mask  is  constructed. 

Listing 

The  Listing  module  (Listing  Nineteen, 
next  month)  creates  the  formatted 
program  listing  with  object  code  and 
source  code  together  in  the  usual  for¬ 
mat.  The  StartListing  procedure  does 
nothing  but  print  a  heading  and  ini¬ 
tialize  the  page  count  and  line  count 
variables.  WriteListLine  does  what  its 
name  implies — writes  one  line  of  list¬ 
ing  to  the  file.  Unused  object  code 
fields  will  be  skipped  automatically 
(no  address  is  entered  in  the  case  of 
an  EQJJ  pseudo-op,  for  example).  The 
LongPut  routine  from  LongNumbers 
is  used  to  write  all  object  code  (in 
hexadecimal)  to  the  file. 

Modula-2  file  libraries  do  not  usu¬ 
ally  contain  any  way  to  write  a  string 
to  a  file  ( InOut  and  Teyts  allow  this, 
i  but  that's  another  story),  so  I  had  to 
|  write  a  small  procedure  to  do  that. 

|  The  WriteStrF  outputs  any  string  to  a 
|  file  and  is  used  throughout  Listing. 

The  WriteSymTab  procedure  uses 
information  imported  from  the  Sym- 
bolTable  module  via  ListSymTab  to 
output  a  symbolic  reference  table  at 
the  end  of  the  listing.  ListSymTab 
will  return  the  nth  entry  in  the  sym¬ 
bol  table  each  time  it  is  called.  Both 
WriteListLine  and  WriteSymTab 
make  use  of  a  procedure  called 
CheckPage  to  form-feed  to  the  next 


page  and  print  a  new  page  number. 
The  listing  file  created  by  this  mod¬ 
ule  may  be  dumped  to  a  standard 
printer  with  the  PIP  command. 

Srecord 

Creation  of  S-record  files  (Listing 
Twenty  next  month)  is  a  bit  more 
complicated  than  creation  of  listing 
files.  Count  and  checksum  bytes 
must  be  calculated,  and  it  is  usual  to 
split  the  source  code  into  equal- 
length  records  unrelated  to  the 
length  of  the  68000  instructions  (that 
is,  some  instructions  may  be  split 
with  half  on  one  line  of  the  file  and 
the  rest  on  the  next  line). 

My  strategy  in  this  was  to  accumu¬ 
late  source  code  until  there  was 
enough  to  output  a  16-byte  record, 
output  that  record  (saving  any  extra 
bytes  accumulated  for  the  next  re¬ 
cord),  then  go  back  to  accumulating 
more.  This  necessitated  two  storage 
arrays  and  two  indexes  for  accessing 
them:  Sdata/Sindejc  and  Xdata/Xin- 
dey.  Another  complication  is  that  re¬ 
cords  should  start  on  boundaries  di¬ 
visible  by  16  whenever  possible.  Only 
three  procedures  are  exported  from 
the  definition  module  of  Srecord: 
StartSrec,  WriteSrecLine,  and  End- 
Srec.  Several  other  procedures  that 
are  hidden  within  the  implementa¬ 
tion  module  do  much  of  the  work. 

StartSrec  creates  the  SO  (header)  re¬ 
cord.  This  record  consists  mainly  of 
the  source  file  name  as  ASCII  charac¬ 
ters  represented  in  hexadecimal  for¬ 
mat.  However,  all  S-records  must 
have  an  address  (this  is  always  0  for 
the  header  record),  a  byte  count,  and 
a  checksum.  The  byte  count  includes 
a  count  for  the  address  and  the 
checksum;  the  checksum  is  the  com¬ 
plement  of  the  1-byte  residual  of  the 
sum  of  the  address,  count,  and  data. 

The  WriteSrecLine  procedure  re¬ 
turns  immediately  if  there  is  no  ad¬ 
dress  to  write  out  (this  occurs  on 
blank  source  lines  or  for  EQU  state¬ 
ments  only).  Next,  Xdata  is  trans¬ 
ferred  to  Sdata  if  there  was  anything 
left  over  from  the  previous  call  to 
WriteSrecLine.  If  for  any  reason  the 
address  count  passed  into  WriteSre¬ 
cLine  is  different  from  the  internal 
count,  any  existing  data  is  output  as  a 
complete  S-record,  and  a  new  record 
is  started.  This  would  occur  any  time 
a  new  ORG  statement  is  encountered 
in  the  source  code.  Finally  each  of 


the  ObjOp,  ObjSrc,  and  ObjDest  (ob¬ 
ject  code  for  opcode,  source,  and  des¬ 
tination,  respectively)  are  appended 
to  Sdata.  If  Sdata  now  contains  more 
than  16  bytes,  the  record  is  written 
out  to  the  file  (this  is  detected  by  Ap- 
pendData,  returning  FALSE).  Any  ex¬ 
cess  object  bytes  are  retained  in 
Xdata. 

The  information  in  Sdata  and 
Xdata  is  retained  between  calls  to 
WriteSrecLine  because  these  vari¬ 
ables  are  declared  within  the  module 
j  (not  within  a  procedure).  These  vari¬ 
ables  cannot  be  seen  outside  the  Sre¬ 
cord  module  (local  visibility)  but  re¬ 
main  in  existence  throughout  the 
lifetime  of  the  program  (global  exis¬ 
tence).  In  Pascal,  lifetime  and  visibili¬ 
ty  are  tied  together:  If  a  variable  ex¬ 
ists,  it  is  visible;  if  it  is  not  visible,  it  no 
longer  exists.  That  prevents  local 
j  variables  in  Pascal  from  retaining 
values  between  calls — a  very  useful 
feature,  as  illustrated  here. 

The  EndSrec  procedure  outputs 
any  data  left  over  from  the  final  call 
to  WriteSrecLine  and  then  outputs  a 
fixed  S8  trailer  record. 

Actually  this  even-boundary  and 
consistent-length  business  is  not  re¬ 
quired  by  the  S-record  format  be¬ 
cause  each  S-record  is  totally  autono¬ 
mous  in  that  it  begins  with  both  its 
own  starting  address  and  a  byte 
count.  It  is  traditional  for  Motorola  S- 
records  to  be  formatted  as  described 
above,  however. 

ErrorX68 

Most  error  handling  (except  that  in¬ 
volving  files)  is  done  by  the  ErrorX68 
module  (Listing  Twenty-One,  next 
month).  This  module  defines  an  enu¬ 
meration  type  that  provides  12 
named  error  types.  The  procedure 
Error  outputs  the  line  count  (source 
line  where  the  error  was  found),  the 
source  line  itself,  an  arrow  pointing 
to  the  error,  and  a  verbal  error  mes¬ 
sage.  The  program  is  then  suspended 
until  the  operator  acknowledges  the 
error  by  pressing  any  key  on  the  con¬ 
sole  keyboard.  If  greater  than  500  er¬ 
rors  occur,  the  program  is  terminat- 
I  ed  with  an  appropriate  message. 

I  After  pass  2  is  completed,  WriteEr- 
rorCount  outputs  an  END  OF  ASSEM-  j 
BLY  message  to  both  the  console  and  j 
the  listing  file. 
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Compiling  X68OOO 

Because  many  of  the  modules  within 
X68000  interact  in  complicated  ways, 
the  order  of  compilation  is  critical. 
Specifically  if  ModuleA  imports  ob¬ 
jects  defined  in  ModuleB,  it  is  clear 
that  ModuleB  must  be  compiled  first. 
In  all  cases,  a  definition  module  must 
be  compiled  before  its  implementa¬ 
tion  module  can  be  compiled;  how- 


Compilation  Order  for  X68000 

1 .  CmdLin2.DEF,  CmdLin2.MOD 

2.  LongNumbers.DEF,  LongNumbers. MOD 

3.  Parser.DEF 

4.  CodeGenerator.DEF 

5.  SyntaxAnalyzer.DEF 

6.  SymbolTable.DEF,  SymbolTable.MOD 

7.  OperationCodes.DEF,  OperationCodes. 

MOD 

8.  Listing. def,  Listing. mod 

9.  Srecord.DEF,  Srecord.MOD 

10.  ErrorX68.DEF,  ErrorX68.MOD 

1 1 .  Parser.  MOD 

12.  SyntaxAnalyzer.MOD 

13.  CodeGenerator.MOD 

14.  X68000.MOD 

Table  1 

ever,  it  goes  further  than  that.  The 
definition  module  of  Parser,  for  ex-  ( 
ample,  defines  two  types  ( TOKEN  and 
OPERAND )  that  are  used  in  SymbolTa- 
ble,  CodeGenerator,  SyntaxAnalyzer, 
and  others.  Therefore,  Parser.DEF 
must  be  compiled  before  any  module 
that  depends  on  it.  If  the  correct  or¬ 
der  is  not  followed,  the  compiler  will 
produce  "undefined  identifier”  er¬ 
rors.  Many  similar  situations  exist  in 
any  nontrivial  Modula-2  program. 

'  The  compilation  order  shown  in 
Table  1,  page  55,  avoids  any  prob¬ 
lems  but  is  not  the  only  possible  or¬ 
dering  arrangement.  (A  harmless  cir¬ 
cular  reference  exists  between 
Parser  and  ErrorX68  because  each 
imports  objects  from  the  other.  This 
only  affects  the  order  of  execution  of 
their  respective  initialization  parts 
and  causes  no  problems  of  any  sort.) 

Modula-Z  Design  Strategy 

The  implementation  module  often 
hides  details  not  apparent  in  the  defi¬ 
nition  module.  Obviously  the  algo¬ 
rithm  is  encapsulated  inside  the  im¬ 
plementation  module,  but  it  goes 
further  than  that.  Constants,  types, 
variables,  and  procedures  that  are 
not  visible  from  the  definition  mod-  : 
ule  may  contribute  an  important  I 


finally  possible! 

Conclusion 

Although  X68000  is  a  fully  functional 
program,  I  do  not  consider  it  a  com¬ 
pleted  project  as  several  areas  could 
use  improvement.  Expression  and 
string  evaluation  should  both  be  im¬ 
proved.  The  first  steps  would  be  to  ex¬ 
pand  and  improve  LongNumbers  to 
include  multiplication  and  division 
and  to  improve  efficiency.  This  can 
wait  until  Modula-2  compilers  con¬ 
form  to  the  new  standard  and  add 
long  integer  and  cardinal  data  types. 
Constant  strings  should  be  expanded 
to  at  least  80  characters  per  line.  That 
is  harder  than  it  sounds  because  of 
the  way  parameters  are  passed  to  the 
Listing  and  Srecord  modules. 

Finally  there  is  the  matter  of  a 
linker.  To  adapt  the  assembler  to  pro¬ 
vide  relocation  information  will  re¬ 
quire  some  rewriting  of  existing  code 
and  some  new  code;  however,  many 
of  the  modules  could  be  reused  al¬ 
most  intact.  Then  there  is  the  Linker 
itself — not  a  trivial  task  either.  If  any 
readers  have  further  suggestions  on 
how  X68000  can  be  improved,  please 
pass  them  along  to  me.  Better  yet, 
make  the  changes  yourself  and  hand 
the  program  back  into  the  public  do¬ 
main  in  improved  form. 

Availability 

The  following  is  available  directly 
from  the  author  for  $20  (U.S.): 

1.  A  25-page  X68000  User's  Manual 
that  includes  operating  instructions 
for  the  program  as  well  as  a  descrip¬ 
tion  and  example  of  a  method  to  use 
the  assembler  to  link  several  modules. 

2.  An  8-inch  CP/M  SSSD  disk  or  a  5'A- 
inch  IBM  PC  disk  with  executable  pro¬ 
gram  as  well  as  complete  source 
code  and  several  68000  assembly-lan¬ 
guage  examples. 

DDJ 

(Listings  begin  on  page  80.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  6. 


part  to  the  module's  function.  (For 
example,  the  GetDigit,  IsHEX,  and 
GetHEX  routines  from  LongNumbers 
!  as  well  as  the  LineParts  procedure  j 
from  Parser  are  unknown  to  the  def¬ 
inition  modules,  and  hence  they 
need  not  be  known  by  any  program- 
l  mer  using  these  modules.) 

Additionally  the  module  initializa¬ 
tion  may  play  an  important  role  in 
the  structure  of  the  program,  as  in  the 
!  SymbolTable  module  when  SymTab 
\  is  cleared  and  the  indexes  for  access 
to  the  table  are  set  to  their  starting 
points  or  as  in  OperationCodes  where 
data  is  brought  in  from  a  file.  Finally 
modules  may  be  used  to  control  visi- 
j  bility  and  lifetime  fully:  Nothing  is  vis¬ 
ible  outside  a  module  unless  it  is  ex¬ 
ported,  but  variables  belonging  to 
library  modules  exist  throughout  the 
life  of  the  program.  These  features  al¬ 
low  large  programming  projects  to  be 
constructed  of  modules  of  only  a  few 
closely  related  procedures.  Debug¬ 
ging  is  easier,  and  maintenance  is 
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ARTICLES 


The  Cryptographer’s 

Toolbox 


The  "Infinite  Key  Encryption 
System”  article  in  the  August 
1984  issue  of  DDJ  contains  an 
excellent  tutorial  on  encryption  sys¬ 
tems.  At  the  time  it  was  published,  I 
read  it  with  only  passing  interest,  but 
about  six  months  ago,  I  developed  a 
need  for  this  type  of  utility  and  so  be¬ 
gins  my  story.  The  first  thing  I  did 
was  write  a  shell  cypher  program 
(cypher.c — Listing  One,  page  94).  Be¬ 
cause  I  had  already  written  a  generic 
file  copy  utility  that  allowed  modifi¬ 
cations  during  transfer,  it  was  a  sim¬ 
ple  matter  to  modify  the  argument 
passing  to  include  multiple  keys  and 
add  a  cyphert  )  function  call  to  en¬ 
crypt  the  file  with  a  simple  exclu- 
sive-ORing  algorithm  (cypherl.c— 
Listing  Two,  page  94).  Although  this 
method  did  encrypt  the  file  and  al¬ 
lowed  for  easy  decryption  (using  the 
same  run  string),  there  were  definite 
detectable  patterns  in  the  resultant 
file.  These  patterns,  a  function  of  the 
key  period,  were  easily  found  in  ar¬ 
eas  of  repetitive  characters  (for  ex¬ 
ample,  a  string  of  asterisks  or  spaces). 
Another  drawback  to  this  scheme 
was  the  inability  to  pass  nonprinta- 
ble  characters  in  the  run  string, 
thereby  limiting  the  number  of  en¬ 
cryption  tokens.  So,  it  was  back  to  the 
drawing  board. 

Rereading  the  aforementioned  ar¬ 
ticle  with  renewed  interest,  I  gained 
an  insight  into  the  methods  and 
schemes  of  practical  modern  cy¬ 
phers.  I  don’t  intend  to  cover  these 
concepts,  so  if  you’re  interested  avail 
yourself  of  that  article  and  those  in 


®1985  by  Fred  A.  Scacchitti,  25  Glen¬ 
view  Lane,  Rochester,  NY  14609. 


by  Fred  A.  Scacchitti 


The  strongest  cypher 
schemes  use  a 
combination  of 
transposition  and 
substitution. 


its  bibliography. 

Although  the  article's  tutorial  por¬ 
tion  was  excellent,  I  disagreed  with  a 
few  points  on  implementation.  First, 
there  was  the  code  itself  and  the  inti¬ 
mation  that  assembly  language  was 
required  for  reasonable  speed.  The 
MAC  Assembler  is  used  only  with  CP/ 
M-80,  and  I  wanted  more  portable 
source,  so  I  decided  to  write  it  in  C. 
Second,  I  felt  that  a  random  key  of 
some  prime  length  could  be  generat¬ 
ed  solely  from  the  original  key  (cy- 
pher2.c — Listing  Three,  page  95).  Al¬ 
though  some  keys  may  work  better 
than  others,  a  means  to  evaluate  re¬ 
sults  can  render  this  method  func¬ 
tional.  And  last,  I  disagreed  with  the 
need  for  passing  information  in  the 
encrypted  file.  It  seemed  unneces¬ 
sary  and  cumbersome.  My  goal  was 
to  develop  a  method  that  worked  en¬ 
tirely  from  the  run  string.  Overall, 
though,  I  must  commend  the  work 
done  by  John  Thomas  and  Joan 
Thersites  for  presenting  such  a  com¬ 
plete  treatment  of  their  topic. 

The  Ultimate  Cypher 

The  ultimate  cypher  is  like  the  ulti¬ 


mate  weapon — no  matter  how  so¬ 
phisticated,  an  antiweapon  (anti¬ 
cypher)  can  be  developed  eventually 
if  there  is  a  need.  The  user  must 
make  some  judgments  regarding 
needs  and  level  of  protection.  The 
two  algorithms  mentioned  above  are 
relatively  simple  to  implement  and 
use.  The  same  keys  can  encypher  or 
decypher  the  file,  and  key  order  isn’t 
important. 

The  experts  (and  it  becomes  quite 
obvious)  point  out  that  the  strongest 
cypher  schemes  utilize  a  combina¬ 
tion  of  transposition  and  substitution. 
When  transposition  is  added  howev¬ 
er,  the  order  of  decyphering  must  be 
the  exact  reverse  of  encyphering. 
The  last  cypher  module  contains  an 
algorithm  for  transposing  the  file  to¬ 
kens  along  with  the  random  generat¬ 
ed  key  encryption  scheme  (cy- 
pher3.c — Listing  Four,  page  95).  This 
is  a  small  price  to  pay  for  the  added 
security. 

The  Weed  for  Tools 

As  I  progressed  in  my  quest  for  the 
ultimate  cypher/decypher  algo¬ 
rithm,  I  became  aware  of  the  defi¬ 
ciencies  of  the  standard  CP/M  utili¬ 
ties  at  my  disposal,  so  I  developed  my 
own. 

The  first  tool,  fv.c  (Listing  Five, 
page  97),  replaced  my  CP/M  dump- 
.com.  Dump  provides  a  continual  on¬ 
screen  display  of  the  hex  contents  of 
a  file.  Because  most  encryption  is 
performed  on  text  files,  it  is  benefi¬ 
cial  to  include  the  ASCII  form  along 
with  the  hex.  And,  because  most  al¬ 
gorithms  use  an  exclusive-OR  as  the 
means  of  encryption,  it  is  easy 
enough  to  dump  two  files  and  the  ex- 
clusive-ORed  difference  between 
them. 
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The  next  tool,  fstat.c  (Listing  Six, 
page  98)  calculates  and  displays  the 
statistical  characteristics  of  the  file. 
This  tool  scans  the  file,  counting  the 
occurrences  of  each  element,  and 
provides  a  16  X  16  display  of  the  dis¬ 
tribution  of  characters.  It  calculates 
mean,  median,  mode,  and  range  of 
the  character  distribution  and  dis¬ 
plays  its  histogram.  As  you  might  sus¬ 
pect,  each  file  type  has  a  definite  sig¬ 
nature.  In  fact,  after  limited  use  of 
this  utility,  you  will  be  able  to  recog¬ 
nize  the  histogram  patterns  for  text, 
WordStar,  and  many  other  files. 

While  experimenting  with  various 
schemes,  it  became  obvious  that  the 
most  difficult  file  to  disguise  was  one 
that  contained  a  single  byte  for  every 


entry  or  some  sequential  scheme.  So, 
the  next  task  was  developing  a  utili¬ 
ty  makef.c  (Listing  Seven,  page  100), 
to  generate  a  known  sequential  or 
unicharacter  file  of  some  user-de¬ 
fined  length. 

Finally  the  last  utility  sp.c  (Listing 
Eight,  page  100),  was  a  search  scheme 
I  needed  to  look  for  repetitive  pat¬ 
terns  occurring  within  a  file  and  to 
provide  some  information  regarding 
location  and  depth  of  the  repetition. 
It  also  includes  the  option  to  calculate 
the  delta  characteristics  of  a  file  to 
search  for  repetitive  mathematical  as 
well  as  character  sequences. 

Cypher.c — Listing  One 

The  cypher  shell  program  is  provid¬ 


ed  for  use  "as  is"  or  for  user  modifi¬ 
cation.  It  contains  the  argument-pass¬ 
ing  and  file-handling  source  code 
needed  to  copy  from  an  existing  file 
to  a  new  file  via  a  16K  buffer,  with  a 
cypher  function  being  called  to  en¬ 
crypt  the  file.  (If  the  file  is  less  than 
16K,  the  input  file  name  may  be  the 
same  as  the  output  thus  destroying 
the  original  contents.)  I  chose  a  16K 
buffer  because  it  should  fit  easily 
with  most  compilers.  This  value  may 
be  adjusted  to  meet  individual  com¬ 
piler  needs. 

Any  of  the  three  algorithms  that 
follow  may  be  included  or  linked 
with  this  shell.  Caution  is  recom¬ 
mended  to  ensure  that  the  function 
name  is  appropriate  for  the  method 
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you  use.  The  keys  are  passed  in  the 
CP/M  command  line  and  therefore 
are  limited  by  its  length  as  well  as  the 
argument-passing  capability  of  the  C 
compiler. 

Cypherl  .c — Listing  Two 

This  minimal  cypher  algorithm  uses 
an  exclusive-ORing  scheme  to  en¬ 
crypt  the  file  with  the  keys  passed.  If 
the  user  employs  keys  of  some  prime 
length  and  performs  multiple  passes, 
the  results  can  be  quite  difficult  to  de- 
cypher.  Because  the  keys  are  limited 
to  include  only  printable  characters, 
you  don't  take  full  advantage  of  the 
256  codes  available  for  a  byte. 

Cyphers. c — Listing  Three 

Now  something  a  little  more  difficult 


for  the  code  breaker,  an  algorithm 
that  grew  out  of  the  previous  listing 
and  generates  a  prime-length  key  for 
each  user  key  passed.  One  of  50 
prime  values  (between  1,009  and 
1,999)  is  selected  as  a  function  of  the 
key  passed.  The  prime  key  is  then 
generated  using  a  simple  summing- 
ANDing-exclusive-ORing  algorithm, 
and  the  file  is  encrypted  using  this 
new  key.  If  two  or  more  keys  are 
used,  this  method  guarantees  a  cy¬ 
pher  period  in  excess  of  1,000,000, 
which  is  significantly  larger  than 
most  text  files. 

The  key-generation  scheme  is 
based  entirely  on  the  original  key 
length  and  its  contents,  and  I  fail  to 
see  how  this  can  be  worked  back¬ 


ward  to  regain  the  original,  especial¬ 
ly  if  multiple  keys  are  used.  Some 
keys  will  generate  shorter  periods 
within  the  prime  length,  but  this  is 
easily  tested  with  the  tools  provided. 
I  welcome  feedback  or  suggestions 
for  improving  this  algorithm. 

Cypher3.c — Listing  Four 

Adding  chaos  to  disorder  has  proba¬ 
bly  driven  many  a  code  cracker  to 
drink,  and  this  is  just  what  I'm  trying 
to  accomplish.  I  have  modified  the 
cypher2.c  algorithm  slightly  to  test 
the  first  character  of  each  key 
passed.  If  the  key  begins  with  a  dash 
(-),  then  the  buffer  is  transposed  by 
some  value  between  2  and  17;  other¬ 
wise,  it  encrypts  the  file  using  the  al- 
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gorithm  as  described  above.  This 
simple  but  effective  method  puts  the 
icing  on  the  cake;  however  it  com¬ 
pletely  reverses  the  decryption 
method.  If  the  original  run  string 
was 

cypher  file.txt  file. new  ABRAHAM  -2 
LINCOLN  -3 

then  the  decryption  run  string 
would  be 

cypher  file. new  file.doc  -3  LINCOLN 
-2  ABRAHAM 

Fv.c — Listing  Five 

As  I  mentioned  earlier,  this  is  my  re¬ 
placement  for  the  CP/M  dump  utili¬ 


ty.  It  allows  the  user  to  pass  one  or 
two  files  in  the  run  string  for  display. 
If  one  file  name  is  passed  in  the  run 
string,  the  output  appears  much  like 
the  CP/M  dump.com  output  with  the 
addition  of  the  ASCII  display.  If  two 
file  names  are  passed,  the  output 
consists  of  a  line  from  file  1,  a  line 
from  file  2,  and  a  third  line  contain¬ 
ing  the  exclusive-ORing  of  the  two 
files  (labeled  "dif”).  In  all  cases,  non- 
printable  characters  are  replaced 
with  a  caret  (  '  )  in  the  ASCII  portion 
and  nulls  are  replaced  with  an  equal 
sign  (  =  )  to  readily  identify  compari¬ 
sons  between  two  files.  The  compar¬ 
ative  output  is  purely  a  byte-for-byte 
operation,  and  no  attempt  is  made  to 
realign  the  file  to  comparing  charac¬ 


ters  as  in  a  compare  utility.  The  first 
file  length  controls  display  length. 
Table  1,  page  GO,  shows  an  example 
of  screen  output  from  the  run  string 
<fv  cypherl.c> ,  and  Table  2,  below, 
shows  one  from  the  run  string  <fv 
cypherl.c  cypher2.c> . 

Fstat.c — Listing  Six 

Descriptive  statistics  is  the  name  of 
the  game  here,  and  as  with  any  statis¬ 
tical  evaluation,  you  must  be  brutally 
honest  (at  least  with  yourself)  to 
draw  an  objective  conclusion.  The 
entire  file  is  read,  16K  at  a  time.  As 
you  read,  the  occurrences  of  each  of 
the  256  tokens  are  accumulated  and 
you  obtain  the  sum  of  all  bytes  as 
well  as  the  min  and  may  token  occur- 
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16640  characters  read  from 

0  0  0 
file  CRYPT-TB.ART 

0 

0 

0 

0 

0 

0 

0 

0 

0 

file  mean  =  85  06480/16640  mode  =  32  (  20  hex) 
file  median  =  0  file  range  =  3250  [  min  =  0  max  =  3249  ] 
scale  =156 


0  to  15  =  666 ! 
16  to  31  =  30! 

32  to  47  =  3684! 
48  to  63  =  162! 
64  to  79  =  327 ! 
80  to  95  =  146! 
96 to  111  =  7836! 


112  to  127  = 

3789! 

128  to  143  = 

0! 

144  to  159  = 

0! 

160  to  175  = 

0! 

176  to  191  = 

0! 

192  to  207  = 

0! 

208  to  223  = 

0! 

224  to  239  = 

0! 

240  to  255  = 

0! 

I*  *****  * 
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rences.  The  sum  is  divided  by  the  to¬ 
tal  characters  to  obtain  the  mean,  the 
max  becomes  the  mode,  and  the 
range  is  the  difference  between  min 
and  max.  Next,  the  256-byte  array  is 
copied  to  a  second  array  and  sorted 
to  obtain  the  median. 

With  all  calculations  completed, 
the  numerical  values  of  occurrences 
are  displayed  in  a  16  X  16  display  for 
evaluation.  The  statistical  character¬ 
istics  are  displayed,  and  the  program 
pauses  to  await  some  keyboard  entry 
to  display  the  histogram.  Depressing 
the  space  bar  prints  a  scaled  horizon¬ 
tal  histogram  of  16  groups  (0-15,  16- 
31, .  . 241-256). 

The  ideal  random  file  (which  is 
what  you  want  to  see)  would  have 


the  following  characteristics: 


mean 

mode 

range 

median 

histogram 


127.5 

not  critical 
<  20%  of  the  total 
bytes  divided  by  256 
at  midpoint  of  range 
reasonably  flat 


Remember  I  said  "ideal!”  A  se¬ 
quential  file  will  display  these  ideal 
characteristics  as  well  as  a  true  ran¬ 
dom  file.  Also,  files  that  look  too  good 
statistically  should  be  just  as  suspect 
as  those  that  don't.  Table  3,  below,  is 
the  output  produced  by  this  article 
"as  is,”  and  Table  4,  page  63,  is  the 
output  when  it's  encrypted  with  the 
run  string 


cypher  crypt-tb.art  new  frederick  -1 
angelo  -2  scacchitti  -3 

In  all  fairness,  I  must  state  that 
other,  possibly  better,  statistical 
methods  exist  for  determining  ran¬ 
domness.  I  opted  to  use  descriptive 
statistics  because  they  are  more  easi¬ 
ly  understood  and  implemented. 

Makei.c — Listing  Seven 

This  is  a  simple  enough  utility  but  an 
absolute  necessity  if  you  are  to  evalu¬ 
ate  encryption  schemes.  A  file  name 
of  n  256-byte  blocks  is  created,  and  if 
a  value  between  0  and  255  is  passed, 
the  file  will  be  filled  with  this  value. 
If  no  value  (or  one  that  is  nonnumer¬ 
ic)  is  passed,  each  block  contains  a  se- 
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16640  characters  read  from 

file  NEW 

file  mean  =  126  07580/16640  mode  = 

142  ( 8E  hex) 

file  median  =  65  file  range 

=  45  [  min  = 

41  max 

=  85] 

scale  =  21 

Oto  15  =  1062!!****** 

********** 

******* 

****** 

*  *  * 

* 

16 to  31  =  1054!!****** 

********** 

****** 

*  *  * 

****** 

*  *  *  *  * 

* 

32  to  47  =  1092!!****** 

******* 

****** 

*  *  * 

****** 

*  *  *  *  * 

*  * 

48 to  63  =  1059!!****** 

********** 

******* 

*  *  * 

****** 

******* 

*  *  *  *  * 

* 

64 to  79  =  990!!****** 

********** 

******* 

****** 

*  *  * 

****** 

*  *  * 

80  to  95  =  990!!****** 

****** 

*  *  * 

****** 

******* 

*  *  * 

96  to  111  =  1063!!****** 

********** 

****** 

*  *  * 

****** 

******* 

*  *  *  *  * 

* 

112  to  127  =  1076!!****** 

******* 

****** 

*  *  * 

****** 

******* 

*  *  *  *  * 

*  * 

128 to  143  -  1036!!*’**** 

*  *  * 

144  to  159  =  1049!!****** 

********** 

****** 

*  *  * 

****** 

******* 

*  *  *  *  * 

160  to  175  =  1015!!****** 

******* 

****** 

*  *  * 

******* 

*  *  *  * 

176  to  191  =  1026!!****** 

****** 

*  *  * 

*  *  *  * 

192  to  207  =  1049!!”***’ 

******* 

****** 

*  *  * 

208  to  223  =  1015!!****** 

********** 

******* 

****** 

*  *  * 

****** 

******* 

*  *  *  * 

224  to  239  =  1057!!****** 

******* 

****** 

*  *  * 

******* 

*  *  *  *  * 

* 

240  to  255  -  1007!! . 

******* 

****** 

****** 

*  *  * 
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quential  count  from  0  to  255.  A  bene¬ 
fit  of  this  program  is  its  ability  to 
clean  a  disk.  The  user  simply  creates 
a  file  the  size  of  the  remaining  disk 
space  and  then  erases  it.  This  results 
in  all  free  disk  space  being  set  as  the 
user  defined. 

Sp.c — Listing  Eight 

Along  with  the  fstat  utility  sp.c  con¬ 
firms  or  denies  (maybe  even  ques¬ 
tions)  the  statistical  data  you  have  re¬ 
ceived.  A  brute-force  search  method 
is  used  to  find  matching  character 
strings  in  the  file.  By  default,  the 
search  starts  at  the  first  character 
and  searches  the  first  128  bytes  for  a 
match  of  four  or  more  characters.  If 
the  match  depth  exceeds  the  block 
size  it  is  searching,  the  program  will 
return  to  CP/M  after  displaying  the 
match  data.  If  not,  it  will  continue  in 
its  search.  Block  size  to  search,  mini¬ 
mum  depth  of  comparison,  and  start¬ 
ing  point  in  the  buffer  may  optional¬ 
ly  be  changed  in  the  run  string. 

Also,  if  an  additional  argument  is 
passed  (one  more  than  the  three 
mentioned),  the  software  converts 
the  data  in  the  buffer  to  delta  form — 
that  is,  element [n]  =  element [n]  -  ele¬ 
ment  [n+1]  for  all  data  in  the  buffer. 
After  the  conversion  is  made,  the 
search  scheme  continues  as  before. 
This  feature  allows  you  to  evaluate 
the  file  for  some  mathematical 
sequence. 

One  drawback  to  this  program  as  it 
stands  is  the  limiting  factor  of  the 
buffer  size.  No  attempt  is  made  tc 
search  beyond  it.  This  shouldn't  mat¬ 
ter  for  most  text  files. 

Small-C,  CP/M ,  and 
Miscellaneous 

The  function  chkkbdf  )  enables  you 
to  stop  display  (program)  activity  if 
Ctrl-S  is  depressed.  Following  this 
with  a  Ctrl-C  causes  a  return  to  CP/ 
M,  and  any  other  character  will  al¬ 
low  the  program  to  continue.  This 
function  calls  a  bdos(  )  function,  so 
the  user  may  have  to  modify  this  for 
other  operating  systems.  The 
getchyf  )  function  is  a  noneehuing 
version  of  getcharf  )  that  uses  BDOS 
function  6.  You  can  substitute  get- 
char(  )  for  getchy(  ). 

The  functions  callocf  ),  mallocf  ), 
and  cfreet  )  are  used  for  the  dynamic 
allocation  and  deallocation  of  memo¬ 
ry.  My  allocation/deallocation 
scheme  is  of  the  simple  variety  in 


which  the  programmer  must  pay 
heed  to  order  or  pay  the  conse¬ 
quences.  The  source  code  contained 
here  should  work  with  most  imple¬ 
mentations  of  these  functions. 

Printer  output  can  be  obtained 
from  any  of  the  programs  by  using 
the  CP/M  Ctrl-P  function.  It  was  the 
simplest  method  to  implement. 

Math  functions  (especially  floating 
point)  are  difficult  for  Small-C.  There 
are  several  routines  in  the  fstat. c 
source  that  perform  the  necessary 
long  and  fractional  calculations.  It's 
not  necessary  to  change  these;  how¬ 
ever,  if  your  compiler  supports  floats 
and  longs,  have  at  it. 

Each  program  will  display  the  us¬ 
age  if  entered  without  the  proper 
number  of  arguments  in  the  run 
string.  Also,  because  most  software 
users  begin  to  feel  uncomfortable 
when  their  computer  is  off  some¬ 
where  performing  exotic  calcula¬ 
tions,  each  program  displays  status  to 
the  screen  to  put  these  fears  at  rest. 

Cypher  Benchmarks 

My  version,  written  in  Small-C,  is  ge¬ 
neric  enough  to  adapt  to  any  C  com¬ 
piler.  Bunning  on  a  4-MHz,  Z80-based 
CP/M  system,  it  benchmarks  at  less 
than  IK  per  second  for  file  I/O,  16K 
per  second  for  file  transposition,  and 
approximately  4K  per  second  per 
key  for  encryption.  Key  encryption 
is  difficult  to  benchmark  because  it 
includes  the  time  to  generate  the 
prime-length  key,  which  varies  from 
1,009  to  1,999  characters  in  length. 

And  Finally 

These  tools  should  be  employed  with 
a  measure  of  common  sense.  A 
strong  cypher  is  indicated  only 
when  both  statistically  and  pattern- 
wise  indicated.  (And  it  doesn't  hurt  to 
view  the  file  either.)  My  intent  in  de¬ 
veloping  these  utilities  was  to  pro¬ 
vide  the  cryptographer-programmer 
with  a  means  to  evaluate  the 
strength  of  an  encryption  scheme  as 
well  as  the  resistance  of  schemes  to 
cracking.  Like  most  tools,  however, 
these  can  be  used  for  destructive  as 
well  as  constructive  purposes.  The 
author  assumes  no  liability  for  illegal 
use  of  these  tools  and  sincerely  be¬ 
lieves  they  can  result  only  in  the  de¬ 
velopment  of  stronger  encryption 
schemes.  ddj 
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Listing  One  (Text  begins  on  page  8.) 


**/ 


LJ.C  —  A  printing  utility  for  the  HP  LaserJet 

This  program  prints  a  series  of  files  on  the  LaserJet 
printer.  The  files  are  printed  in  a  "landscape1 1  font  at 
17  characters  to  the  inch.  To  take  advantage  of  this 
density,  two  "pages'1  of  information  from  the  file  are 
printed  on  each  piece  of  paper  (left  and  right  halves) . 

Usage  is:  LJ  filel  file2  file3  ... 

Where  file*  is  a  valid  MS-DOS  filename,  included  on  the 
command  line.  This  program  is  compatible  with  Lattice  C 
on  the  IBM  PC  and  the  HP  Touchscreen  computers . 

Joe  Barnhart  original  version  May  5,  1985 

Ray  Duncan  date  and  time  stamping  May  22,  1985 

Joe  Barnhart  revised  date  stamping  June  6,  1985 

Ray  Moon  modified  for  CI86  December  13,  1985 
&  revised  EOF  test 


♦define  CI86  1  /*  Remove  this  #define  ->  Lattice  C  version  */ 


#ifdef  Cl 86 
♦include  <stdio.h> 

♦else 

♦include  <h\stdio.h> 

♦  endif 

♦define  MAXLINE  56  /‘  maximum  lines  per  page  */ 

♦  define  Page  '/f'  /‘  for  compilers  without  '/f*  */ 

♦define  TAB  8  /*  width  of  one  tab  stop  */ 

♦ifdef  CI86 
typedef  struct  { 

unsigned  short  ax, bx, cx, dx, si,  di, ds, es; 

}  REGSET; 

♦else 

typedef  struct  { 

int  ax,  bx,  cx,  dx,  si,  di; 

}  REGSET; 

♦endif 

main(argc,  argv) 

int  argc; 
char  *  argv [ ] ; 

{ 

int  filenum; 

FILE  ‘fp,  ‘prn,  *fopen(); 


} 


if(  (prn  -  fopen  (  "PRN : 1  1 ,  "w1')  )  —  NULL  ) 

print  f  (  "Error  opening  printer  as  file.\n''); 

else  { 

/*  initialize  the  LaserJet  for  landscape  printing  */ 
fprintf (prn,  "\033E\033&llo\033 (sl7H\033&18d6E‘ •  ); 
for (filenul-1;  filenum  <  argc;  filenum++)  { 
fp  -  fopen  ( argv  [  filenum] ,  "r''); 
if  (fp  —  NULL) 

printf("file  %s  doesn't  exist. \n'',  argv  [filenum]) 

else  ( 

printf("Now  printing  %s\n' ',  argv [ filenum] ) ; 
printfile(fp,  prn,  argv [ filenum] ) ; 
fclose(fp) ; 

) 

fprintf  (prn,  "\015\033E ' ' ) ;  /*  clear  LaserJet  */ 

) 


print  file  (fp,  prn,  filename) 

FILE  ‘fp,‘prn; 
char  ‘filename; 

{ 

int  pagenum  -  1; 
while (  !feof(fp))  { 

fprintf (prn,  "\033&a0r85m5L\015 ' ' ) ;  /‘  set  left  half  ‘/ 

printpage (fp,prn) ;  /*  print  page  ‘/ 

if(  !feof(fp))  {  /‘if  more  ..  ‘/ 

fprintf (prn,  "\033&a0rl71m91L' ' ) ;  /‘set  right  half  */ 
printpage (fp, prn) ;  /*  print  another  */ 

) 

stamp(prn,  filename,  pagenum++);  /‘  title  */ 

fputc (PAGE,  prn);  /*  kick  paper  */ 


printpage ( fp, prn) 

FILE  ‘fp. 


{ 


‘prn; 


int  c, line,  col; 


line  -  col  -  0; 
while (line  <  MAXLINE) 

switch (c  -  fgetc(fp))  { 

case  '\n':  /‘  newline  found  */ 

col  -  0;  /*  zero  column  */ 

line++;  /*  adv  line  cnt 

fputc ( '\n' ,prn) ; 
break; 

case  '\t':  /*  TAB  found  */ 


do 

fputc ( '\ 04 O' , prn) ; 
while  ( (++col  %  TAB)  !-  0); 
break; 


*/ 
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Listing  One  (Listing  continued,  text  begins  on  page  8.) 


/*  page  break  or  */ 


line  -  MAXLINE; 
break; 

fputc(c,prn) ; 

col++; 

break; 


/‘  EOF  found  */ 

/*  force  terminate  ‘/ 

/‘  no  special  case  */ 

/*  print  character  */ 


stamp (prn,  filename, pagenum) 
FILE  ‘prn;~ 
char  ‘filename; 
int  page  num.- 


char  datestr [10],  timestr [10]; 

fprintf  (prn,  "\033&a51171M' ' ) ; 
fprintf (prn,  "\015\033&a58R‘  '); 
fprintf  (prn,  "File:  %-113s,,/  filename); 
fprintf (prn,  "Page  %-3d'',  pagenum); 
timestamp (timestr) ; 
datestamp(datestr) ; 

fprintf(prn,  "  %s  %s'',  datestr,  timestr); 


/*  widen  margins  */ 
/*  move  to  row  58  */ 


datestamp( datestr) 

char  ‘datestr; 

( 

REGSET  regs; 

int  month,  day,  year; 

regs. ax  -  Ox2aOO; 

♦ifdef  CI86 

sysint21  Uregs,  &regs)  ; 

♦else 

int 8 6 (0x21, & regs, firegs) ; 

♦endif 

month  -  (regs.dx  »  8)  &  255; 
day  -  regs.dx  &  255; 
year  -  regs.cx  -  1900; 

sprintf (datestr,  "%02d/%02d/%02d 1 ' ,  month,  day,  year); 


timestamp  (timestr) 

char  ‘timestr; 

REGSET  regs; 
int  hour s, mins; 

regs. ax  -  0x2c00; 

♦ifdef  CI86 

sysint21 (&regs,  &regs)  ; 

♦else 

int86 (0x21, &regs, &regs) ; 

♦  endif 

hours  -  (regs.cx  »  8)  &  255; 
mins  -  regs.cx  &  255; 

sprintf (timestr,  ' x%02d: %02d' ' ,  hours,  mins); 


End  Listing 
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C  CHEST 

UStinCj  On©  (Text  begins  on  page  IS.) 

1  #include  <stdio.h> 

2  # include  <dos.h> 

4  #define 

NUMRCWS 

25 

5  #define 

NUMCOLS 

80 

6  #define 

VIDBASE 

OxbOOOOOOO  /*  Base  address  of  video  screen 

7 

*  in  canonical  form. 

8 

9 

*/ 

10  fdefine 

NORMAL 

0x07  /*  Basic  Attributes.  Only  one  */ 

11  #define 

UNDERLINED 

0x01  /*  of  these  may  be  present.  */ 

12  #define 

REVERSE 

0x70 

13 

14  #define 

BLINKING 

0x80  /*  May  be  ORed  with  the  above  */ 

15  #define 

BOLD 

0x08  /*  and  with  each  other  */ 

16 

. 

18 

19  typedef 

struct 

20  { 

21 

char  letter; 

22 

char  attribute; 

23  } 

24  CHARACTER; 

25 

26  typedef 

CHARACTER 

DISPLAY  [  NUMROWS  ][  NUMCOLS  ]; 

27 

28  static  DISPLAY  far 

Screen  =  (DISPLAY  far  *)  VIDBASE; 

29 

30  /* - 

-*/ 

31 

32  static 

.nt  Row 

=  0; 

33  static 

.nt  Col 

=  0; 

34 

. 

36 

37  static  void  fix 

cur  () 

38  { 

39 

/*  Direct  video  writes  won't  actually  move  the  cursor 

40 

so  we'll  do  that  with  a  ROM-BIOS  call,  move  cur 

41 

*  puts  the  cursor  at  Row.  Col. 

42 

*/ 

43 

44 

union  REGS 

Regs ; 

45 

46 

Regs.h.dh  = 

Row; 

47 

Regs.h.dl  = 

Col; 

48 

Regs.h.bh  = 

0  ;  /*  Use  "active"  video  page 

*/ 

49 

Regs. h. ah  = 

2  ;  /*  Function  2,  set  cursor  position 

*/ 

50 

int86(  0x10, 

&Regs,  &Regs) ;  /*  Video  int 

*/ 

52 

53  /*_  — 

. 

54 

55  void 

set cur  (  row. 

col  > 

56  { 

57 

Row  =  row; 

58 

Col  =  col; 

59 

fix  cur  () ; 

60  } 

61 

62  /*- - 

A  41 

63 

64  void 

getcur(  rowp 

,  colp  ) 

65  int 

*rowp,  *colp; 

66  { 

67 

*rowp  =  Row; 

68 

*colp  ■=  Col; 

69  ) 

70 

71  /* — 

. 

72 

73  void 

d_putc(  c,  attrib  ) 

74  ( 

75 

switch (  c  ) 

76 

i 

77 

case  '\r': 

Col  =  0; 

78 

break; 

79 

80 

case  '\n': 

if (  ++Row  >=  NUMROWS  ) 

81 

Row  =0; 

82 

break; 

83 

84 

case  ' \b' : 

if (  --Col  <  0  ) 

85 

Col  =  0; 

86 

break; 

87 

default : 

88 

(* Screen ) [  Row  ][  Col  ]. letter  =  c 

89 

(♦Screen) [  Row  ] [  Col  ] .attribute  =  attrib  ; 

90 

if (  ++Col  >=  NUMCOLS  ) 

91 

{ 

92 

Col  =  0; 
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93  if (  ++Row  >=  NUMROWS  ) 

94  Row  =  0; 

95  } 

96  break; 

97  } 

98 

99  fix_cur(); 

100  } 

101 

102  /* - */ 

103 

104  void  d_puts (  str,  attrib  ) 

105  register  char  *str; 

106  register  int  attrib; 

107  { 

108  while (  *str  ) 

109  d_putc(  *str++,  attrib  ); 

110  } 

111 

112  /* - */ 

113 

114  void  clrs(  attrib  ) 

115  { 

116  /*  Clears  the  screen.  The  cursor  is  not  moved. 

117  */ 

118 

119  CHARACTER  far  *p  =  (CHARACTER  *)VIDBASE  ; 

120  register  int  i  ; 

121 

122  for (  i  =  NUMROWS  *  NUMCOLS;  — i  >=  0  ;  ) 

123  { 

124  (p  )->letter  =  '  '; 

125  (pf+> ->attribute  =  attrib  ; 

126  } 

127  } 

128 

129  /* - */ 

130 

131  main() 

132  { 

133  clrs  (  NORMAL  ); 

134  setcur  (0,  0  ) ; 

135 

136  d_puts  ("Normal\n\r"/  NORMAL  ); 

137  d_puts ("Normal  blinking\n\r",  NORMAL | BLINKING  ); 

138  djputs ("Reverse\n\r",  REVERSE  ); 

139  d_puts ("Underlined\n\r",  UNDERLINED  ); 

140  d_puts ("Underlined  bold\n\r",  UNDERLINED | BOID  ); 

141  d_puts ("Underlined  blinking  bold\n\r",  UNDERLINED  I  BOLD | BLINKING) ; 

142 

143  exit  (0) ; 

144  } 

End  Listing  One 


Listing  Two 


main  () 

{ 

/*  Exit  status  ==  0  if  SHLEV  environment  exists,  else 
*  exit  status  ==  1 
*/ 

exit (  get env ("SHLEV")  =  0  ); 

} 


End  Listing  Two 


LISTING  THREE 


I 


I  # 

|  shlev 

|  if(  Sstatus  )  then 

|  set env  SHLEV  1 

j  else 

j  set env  SHLEV  " 'expr  3SHLEV  +  1'" 

j  endif 

I  # 

|  set  prompt=" [3SHLEV, ! ]  " 

I 


End  Listings 
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Listing  One  (Text  begins  on  page  42.) 

/* 

*  SINE .C 

*  Plot  sin(x)  vs.  x  on  an  enhanced  color  display  with 

*  an  IBM  enhanced  graphics  adapter  in  the  high  resolution  mode. 

*  Purpose  is  to  test  the  video  routines . 

*  by  Nabajyoti  Barkakati,  Silver  Spring,  MD  20904. 

*/ 


♦include  <stdio.h> 

♦include  <math.h> 

♦define 

BLUE 

1 

/* 

Color  number  1  is 

BLUE 

*/ 

♦define 

RED 

4 

/* 

Color  number  4  is 

RED 

*/ 

♦define 

BOTTOM 

4 

/* 

Bottom  margin 

*/ 

♦define 

TOP 

345 

/* 

Top  margin 

*/ 

♦de fine 

LEFT 

4 

/* 

Left  margin 

*/ 

♦define 

RIGHT 

635 

/* 

Right  margin 

*/ 

♦define 

TWOPI 

6.283 

/* 

Approximate  value 

of  2  Pi 

*/ 

♦define 

main ( ) 

MAXPNT 

100 

/* 

Points  on  the  sinusoid 

*/ 

{ 

int  i,  x,  y,  oldx,  oldy,  midpoint; 
double  xd,  yd,  ampl; 

v_init  (RED) ;  /*  Initialize  the  display  */ 

midpoint  -  (TOP  -  BOTTOM) / 2; 

ampl  -  (double) midpoint  -  (double) BOTTOM; 

oldx  =  LEFT; 
oldy  -  midpoint; 

for  (i-0;  i<**MAXPNT;  i++) 

( 

yd  -  ampl  *  sin(TWOPI  *  ( (double) i) /( (double) MAXPNT) ) ; 
xd  -  ( (double) RIGHT  -  (double) LEFT) *  (double) i  /  (double) MAXPNT; 
x  -  LEFT  +  (int ) xd; 
y  -  midpoint  +  (int) yd; 

/*  Draw  a  line  from  the  old  point  to  the  new  point  */ 

v_draw  (oldx,  oldy,  x,  y,  BLUE) ; 

/*  Save  the  new  coordinates  */ 

oldx  -  x; 
oldy  -  y; 

) 

/*  Draw  a  box  around  the  plot  */ 

v_draw  (LEFT,  BOTTOM,  RIGHT,  BOTTOM,  BLUE) ; 
v_draw  (RIGHT,  BOTTOM,  RIGHT,  TOP,  BLUE); 
v_draw  (RIGHT,  TOP,  LEFT,  TOP,  BLUE) ; 
v_draw  (LEFT,  TOP,  LEFT,  BOTTOM,  BLUE); 

/*  Done  */ 

) 


End  Listing  One 


Listing  Two 

/* 

*  VIDEO. C 

*  This  file  contains  the  video  display  modules.  Uses  the  int86 

*  function  of  Lattice  C  2.14  to  draw  graphs  on  an  enhanced  color 

*  display  with  the  IBM  enhanced  graphics  adapter. 

*  by  N.  Barkakati,  Silver  Spring,  MD  20904. 

*/ 

♦include  <dos.h> 


♦define 

void 

int 

♦define 

EGAMODE 

16 

/* 

EGA  in  high  resolution 

*/ 

♦define 

MAXROW 

24 

♦define 

MAXCOL 

79 

♦define 

MAX Y DOT 

349 

/* 

Max.  columns  and  rows  on 

*/ 

♦define 

MAXXDOT 

639 

/* 

enhanced  color  display 

*/ 

♦define 

BIOS  VIDEO 

16 

/* 

BIOS  Video  service  int.  no. 

*/ 

♦define 

SETMODE 

0 

/* 

Service:  set  video  mode 

*/ 

♦define 

SETCOLOR 

11 

/* 

Service:  set  color  pallette 

*/ 

♦de fine 

WRITE  PIX 

12 

/* 

Service:  write  pixel 

*/ 

static  union  REGS 

xr,yr; 

/* 

See  dos.h  for  explanation 

*/ 

/*  v  _ 

i  n  i  t 

*  Initialize  the 

display. 

Put  it  in  EGA  1 

hi-resolution  mode . 

*  Set 

background 

color. 
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*/ 

void  v_init (bgcolor) 
int  bgcolor; 

/*  ROM  BIOS  Video  functions  —  mode  16  is  EGA  in  high-resolution 
*  (640x350  pixels) 

*/ 

xr.h.ah  -  SETMODE; 
xr.h.al  -  EGAMODE; 
int 86  (BIOSVIDEO,  4xr,  &yr) ; 

/*  Set  color. 

*/ 

xr.h.ah  -  SETCOLOR; 

xr.h.bh  -  0; 

xr.h.bl  -  bgcolor; 

int 8 6  (BIOS_VIDEO#  &xr,  &yr) ; 

/*  Done  */ 

) 

/* - */ 


/* 

*  v  _  d  r  a  w 

* 

*  Draw  a  line  of  specified  color  between  the  two  points  (xl,yl) 

*  and  (x2,y2) .  Uses  Bresenham's  Algorithm  described  in; 

*  J.D.  Foley  and  A.  Van  Dam,  FUNDAMENTALS  OF  INTERACTIVE 

*  COMPUTER  GRAPHICS,  Addison-Wesley ,  1982,  pp. 433-435. 


*/ 

void  v_draw(xl,  yl,  x2,  y2,  color) 
int  xl,  yl,  x2,  y2,  color; 

{ 

int  dx,  dy,  incrl,  incr2,  incr3,  d,  x,  y,  xend,  yend; 
dx  “  abs(x2-xl); 
dy  -  abs(y2-yl); 
if  (dy<-dx) 

(  /*  Absolute  value  of  slope  of  line  is  less  than  1  */ 

if  (xl>x2) 

(  /*  Start  at  point  with  smaller  x  coordinate  */ 

x  -  x2; 

y  -  y2; 

xend  -  xl; 
dy  -  yl-y2; 

) 

else 


( 

x  -  xl;  ^ 

y  -  yi; 

xend  -  x2; 
dy  -  y2-yl; 

) 

d  -  2*dy-dx; 
incrl  -  2*dy; 
incr2  -  2*(dy-dx); 
incr3  -  2* (dy+dx) ; 
putdot  (x,  y,  color) ; 
while  (x  <  xend) 

( 

x  +-  1; 
if  (d  >-  0) 

{ 

if  (dy<-0) 

{ 

d  +-  incrl; 

) 

else 

{ 

y  +-  1; 
d  +-  incr2; 

) 

} 

else 

{ 

if  (dy>-0) 

( 

d  +-  incrl; 

) 

else 

{ 

y  —  i; 

d  +-  incr3; 

) 


/*  Negative  or  zero  slope  */ 


/*  Positive  slope  */ 


/*  Negative  or  zero  slope  */ 


/*  Positive  slope  */ 


) 

) 

else 

{ 

if 

( 


) 

putdot  (x,  y,  color) ; 

/*  end  while  */ 
/*  end  if  */ 

/*  Absolute  value  of  slope  is  greater  than  1  */ 

(yi>y2) 

/*  Start  with  point  with  samller  y  coordinate  */ 

y  -  y2; 

x  -  x2  ; 
yend  -  yl; 
dx  -  xl-x2 ; 


) 

else 

{ 

y  -  yl; 
x  -  xl; 
yend  -  y2; 

) 

d  -  2*dx-dy; 
incrl  -  2*dx; 
incr2  -  2*(dx-dy); 
incr3  -  2* (dx+dy) ; 
putdot  (x,  y,  color); 
while  (y  <  yend) 

{ 


(continued  on  page  77) 


Dr.  Dobb's  Journal,  May  1986 

35 


EGA 


Listing  Two  (Listing  continued;  text  begins  on  page  42.) 


y  +-  1; 

if (d  >-  0) 

{ 

if  (dx  <-  0) 

{ 


/*  Negative  or  zero  slope  */ 


d  +-  incrl; 


x  +-  1; 
d  +-  incr2; 


/*  Positive  slope  */ 


if  (dx  >-  0) 

{ 

d  +-  incrl; 

} 

else 

{ 

x  —  1; 
d  +-  incr3; 


/*  Negative  or  zero  slope  */ 


/*  Positive  slope  */ 


putdot  (x,  y,  color)  ; 


/*  Done  */ 

) 

/* - 


/*  end  while  */ 
/*  end  else  */ 


*  putdot 

* 

*  Put  a  dot  of  specified  color  at  location  (x,y)  on  screen. 

*  Check  if  dot  coordinates  are  within  screen  bounds. 


Convention:  | 


I  Origin  at  lower  left  corner  of  screen. 


void  putdot (x,  y,  color) 
int  x,  y,  color; 

{ 

if  (  x<0  |  x>MAXXDOT  |  y<0  |  y>MAXYDOT  )  return; 

xr.x.dx  -  MAXYDOT  -  y; 
xr.x.cx  -  x; 
xr.h.ah  -  WRITE_PIX; 
xr.h.al  -  color; 
int86  (BIOS_VIDEO,  &xr,  &yr) ; 


End  Listings 
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Listing  Eleven  (Text  begins  on  page  44.) 


IMPLEMENTATION  MODULE  LongNumbers; 

(*  Routines  to  handle  HEX  digits  for  the  X68000  cross  assembler.  *) 
(*  All  but  LongPut  and  LongWrite  are  limited  to  8  digit  numbers.  *) 

FROM  Files  IMPORT 
FILE; 


IMPORT  Terminal; 


(*  These  objects  are  declared  in  the  DEFINITION  MODULE  *) 
CONST 

DIGITS  -  8; 

BASE  -  16; 

TYPE 

LONG  -  ARRAY  [1.. DIGITS)  OF  INTEGER; 


CONST 

Zero  -  30H; 
Nine  -  39H, 
hexA  “  41H, 
hexF  -  46H, 


PROCEDURE  LongClear  (VAR  A  :  LONG) ; 
(*  Sets  A  to  Zero  *) 


BEGIN 

FOR  i  1  TO  DIGITS  DO 
A[i)  0; 

END; 

END  LongClear; 


PROCEDURE  LongAdd  (A,  B  :  LONG;  VAR  Result  :  LONG) ; 
(*  Add  two  LONGs ,  giving  Result  *) 


Carry  :  INTEGER; 
i  :  CARDINAL; 

BEGIN 

Carry  0; 

FOR  i  1  TO  DIGITS  DO 

Result[i]  (A[i)  +  Carry)  +  B [ i ) ; 
IF  Result (i)  >-  BASE  THEN 

Result  ii)  Result [i]  -  BASE; 
Carry  ; -  1; 

ELSE 

Carry  0; 

END; 

END; 

END  LongAdd; 


BEGIN 

IF  ORD  (CommandLine [ 0] )  -  0  THEN 

ArgC  :  —  0;  (*  Nothing  in  Command  Tail  Buffer  *) 

ArgV  NIL; 

ELSE 

i  1;  C  0; 

LOOP 

WHILE  CommandLine [i]  -  '  '  DO  (*  Skip  Blanks  *) 

INC  (i) ; 

END; 

IF  CommandLine [i]  -  0C  THEN  {*  end  of  tail  buffer  *) 

EXIT; 

ELSE 

Arguments [C]  ADR  (CommandLine ( i] ) ; 

INC  (C) ; 

IF  C  -  MAXARGS  THEN 
EXIT; 

END; 

END; 

WHILE  CommandLine [i]  #  '  1  DO  (*  Advance  to  next  Argument  *) 
INC  (i); 

IF  CommandLine (1)  -  0C  THEN 
EXIT; 

END; 

END; 

CommandLine ( i]  0C;  (*  Terminate  Argument  *) 

INC  (i); 

END;  (•  LOOP  *) 

CommandLine (0)  0C;  (*  Command  Tail  must  only  be  used  once  *) 

ArgC  C; 

ArgV  : ■  ADR  (Arguments) ; 

END; 

END  ReadCmdLin; 


End  Listing  Twelve 


Listing  Thirteen 


IMPLEMENTATION  MODULE  Parser; 

(*  Reads  the  Source  file,  and  splits  each  *) 
(*  line  into  Label,  OpCode  £  Operand (s) .  *) 

FRCM  Strings  IMPORT 
STRING; 

FRCM  Files  IMPORT 
FILE,  EOF,  Read; 

FRCM  ErrorX68  IMPORT 
ErrorType,  Error; 


PROCEDURE  LongSub  (A,  B  :  LONG;  VAR  Result  :  LONG) ; 
(*  Subtract  two  LONGs  (A  -  B),  giving  Result  *) 


Borrow  :  INTEGER; 

1  :  CARDINAL; 

BEGIN 

Borrow  0; 

FOR  i  1  TO  DIGITS  DO 

Result(i)  (A(i)  -  Borrow)  -  B [ 1) ; 
IF  Result l 13  <  0  THEN 

Result (i)  Result [ i]  +  BASE; 
Borrow  1; 

ELSE 

Borrow  s-  0; 

END; 

END; 

END  LongSub; 


(*  These  objects  are  declared  in  the  DEFINITION  MODULE  *) 

CONST 

Token Size  -  8; 

OperandSize  »  20; 

TYPE 

TOKEN  -  ARRAY  ( 0 . .TokenSize ]  OF  CHAR; 

OPERAND  -  ARRAY  [0 . .OperandSize]  OF  CHAR; 

VAR 

OpLoc,  SrcLoc,  DestLoc  :  CARDINAL;  (*  location  of  line  parts  *) 
Line  :  STRING; 

LineCount  :  CARDINAL; 


PROCEDURE  GetLine  (f  :  FILE;  VAR  EndFile  :  BOOLEAN); 

(*  Inputs  a  Line  —  up  to  80  characters  ending  in  cr/lf  —  from  a  file. 


PROCEDURE  CardToLong  (n  :  CARDINAL;  VAR  A  :  LONG); 
(*  Converts  CARDINALS  to  LONGs  *) 


BEGIN 

LongClear  (A) ; 


End  Listing  Eleven 


Listing  Twelve 


IMPLEMENTATION  MODULE  CmdLin2; 

(*  Parses  command  line  -  returns  pointer  to  an  array  of  pointer  to  strings 

FRCM  SYSTEM  IMPORT 
ADDRESS,  ADR; 


CONST 

MAXARGS  -  5; 


CommandLine [8 OH]  :  ARRAY  [0..7FH]  OF  CHAR; 
Arguments  :  ARRAY  (0.. MAXARGS  -  1 ]  OF  ADDRESS; 


PROCEDURE  ReadCmdLin  (VAR  ArgC  :  CARDINAL;  VAR  ArgV  :  ADDRESS); 

(*  Gives  count  of  items  in  command  line,  and  an  array  of  pointer  to  them  *) 


i,  C  :  CARDINAL; 


i  ;  CARDINAL; 
ch  :  CHAR; 

PROCEDURE  Get  (VAR  c  :  CHAR)  :  CHAR; 

BEGIN 

IF  NOT  EOF  (f)  THEN 
Read  (f,  c) ; 

RETURN  c; 

ELSE 

EndFile  TRUE; 

END; 

END  Get; 

BEGIN  (•  GetLine  •) 

EndFile  FALSE; 

i  0; 

WHILE  (i  <  MAXLINE)  AND  (Get  (ch)  #  ASCI  I. If)  AND  (NOT  EndFile)  DO 
Line[i]  ch; 

INC  (i); 

END; 

IF  Line [ i  -  1]  -  ASCII. cr  THEN  {*  Strip  cr/lf  -  terminate  with  0C  *) 
Lined  -  1]  0C; 

ELSE 

Line ( i]  0C; 

END; 

INC  (LineCount); 

END  GetLine; 


PROCEDURE  SplitLine  (VAR  Label,  OpCode  :  TOKEN; 

VAR  SrcOp,  DestOp  :  OPERAND); 
(*  Separates  TOKENS  £  OPERANDS  from  Line.  *) 


(continued  on  page  82) 
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Listing  Thirteen 

(Listing  continued,  text  begins  on  page  44.) 


CONST 

Quote  -  47C; 

StringMAX  -  12; 

VAR 

i,  j  :  CARDINAL; 

ParCnt  :  INTEGER;  (*  Tracks  open  parentheses  *) 
c  :  CHAR; 

InQuotes  :  BOOLEAN; 

PROCEDURE  Cap  (ch  ;  CHAR)  ;  CHAR; 

BEGIN 

IF  InQuotes  THEN 
RETURN  (ch); 

ELSE 

RETURN  CAP  (ch)  ; 

END; 

END  Cap; 

PROCEDURE  White  (ch  :  CHAR)  :  BOOLEAN; 

BEGIN 

RETURN  ((ch  -  ASCII. ht)  OR  (ch  »  1  *)); 

END  White; 

PROCEDURE  Delimiter  (ch  :  CHAR)  :  BOOLEAN; 

BEGIN 

RETURN  ((NOT  InQuotes)  AND 

({ch  -  ASCII. ht)  OR  (ch  -  1  ’)  OR  (ch  -  OC))); 

END  Delimiter; 

PROCEDURE  OpDelimiter  (ch  ;  CHAR)  ;  BOOLEAN; 

BEGIN 

RETURN  ((NOT  InQuotes)  AND  (ch  -  ',*)  AND  (ParCnt  -  0)); 

END  (^Delimiter; 

PROCEDURE  Done  (ch  :  CHAR)  :  BOOLEAN; 

(*  look  for  start  of  comment  or  NULL  terminator  *) 

BEGIN 

RETURN  ((ch  -  ';’)  OR  (ch  -  OC)  OR  ((ch  -  •  *’)  AND  (i  -  0))); 
END  Done; 


BEGIN  (»  SplitLine  *) 
i  0; 

InQuotes  FALSE; 

IF  Done  (Line(i])  THEN  (*  look  for  blank  or  all-comment  line  *) 
RETURN; 

END; 

IF  White  (Line [i] )  THEN 
INC  (i); 

WHILE  White  (Line ( i ] )  DO 

INC  (i);  (*  Skip  spaces  (  tabs  *) 

END; 

ELSE  (*  Found  a  Label  *) 

3  0; 

c  Lined]; 

WHILE  (NOT  Delimiter  (c) )  AND  (j  <  TokenSize)  DO 
Label [j]  :«  CAP  (c) ; 

INC  (i);  INC  (j); 
c  Line ( i] ; 

END; 

Label (j]  OC;  (*  terminate  Label  string  *) 

IF  J  -  TokenSize  THEN 
Error  (i,  TooLong) ; 

END; 

WHILE  NOT  Delimiter  (Line(iJ)  DO 

INC  (i) ;  (*  Skip  remainder  of  Too- Long  Token  *) 

END; 

END; 

WHILE  White  (Line ( i] )  DO 
INC  (i); 

END; 

IF  Done  (Line(i])  THEN 
RETURN; 

ELSE  (‘  Found  an  Opcode  *) 

OpLoc  : -  i; 

3  0; 

c  Line | i]; 

WHILE  (NOT  Delimiter  (c))  AND  (j  <  TokenSize)  DO 
Opcode [j]  CAP  (c) ; 

INC  (i);  INC  (j); 
c  Line [ i] ; 

END; 

Opcode [j]  0C; 

IF  j  -  TokenSize  THEN 
Error  (i,  TooLong) ; 

END; 

WHILE  NOT  Delimiter  (Line(iJ)  DO 

INC  (i) ;  (*  Skip  remainder  of  Too-Long  Token  *) 

END; 

END; 

WHILE  White  (Line(i])  DO 
INC  (i); 

END; 

IF  Done  (Hne(i])  THEN 
RETURN; 

ELSE  (»  Found  1st  Operand  •) 

SrcLoc  i; 

3  0; 

ParCnt  0; 
c  Line|i]; 

IF  c  -  Quote  THEN  (•  String  Constant  *) 

SrcOp [ 3]  c; 

INC  (i);  INC  (3); 

REPEAT 

c  Line[i]; 

SrcOp (3)  c; 

INC  (i);  INC  (3); 

UNTIL  (c  -  Quote)  OR  (3  >  StringMAX)  OR  (c  -  0C) ; 

SrcOp ( 3]  0C; 

IF  3  >  StringMAX  THEN 
Error  (i,  TooLong); 

END; 

RETURN;  (*  second  operand  not  allowed  after  string  constant  *) 
ELSE  l*  Normal  Operand  *) 

WHILE  (NOT  Delimiter  (c)  ) 

AND  (NOT  OpDelimiter  (c) ) 

AND  (j  <  OperandSize)  DO 
IF  c  -  Quote  THEN 

(continued  on  page  84) 
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Listing  Thirteen  (Listing  continued,  text  begins  on  page  44.) 


(*  Switched  CAP  function 


InQuotes  NOT  InQuotes;  (*  Toggle  Switch  *) 

END; 

IF  NOT  InQuotes  THEN 
IF  c  -  ’ (•  THEN 
INC  (Parent); 

END; 

IF  c  -  •) ’  THEN 
DEC  (Parent); 

END; 

END; 

SrcOp[j]  j-  Cap  (c) ;  (*  Switched  CAP  function  *) 

INC  (i);  INC  (j); 
c  Line  [i] ; 

END; 

SrcOp ( j]  OC; 

IF  j  -  OperandSize  THEN 
Error  (i,  TooLong) ; 

END; 

END; 

WHILE  (NOT  Delimiter  (Line(i]))  AND  (NOT  OpDelimiter  (Line[i]))  DO 
INC  (i);  (•  Skip  remainder  of  Too-Long  Operand  *) 

END; 

END; 

IF  NOT  OpDelimiter  (Line[i])  THEN 

RETURN;  (*  because  only  one  OPERAND  *) 

ELSE  (*  Found  2nd  Operand  *) 

INC  (i);  (*  Skip  OpDelimiter  (comma)  *) 

DestLoc  i; 

j  0; 

c  Line(i); 

WHILE  (NOT  Delimiter  (c) )  AND  (j  <  OperandSize)  DO 
DestOp [ j]  CAP  (c) ; 

INC  (i);  INC  (j); 
c  : —  Line [ i] ; 

END; 

DestOp [j]  OC; 

IF  j  -  OperandSize  THEN 
Error  (i,  TooLong) ; 

END; 

END; 

END  SplitLine; 


PROCEDURE  LineParts  (f  ;  FILE;  VAR  EndFile  :  BOOLEAN; 

VAR  Label,  OpCode  :  TOKEN; 

VAR  SrcOp,  DestOp  ;  OPERAND); 

(*  Reads  line,  breaks  into  tokens,  on-passes  to  symbol  &  code  generators  *) 


BEGIN 

Line 

GetLine  (f ,  EndFile) ; 


(*  read  a  line  from  the  file  *) 


Label  OpCode  SrcOp  De: 

IF  EndFile  THEN 

Error  (0,  EndErr) ; 

ELSE 

SplitLine  (Label,  OpCode,  SrcOp,  DestOp) ; 
END; 

END  LineParts; 


BEGIN  (*  MODULE  Initialization  *) 

OpLoc  0;  SrcLoc  0;  DestLoc  0;  LineCount  0; 
END  Parser. 


End  Listing  Thirteen 


Listing  Fourteen 


IMPLEMENTATION  MODULE  SymbolTable; 

(*  Initializes  symbol  table.  Maintains  list  of  all  labels,  *) 
(*  along  with  their  values.  Provides  access  to  the  list.  *) 

FROM  LongNumbers  IMPORT 
LONG,  LongClear; 


FROM  Strings  IMFORT 
CompareStr; 


CONST 

MAXSYM 


(»  Maximum  entries  in  Symbol  Table 


'  RECORD 

Name  :  TOKEN; 
Value  :  LONG; 
END; 


SymTab  :  ARRAY  [1.. MAXSYM]  OF  SYMBOL; 

Next  :  CARDINAL;  (*  Array  index  into  next  entry  in  Symbol  Table  *) 
Top  :  INTEGER;  (*  Last  used  array  position  as  seen  by  Sort  *) 


PROCEDURE  FillSymTab  (Label  :  TOKEN;  ' 
(*  Add  a  symbol  to  the  table  *) 

BEGIN 

IF  Next  <■=  MAXSYM  THEN 

SymTab [Next] .Name  Label; 
SymTab [Next] .Value  :«  Value; 
INC  (Next); 

Full  FALSE; 

ELSE 

Full  TRUE; 

END; 

END  FillSymTab; 


TOKEN;  Value  :  LONG;  VAR  Full  :  BOOLEAN) ; 
) 


PROCEDURE  Swap; 

BEGIN 

Temp  SymTab [j]; 

SymTab [j]  SymTab [ j  +  gap]; 

SymTab [j  +  gap]  Temp; 

END  Swap; 

BEGIN  (*  Sort  *) 

Top  Next  -  1; 

gap  (Top  +  1)  DIV  2; 

WHILE  gap  >  0  DO 
i  gap; 

WHILE  i  <-  Top  DO 
j  i  -  gap; 

WHILE  j  >-  1  DO 

IF  CompareStr  (SymTab [J] .Name,  SymTab (J  +  gap] .Name)  >  0  THEN 
Swap; 

END; 

j  j  -  gap; 

END; 

INC  (i); 

END; 

gap  gap  DIV  2; 

END; 

NumSyms  Top; 

END  SortSymTab; 


PROCEDURE  ReadSymTab  (LABEL  :  ARRAY  OF  CHAR; 

VAR  Value  :  LONG;  VAR  Duplicate  :  BOOLEAN)  :  BOOLEAN; 
(*  Passes  Value  of  Label  to  calling  program  —  returns  FALSE  if  the  *) 

(*  Label  is  not  defined.  Also  checks  for  Multiply  Defined  Symbols  *) 


CONST 

Go Lower  -  -1; 
GoHigher  -  +1; 


i,  j,  mid  :  INTEGER; 

Search  :  INTEGER; 

Found  :  BOOLEAN; 
c  :  CHAR; 

Label  :  TOKEN; 

BEGIN 

LongClear  (Value) ; 
Duplicate  FALSE; 

i  0; 

REPEAT 

c  LABEL [i]  ; 

Label [i]  c; 

INC  (i); 

UNTIL  (c  -  0C)  OR  (i  >  8); 


IF  c  #  0C  THEN  (*  Operand  label  too  long  — >  Undefined  *) 
RETURN  FALSE; 

END; 

i  1; 

3  Top; 

Found  FALSE; 

REPEAT  (*  Binary  search  *) 
mid  (i  +  j)  DIV  2; 

Search  CompareStr  (Label,  SymTab [mid] . Name) ; 

IF  Search  *»  GoLower  THEN 
3  mid  -  1; 

ELS  IF  Search  -  GoHigher  THEN 
i  :■»  mid  +  1; 

ELSE  (*  Got  It!  *) 

Found  TRUE; 

END; 

UNTIL  (3  <  i)  OR  Found; 

IF  Found  THEN 

IF  mid  >  1  THEN 

IF  CompareStr  (SymTab(mid) .Name,  SymTab[mid  -  1] .Name) 
Duplicate  TRUE;  (*  Multiply  Defined  Symbol  *) 
END; 

END; 

IF  mid  <  Top  THEN 

IF  CompareStr  (SymTab [mid] .Name,  SymTab(mid  +  1]  .Name) 
Duplicate  TRUE;  (*  Multiply  Defined  Symbol  *) 
END; 

END; 

Value  SymTab [mid] .Value; 

RETURN  TRUE; 

ELSE 

RETURN  FALSE; 

END; 

END  ReadSymTab; 


PROCEDURE  ListSymTab  (i  :  CARDINAL;  VAR  Label  :  TOKEN;  VAR  Value  :  LONG) ; 
(*  Returns  the  i-th  item  in  the  symbol  table  *) 

BEGIN 

IF  i  <  Next  THEN 

Label  SymTab [i] .Name; 

Value  SymTab [i] .Value ; 

END; 

END  ListSymTab; 


BEGIN  (*  MODULE  Initialization  *) 
FOR  Next  1  TO  MAXSYM  DO 
SymTab [Next] .Name  : - 
LongClear  (SymTab [Next] .Value) ; 
END; 

Top  : -  0 ; 

Next  1; 

END  SymbolTable. 


PROCEDURE  SortSymTab  (VAR  NumSyms  :  CARDINAL); 
(•  Sort  symbols  into  alphabetical  order  *) 


End  Listing  Fourteen 


1,  3,  gap  :  INTEGER; 
Temp  :  SYMBOL; 


uses  3  to  go  negative  *) 


(Listing  Fifteen  begins  on  page  86.) 
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Listing  Fifteen  (Listing  continued,  text  begins  on  page  44.) 


IMPLEMENTATION  MODULE  OperationCodes; 

(*  Initializes  lookup  table  for  Mnemonic  Opcodes.  Searches  the  table  *) 
(*  and  returns  the  bit  pattern  along  with  address  mode  information.  *) 

FRCM  Files  IMPORT 

FILE,  FileState,  C^pen,  ReadRec,  Close; 

FRCM  Terminal  IMPORT 

WriteString,  WriteLn; 

FRCM  Strings  IMPORT 
STRING,  CompareStr; 


FOR  i  FIRST  TO  LAST  DO 
ReadRec  (f.  Table 68K [ i] ) ; 
END; 

IF  Close  (f)  #  FileOK  THEN 

(*  Don't  worry  about  it!  *) 
END; 

END  OperationCodes . 


FRCM  Parser  IMPORT 
TOKEN ; 


FRCM  ErrorX68  IMPORT 
ErrorType,  Error; 


End  lasting  Fifteen 


CONST 

FIRST  -  1; 
LAST  -  118; 


(*  First  68000  OpCode  •) 
(*  Last  68000  OpCode  *) 


(*  These  objects  are  declared  in  the  DEFINITION  MODULE  •) 


TYPE 

ModeTypeA  -  (RegMem3, 

Ry02, 

Rx91 1, 
Data911, 
CntR91 1, 
Brnch, 

DecBr, 

Data03, 
Data07 , 
OpM68D, 
OpM68A, 
OpM68C, 
OpM68X, 
OpM68S , 
OpM68R, 

Op  M3  7)  ; 

ModeTypeB  -  (Bit811, 

Size 67, 
Size6, 

Size  12 13A, 

Sizel213, 

Exten, 

EA05a, 

EAOSb, 

EA05c, 

EAOSd, 

EAOSe, 

EA05f, 

EA05x, 

EA05y, 

EAOSz, 

EA611)  ; 

ModoA  -  SET  OF  ModeTypeA; 

ModeB  -  SET  OF  ModeTypeB; 


0  -  Register,  1  -  Memory  *) 

Register  Rx  —  Bits  0-2  *) 

Register  Ry  —  Bits  9-11  *) 

Immediate  Data  —  Bits  9-11  •) 

Count  Register  or  Immediate  Data  *) 
Relative  Branch  *) 

Decrement  and  Branch  *) 

Used  for  VECT  only  *) 

MOVEQ  *) 

Data  *) 

1  Address  *) 

1  Compare  * ) 

1  XOR  •) 

1  Sign  Extension  *) 

1  Register/Memory  *) 

1  Exchange  Registers  *) 

1  BIT  operations  -  bits  8/11  as  switch 
'  00  -  Byte,  01  -  Word,  10  -  Long  *) 

1  0  -  Word,  1  -  Long  *) 

'  01  -  Byte,  11  -  Word,  10  -  Long  *) 
'll-  Word,  10  -  Long  *) 

'  OpCode  extension  required  *) 

'  Effective  Address  -  ALL  *) 

'  Less  1  *) 

1  Less  1,  11  •) 

*  Less  9,  10,  11  •) 

'  Less  1,  9,  10,  11  *) 

*  Less  0,  1,  3,  4,  11  *) 

*  Dual  mode  -  OR/ AND  *) 

*  Dual  mode  -  ADD/SUB  *) 

‘  Dual  mode  -  MOVEM  *) 

*  Used  only  by  MOVE  •) 


Listing  Sixteen 

MODULE  InitOperationCodes; 

(*  Module  to  construct  the  file  containing  the  Operation  Code  Data  Table  *) 
FRCM  Files  IMPORT 

FILE,  FileState,  Create,  WriteRec,  Close; 

FRCM  Terminal  IMPORT 
WriteString,  WriteLn; 

FRCM  Parser  IMPORT 
TOKEN ; 


CONST 

FIRST  -  1; 
LAST  -  118; 


TYPE 

ModeTypeA  -  (RegMem3, 
Ry02, 


0  -  Register,  1  -  Memory  *) 

Register  Rx  —  Bits  0-2  *) 

Register  Ry  —  Bits  9-11  *) 
Immediate  Data  —  Bits  9-11  *) 

Count  Register  or  Immediate  Data  *) 
Relative  Branch  *) 

Decrement  and  Branch  *) 


TYPE 

Table Re cord  -  RECORD 

Mnemonic  :  TOKEN; 
Op  ;  BITSET; 
AddrModeA  :  ModeA; 
AddrModeB  ;  ModeB; 
END; 


Table68K  :  ARRAY  (FIRST .. LAST]  OF  TableRecord; 
i  :  CARDINAL;  (*  index  variable  for  initializing  Table68K  *) 
f  :  FILE; 

PROCEDURE  Instructions  (MnemonSym  :  TOKEN; 

OpLoc  :  CARDINAL;  VAR  Op  :  BITSET; 

VAR  AddrModeA  :  ModeA;  VAR  AddrModeB  :  ModeB); 

(*  Uses  lookup  table  to  find  addressing  mode  i  bit  pattern  of  opcode.  •) 


Data03, 

(*  Used  for  VECT  only  *) 

Data07, 

(*  Branch  &  MOVEQ  *) 

OpM68D , 

(•  Data  ») 

OpM68A, 

(*  Address  *) 

OpM68C, 

(*  Compare  *) 

OpM68X, 

(*  XOR  *) 

OpM68S , 

(*  Sign  Extension  *) 

OpM68R, 

(*  Register/Memory  *) 

OpM37)  ; 

(*  Exchange  Registers  *) 

(Bit8 1 1 , 

(*  BIT  operations  -  bits 

8/i: 

Si ze67 , 

(*  00  -  Byte,  01  -  Word, 

10  ■ 

Size6, 

(*  0  -  Word,  1  -  Long  *) 

Slzel213A, 

(*  01  -  Byte,  11  -  Word, 

10  ■ 

Sizel213, 

(»  11  -  Word,  10  -  Long  1 

‘) 

Exten, 

(*  OpCode  extension  required 

EA05a, 

(*  Effective  Address  -  ALL  *] 

EA05b, 

(*  Less  1  *) 

EA05c, 

(*  Less  1,  11  *) 

EA05d, 

(*  Less  9,  10,  11  *) 

EA05e, 

(»  Less  1,  9,  10,  11  •) 

EA05  f , 

(*  Less  0,  1,  3,  4,  11  *1 

i 

EA05x, 

(*  Dual  mode  -  OR/ AND  *) 

EA05y, 

(*  Dual  mode  -  ADD/SUB  *) 

EA05  z, 

(*  Dual  mode  -  MOVEM  *) 

EA611)  ; 

(*  Used  only  by  MOVE  *) 

CONST 

GoLower  -  -1; 
GoHigher  -  +1; 


ModeA  -  SET  OF  ModeTypeA; 

ModeB  -  SET  OF  ModeTypeB; 

TableRecord  -  RECORD 

Mnemonic  :  TOKEN; 
Op  :  BITSET; 
AddrModeA  :  ModeA; 
AddrModeB  :  ModeB; 
END; 


Table68K  :  ARRAY  (FIRST .. LAST)  OF  TableRecord; 
i  :  CARDINAL;  (*  index  variable  for  initializing  Table68K  *) 
f  :  FILE;  (•  "OPCODE.DAT"  •) 


Top,  Bottom,  Look  :  CARDINAL;  (*  index  to  Op-code  table  *) 

Found  :  BOOLEAN; 

Search  :  INTEGER; 

BEGIN 

Bottom  FIRST; 

Top  LAST; 

Found  FALSE; 

REPEAT  (*  Binary  Search  *) 

Look  (Bottom  +  Top)  DIV  2; 

Search  CompareStr  (MnemonSym,  Table68K (Look) .Mnemonic) ; 

IF  Search  -  GoLower  THEN 
Top  Look  -  1; 

ELS  IF  Search  -  GoHigher  THEN 
Bottom  Look  +  1; 

ELSE  (*  Got  It!  *) 

Found  TRUE; 

END; 

UNTIL  (Top  <  Bottom)  OR  Found; 

IF  Found  THEN 

(*  Return  the  instruction,  mode,  and  address  restristictions  *) 
Op  Table68K[Look] .Op; 

AddrModeA  Table68K [Look] .AddrModeA; 

AddrModeB  Table68K [Look] .AddrModeB; 

ELSE 

Error  (OpLoc,  NoCode) ; 

END; 

END  Instructions; 


WITH  Table68K[i]  DO 
Mnemonic  : -  "ABCD"; 

Op  (IS,  14,  8); 

AddrModeA  ModeA (Rx 911,  RegMem3,  Ry02); 

AddrModeB  ModeB(); 

END; 

INC  (i); 

WITH  Table 68K [ i]  DO 
Mnemonic  : -  "ADD"; 

Op  (15,  14,  12}; 

AddrModeA  ModeA { OpM6 8D ) ; 

AddrModeB  ModeB ( EAOSy] ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "ADDA"; 

Op  (15,  14,  12); 

AddrModeA  ModeA(OpM68A) ; 

AddrModeB  ModeB ( EA05a) ; 

END; 


INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "ADDI"; 

Op  (10,  9); 

AddrModeA  ModeA{); 

AddrModeB  :«  ModeB ( Si ze67 ,  EA05e,  Exten); 
END; 


BEGIN  (*  MODULE  Initialization  *) 

IF  Open  (f,  "OPCODE.DAT")  #  FileOK  THEN 

WriteString  ("Can't  Find  'OPCODE.DAT'."); 
WriteLn; 
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INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  :**  "ADDQ"; 

Op  {14,  12}; 

AddrModeA  :=  ModeA{ Data 911} ; 

AddrModeB  ;»  ModeB {Size 67,  EA05d) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  :•=  "ADDX"; 

Op  {15,  14,  12,  8); 

AddrModeA  ModeA{ RegMem3,  Rx911,  Ry02); 

AddrModeB  ModeB { Size67 } ; 

END; 

INC  (i); 

WITH  Table68K{i]  DO 
Mnemonic  ’AND"; 

Op  {15,  14); 

AddrModeA  ModeA{ OpM68D ) ; 

AddrModeB  ModeB { EA05x) ; 

END; 

INC  (i); 

WITH  Table 68 K{ i]  DO 
Mnemonic  :=  ’  AN  D I " ; 

Op  {9}; 

AddrModeA  ModeA{); 

AddrModeB  ModeB {EAOSe,  Size 67,  Exten); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  :«  "ASL"; 

Op  {15,  14,  13,  8); 

AddrModeA  ModeA{CntR91 1 ) ; 

AddrModeB  :»  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  : “  "ASR"; 

Op  :=  {15,  14,  13); 

AddrModeA  :=  ModeA{CntR91 1 } ; 

AddrModeB  :*  ModeB{); 

END; 

INC  (i); 

WITH  Table68K ( i ]  DO 
Mnemonic  "BCC"; 

Op  {14,  13,  10); 

AddrModeA  :»  ModeA{ Brnch) ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  :■  "BCHG"; 

Op  {6); 

AddrModeA  :*=  ModeA{); 

AddrModeB  ModeB {EA05e,  Exten,  Bit811); 

END; 

INC  (i); 

WITH  Tab le 68K ( i ]  DO 
Mnemonic  "BCLR"; 

Op  {7}; 

AddrModeA  ModeA{); 

AddrModeB  ModeB {EA05e,  Exten,  Bit811); 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "BCS"; 

Op  {14,  13,  10,  8); 

AddrModeA  :=  ModeA{ Brnch) ; 

AddrModeB  :•*  ModeB{); 

END; 

INC  (i); 

WITH  Table68K ( i)  DO 
Mnemonic  :■*  "BEQ"; 

Op  {14,  13,  10,  9,  8); 

AddrModeA  ModeA{ Brnch) ; 

AddrModeB  :•=  ModeB{); 

END; 

INC  (i); 

WITH  Table68K{ i)  DO 
Mnemonic  :=  "BGE"; 

Op  {14,  13,  11,  10); 

AddrModeA  :=  ModeA{ Brnch) ; 

AddrModeB  :*=  ModeB{); 

END; 

INC  (i); 

WITH  Tab !e68K [ i)  DO 
Mnemonic  "BGT"; 

Op  {14,  13,  11,  10,  9); 

AddrModeA  ModeA{ Brnch) ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  :=  "BHI"; 

Op  {14,  13,  9); 

AddrModeA  :*=  ModeA{ Brnch)  ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i) ; 

WITH  Table68K [ i]  DO 
Mnemonic  :=  "BLE"; 

Op  :•*  {14,  13,  11,  10,  9,  8); 

AddrModeA  ModeA{Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "BLS"; 

Op  {14,  13,  9,  8); 

AddrModeA  :=  ModeA{ Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 


Mnemonic  "BLT"; 

Op  {14,  13,  11,  10,  8); 

AddrModeA  :=  ModeA{ Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "BMI"; 

Op  {14,  13,  11,  9,  8); 

AddrModeA  ModeA{ Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K  (  i]  DO 
Mnemonic  "BNE"; 

Op  {14,  13,  10,  9); 

AddrModeA  ModeA{ Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "BPL" ; 

Op  {14,  13,  11,  9); 

AddrModeA  :«  ModeA{ Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table 68 K[ i]  DO 
Mnemonic  :■  "BRA"; 

Op  {14,  13); 

AddrModeA  ModeA{ Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "BSET"; 

Op  {7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB {EA05e,  Exten,  Bit811); 
END; 

INC  (i); 

WITH  Table68K( 1]  DO 
Mnemonic  "BSR"; 

Op  {14,  13,  8); 

AddrModeA  ModeA{ Brnch) ; 

AddrModeB  :»  ModeB{); 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "BTST"; 

Op  {}; 

AddrModeA  ModeA{); 

AddrModeB  ModeB {EA05c,  Exten,  Bit811); 
END; 

INC  {1); 

WITH  Table68K(i]  DO 
Mnemonic  "BVC"; 

Op  {14,  13,  11); 

AddrModeA  ModeA{Brnch) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "BVS"; 

Op  {14,  13,  11,  8); 

AddrModeA  ModeA{Brnch) ; 

AddrModeB  :»  ModeB'}; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "CHK"; 

Op  {14,  8,  7); 

AddrModeA  ModeA{ Rx91 1 } ; 

AddrModeB  ModeB { EA05b) ; 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "CLR"; 

Op  {14,  9); 

AddrModeA  ModeA{); 

AddrModeB  ModeB {Size 67,  EA0 5 e ) ; 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "CMP"; 

Op  {15,  13,  12); 

AddrModeA  ModeA{C^pM68C } ; 

AddrModeB  ModeB { EAOSa) ; 

END; 

INC  (i); 

WITH  Table68K{ i]  DO 
Mnemonic  "CMPA"; 

Op  {15,  13,  12); 

AddrModeA  ModeA{C^jM68AJ ; 

AddrModeB  ModeB  { EA05a)  ; 

END; 

INC  (i); 

WITH  Table68K( i)  DO 
Mnemonic  "CMPI"; 

Op  {11,  10); 

AddrModeA  :=  ModeA{); 

AddrModeB  ModeB{Size67,  EA05e,  Exten); 
END; 

INC  (i); 

WITH  Table68K{i]  DO 
Mnemonic  "CMPM"; 

Op  {15,  13,  12,  8,  3); 

AddrModeA  : -  ModeA{Rx911,  Ry02); 
AddrModeB  ModeB { Size 67 } ; 

END; 

INC  (i); 

WITH  Table68K ( i ]  DO 
Mnemonic  "DBCC"; 

Op  {14,  12,  10,  7,  6,  3); 


AddrModeA  ModeA{ DecBr } ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "DBCS"; 

Op  {14,  12,  10,  8,  7,  6,  3); 

AddrModeA  Mode A { DecBr } ; 

AddrModeB  :=  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "DBEQ"; 

Op  {14,  12,  10,  9,  8,  7,  6,  3); 

AddrModeA  ModeA{ DecBr) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K{ i]  DO 
Mnemonic  "DBF"; 

Op  {14,  12,  8,  7,  6,  3); 

AddrModeA  ModeA{ DecBr ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "DBGE"; 

Op  {14,  12,  11,  10,  7,  6,  3); 

AddrModeA  ModeA{ DecBr ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K { i]  DO 
Mnemonic  "DBGT"; 

Op  {14,  12,  11,  10,  9,  7,  6,  3); 

AddrModeA  ModeA{ DecBr ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[ i)  DO 
Mnemonic  "DBHI"; 

Op  {14,  12,  9,  7,  6,  3); 

AddrModeA  ModeA{DecBr ) ; 

AddrModeB  :■*  ModeB{); 

END; 

INC  (1); 

WITH  Table68K [ i]  DO 
Mnemonic  "DBLE"; 

Op  {14,  12,  11,  10,  9,  8,  7,  6,  3); 
AddrModeA  Mode A { DecBr ) ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  {i) ; 

WITH  Table68K( i)  DO 
Mnemonic  "DBLS"; 

Op  {14,  12,  9,  8,  7,  6,  3); 
AddrModeA  ModeA{ DecBr } ; 

AddrModeB  ModeB{); 

END; 

INC  (1); 

WITH  Table68K(i]  DO 
Mnemonic  "DBLT"; 

Op  {14,  12,  11,  10,  8,  7,  6,  3); 
AddrModeA  ModeA{ DecBr } ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "DBMI"; 

Op  {14,  12,  11,  9,  8,  7,  6,  3); 

AddrModeA  ModeA{DecBr ) ; 

AddrModeB  :=  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  :=  "DBNE"; 

Op  {14,  12,  10,  9,  7,  6,  3); 

AddrModeA  :«  ModeA{ DecBr } ; 

AddrModeB  :»•  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[ i)  DO 
Mnemonic  :=  "DBPL"; 

Op  {14,  12,  11,  9,  7,  6,  3); 
AddrModeA  ModeA(DecBr) ; 

AddrModeB  : -  ModeB { } ; 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  :=  "DBRA"; 

Op  {14,  12,  8,  7,  6,  3); 

AddrModeA  :=  ModeA{ DecBr } ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K(i)  DO 
Mnemonic  :=  "DBT"; 

Op  {14,  12,  7,  6,  3); 

AddrModeA  ModeA{ DecBr ) ; 

AddrModeB  ; •*  ModeB{); 

END; 

INC  (i); 

WITH  Table68K(i)  DO 
Mnemonic  :=*  "DBVC"; 

Op  {14,  12,  11,  7,  6,  3); 

AddrModeA  : “  ModeA{ DecBr } ; 

AddrModeB  :=  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  :«  "DBVS"; 
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Op  {14,  12,  11,  8,  7,  6,  3); 

AddrModeA  ModeA{DecBr J ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "DIVS"; 

Op  {15,  8,  7,  6); 

AddrModeA  Mode A { Rx91 1 } ; 

AddrModeB  ModeB { EA05b } ; 

END; 

INC  (i); 

WITH  Table68K|i]  DO 
Mnemonic  "DIVU"; 

Op  {15,  7,  6); 

AddrModeA  ModeA{Rx91 1 ) ; 

AddrModeB  ModeB{EA05b) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "EOR"; 

Op  {15,  13,  12}; 

AddrModeA  ModeA{OpM68X) ; 

AddrModeB  ModeB{EA05e) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "EORI"; 

Op  {11,  9); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { Si ze67 ,  EA05e,  Exten}; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "EXG" ; 

Op  {15,  14,  8); 

AddrModeA  Mode A { qpM37 ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K [ i)  DO 
Mnemonic  "EXT"; 

Op  {14,  11); 

AddrModeA  ModeA{OpM68S ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 

Mnemonic  "ILLEGAL"; 

Op  {14,  11,  9,  7,  6,  5,  4,  3,  2); 

AddrModeA  ModeA{); 

AddrModeB  :-ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  :»  "JMP"; 

Op  {14,  11,  10,  9,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05 f) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  :■  "JSR"; 

Op  {14,  11,  10,  9,  7); 

AddrModeA  ModeA{); 

AddrModeB  ModeB{EA05f ) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "LEA"; 

Op  {14,  8,  7,  6); 

AddrModeA  ModeA{Rx91 1 ) ; 

AddrModeB  ModeB {EA05f ) ; 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "LINK"; 

Op  {14,  11,  10,  9,  6,  4); 

AddrModeA  ModeA{Ry02); 

AddrModeB  ModeB { Exten } ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "LSL" ; 

Op  {15,  14,  13,  9,  8,  3); 

AddrModeA  ModeA{CntR91 1 } ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "LSR"; 

Op  {15,  14,  13,  9,  3); 

AddrModeA  ModeA{CntR911) ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "MOVE"; 

Op  {); 

AddrModeA  ModeA{); 

AddrModeB  ModeB {Si re 12 13 A,  EA611); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 

Mnemonic  "MOVE A" ; 

Op  { 6); 

AddrMoaeA  ModeA(Rx911) ; 

AddrModeB  ModeB {Si re  12 13,  EA05a) ; 

END; 

INC  {i); 

WITH  Table68K(i)  DO 

Mnemonic  "MOVEM" ; 

Op  {14,  11,  7); 

AddrModeA  ModeA{); 


AddrModeB  ModeB{Size6,  EA05z,  Exten); 
END; 

INC  (i); 

WITH  Table68K ( 1)  DO 

Mnemonic  "MOVEP"; 

Op  {3); 

AddrModeA  ModeA{C^>M68R) ; 

AddrModeB  ModeB {Exten ) ; 

END; 

INC  {i); 

WITH  Table68K [ i]  DO 

Mnemonic  "MOVEQ"; 

Op  {14,  13,  12); 

AddrModeA  ModeA{Data07 ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K ( i]  DO 
Mnemonic  "MULS "; 

Op  {15,  14,  8,  7,  6); 

AddrModeA  ModeA{Rx91 1 ) ; 

AddrModeB  ModeB (EA05b) ; 

END; 

INC  (i) ; 

WITH  Table68K|i]  DO 
Mnemonic  "MULO"; 

Op  {15,  14,  7,  6); 

AddrModeA  ModeA{Rx911) ; 

AddrModeB  ModeB { EAOSb ) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "NBCD"; 

Op  {14,  11); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EAOSe ) ; 

END; 

INC  (i); 

WITH  Table68K(i)  DO 
Mnemonic  "NEG"; 

Op  {14,  10); 

AddrModeA  ModeA{); 

AddrModeB  ModeB {Si re 67,  EAOSe); 

END; 

INC  (i); 

WITH  Table68K[l]  DO 
Mnemonic  "NEGX"; 

Op  {14}; 

AddrModeA  ModeA{); 

AddrModeB  ModeB { Size67 ,  EAOSe); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "NOP"; 

Op  {14,  11,  10,  9,  6,  5,  4,  0); 

AddrModeA  :»  ModeA{); 

AddrModeB  ModeB{); 

END; 

INC  {i); 

WITH  Table68K [ i]  DO 
Mnemonic  "NOT"; 

Op  {14,  10,  9); 

AddrModeA  ModeA{); 

AddrModeB  ModeB{Size67,  EAOSe); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  s-  "OR"; 

Op  {15); 

AddrModeA  ModeA{OpM68D ) ; 

AddrModeB  :»  ModeB {EAOSx} ; 

END; 

INC  (i); 

WITH  Table68K(i)  DO 
Mnemonic  "ORI"; 

Op  {}; 

AddrModeA  ModeA{); 

AddrModeB  ModeB{Size67,  EA05e,  Exten); 
END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "PEA"; 

Op  {14,  11,  6); 

AddrModeA  : -  ModeA{); 

AddrModeB  ModeB {EA05f ) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 

Mnemonic  "RESET"; 

Op  {14,  11,  10,  9,  6,  5,  4); 

AddrModeA  ModeA{); 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K[ 1]  DO 
Mnemonic  :*  "ROL"; 

Op  {15,  14,  13,  10,  9,  8,  4,  3); 
AddrModeA  ModeA{CntR91 1 ) ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "ROR"; 

Op  {15,  14,  13,  10,  9,  4,  3); 
AddrModeA  ModeA{CntR91 1 } ; 

AddrModeB  : ”  ModeB { ) ; 


INC  (i); 

WITH  Table68K[l)  DO 
Mnemonic  "ROXL"; 

Op  {15,  14,  13,  10,  8,  4); 
AddrModeA  ModeA{CntR91 1 } ; 
AddrModeB  ModeB{); 

END; 


INC  (i); 

WITH  Table 68K[i]  DO 
Mnemonic  "ROXR"; 

Op  {15,  14,  13,  10,  4); 

AddrModeA  ModeA{CntR911 ) ; 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table 68K  [  i]  DO 
Mnemonic  "RTE"; 

Op  {14,  11,  10,  9,  6,  5,  4,  1,  0); 

AddrModeA  ModeA{); 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "RTR" ; 

Op  {14,  11,  10,  9,  6,  5,  4,  2,  1,  0); 

AddrModeA  :=*  ModeA{); 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K( i]  DO 
Mnemonic  "RTS"; 

Op  {14,  11,  10,  9,  6,  5,  4,  2,  0); 
AddrModeA  : -  ModeA{ ) ; 

AddrModeB  ModeB  {)*' 

END; 

INC  (i); 

WITH  Table68K  (  i]  DO 
Mnemonic  "SBCD"; 

Op  {15,  8); 

AddrModeA  ModeA{Rx911,  RegMem3,  Ry02); 
AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K( i]  DO 
Mnemonic  "SCC"; 

Op  {14,  12,  10,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05e ) ; 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "SCS"; 

Op  {14,  12,  10,  8,  7,  6); 

AddrModeA  ; “  ModeA{ ) ; 

AddrModeB  ModeB { EAOSe } ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "SEQ"; 

Op  {14,  12,  10,  9,  8,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB {EA05e); 

END; 

INC  (i); 

WITH  Table68K [ i)  DO 
Mnemonic  "SF"; 

Op  {14,  12,  8,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05e } ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "SGE"; 

Op  {14,  12,  11,  10,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EAOSe ) ; 

END; 

INC  (i); 

WITH  Table€8K(i)  DO 
Mnemonic  "SGT"; 

Op  {14,  12,  11,  10,  9,  7,  6); 
AddrModeA  ModeA{); 

AddrModeB  ModeB { EAOSe) ; 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "SHI"; 

Op  s-  {14,  12,  9,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05e ) ; 

END; 

INC  <i); 

WITH  Table68K[i]  DO 
Mnemonic  : -  "SLE"; 

Op  {14,  12,  11,  10,  9,  8,  7,  6); 
AddrModeA  :•  ModeA{); 

AddrModeB  ModeB{EA05e) ; 

END; 

INC  Ci) ; 

WITH  Table68K[ i]  DO 
Mnemonic  "SLS"; 

Op  {14,  12,  9,  8,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05e ) ; 

END; 

INC  (i); 

WITH  Table68K [ i]  DO 
Mnemonic  "SLT"; 

Op  {14,  12,  11,  10,  8,  7,  6)  ; 
AddrModeA  : “  ModeA{); 

AddrModeB  ModeB { EA05e) ; 

END; 

INC  {i); 

WITH  Table68K[i]  DO 
Mnemonic  "SMI"; 

Op  {14,  12,  11,  9,  8,  7,  6); 
AddrModeA  ModeA{); 

AddrModeB  ModeB {EAOSe)  ; 

END; 


(continued  on  page  92) 
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UStinC)  Sixt@@n  (Listing  continued,  text  begins  on  page  44.) 


INC  (i); 

WITH  Table68K{i]  DO 
Mnemonic  "SNE"; 

Op  {I*.  12,  10,  9,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05e ) ; 

END; 

INC  (i); 

WITH  Table68K  [ 1]  DO 
Mnemonic  "SPL"; 

Op  {14,  12,  11,  9,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  ModeB { EA05e ) ; 

END; 

INC  (i); 

WITH  Table 68K [ 1]  DO 
Mnemonic  "ST"; 

Op  i-  {14,  12,  7,  6); 

AddrModeA  :■  ModeA{}; 

AddrModeB  ModeB (£A05e) ; 

END; 

INC  (1); 

WITH  Table68K[i]  DO 
Mnemonic  "STOP"; 

Op  {14,  11,  10,  9,  6,  5,  4,  1); 
AddrModeA  ModeA{); 

AddrModeB  ModeB { Exten ) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "SUB"; 

Op  {15,  12); 

AddrModeA  ModeA{qpM68D); 

AddrModeB  ModeB { EA05y ) ; 

END; 

INC  (i); 

WITH  Table68K[ i]  DO 
Mnemonic  : ■  "SUBA"; 

Op  {15,  12); 

AddrModeA  : -  ModeA{OpM68A) ; 

AdarModeB  :■  ModeB{EA05a) ; 

END; 

INC  (i); 

WITH  Teble68K(i]  DO 
Mnemonic  "SUBI"; 

Op  (10); 

AddrModeA  ModeA{); 

AddrModeB  ModeB {Si re 67,  EA05e,  Exten); 

END; 

INC  (1) ; 

WITH  Table68K[i)  DO 
Mnemonic  s-  "SUBQ"; 

Op  {14,  12,  8); 

AddrModeA  ModeA{ Data 911) ; 

AddrModeB  ModeB{Size67,  EA05d); 

END; 

INC  (1); 

WITH  Table68K [ 1]  DO 
Mnemonic  "SUBX"; 

Op  «-  {15,  12,  8); 


AddrModeA  ModeA{Rx911,  RegMem3 ,  Ry02 ) ; 
AddrModeB  ModeB{Sire67 ) ; 

END; 

INC  (1) ; 

WITH  Table68K(i)  DO 
Mnemonic  "SVC"; 

Op  {14,  12,  11,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  : ~  ModeB { EA05e) ; 

END; 

INC  (i); 

WITH  Table68K[i]  DO 
Mnemonic  "SVS"; 

Op  {14,  12,  11,  8,  7,  6); 

AddrModeA  ModeA{); 

AddrModeB  : -  ModeB { EAO 5e ) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "SWAP"; 

Op  {14,  11,  6); 

AddrModeA  ModeA{Ry02); 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K( ij  DO 
Mnemonic  "TAS"; 

Op  {14,  11,  9,  7,  6); 

AddrModeA  : -  ModeA{); 

AddrModeB  : “  ModeB { EA05e) ; 

END; 

INC  (i); 

WITH  Table68K( i]  DO 
Mnemonic  "TRAP"; 

Op  {14,  11,  10,  9,  6); 

AddrModeA  ModeA(Data03 ) ; 

AddrModeB  : -  ModeB { ) ; 

END; 

INC  (i); 

WITH  Table68K(i]  DO 

Mnemonic  "TRAPV" ; 

Op  {14,  11,  10,  9,  6,  5,  4,  2,  1); 
AddrModeA  ModeA{); 

AddrModeB  ModeB{); 

END; 

INC  (i); 

WITH  Table68K(i]  DO 
Mnemonic  "TST"; 

Op  {14,  11,  9); 

AddrModeA  : -  ModeA{  ) ; 

AddrModeB  ModeB{Size67,  EA05e); 

END; 

INC  (i); 

WITH  Table68K[i)  DO 
Mnemonic  "UNLK"; 

Op  {14,  11,  10,  9,  6,  4,  3); 

AddrModeA  ModeA{Ry02); 

AddrModeB  ModeB  {)»' 


IF  Create  (f,  "OPCODE.DAT")  #  FileOK  THEN 

WriteString  {"Unable  to  create  OpCode  File."); 
WriteLn; 

HALT; 

END; 

FOR  i  FIRST  TO  LAST  DO 

WriteRec  (f,  Table68K (i) )  ; 

END; 

IF  Close  (f)  #  FileOK  THEN 

WriteString  ("Unable  to  close  OpCode  File."); 
WriteLn; 

END; 

END  InitOperationCodes . 


End  Listing  Sixteen 

(to  be  continued  next  month) 
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Listing  One  (Text  begins  on  page  58.) 

/* 

**  cypher. c  File  Cypher  Program  by  F . A . Scacchitti  9/11/85 

**  Written  in  Small-C  Version  2.10  or  later 

**  Copies  from  original  file  to  encrypted  file 

**  using  cypher  key(s)  passed  to  encode  or  decode. 


♦include  <stdio.h> 

♦define  BUFSIZE  16384 

int  fdin,  fdout;  /*  file  i/o  channel  pointers  */ 
int  n,  count; 
char  *inbuf,  *key; 

main (argc, argv)  int  argc,  argv[];  { 
inbuf  -  malloc (BUFSIZE) ; 

/* 

**  Open  file  streams 
*/ 

if(argc  <  4)  { 

printf ("\ncypher  usage:  cypher  <source  file>  <new  file> 

<keyl>  <key2>  .  .  .  <keyN>  <CR>\n")  ; 
exit  ( ) ; 

) 

if ((fdin  =  fopen(argv[l] ,"r") )  — -  NULL)  { 
printf ("\nUnable  to  open  %s\n"/  argv[l]); 
exit ( ) ; 

} 

if ((fdout  -  fopen (argv[2] , "w") )  —  NULL)  ( 
printf ("\nUnable  to  create  %s\n",  argv  [2]); 
exit ( ) ; 

) 

/* 

**  Read  file  -  encode  it  -  write  new  file 
*/ 

do  { 

printf ("-reading  file\n"); 

count  -  read (fdin, inbuf, BUFSIZE) ; 

n-3; 

while (n++  <argc) ( 
key  argv[n-l]; 
cypher (inbuf, count, key) ; 

} 

printf ("-writing  %d  byte  file\n\n",  count); 

write (fdout, inbuf, count) ; 

)  while (count  —  BUFSIZE); 

/*  close  up  shop  */ 

fclose (fdin) ; 
fclose ( fdout) ; 

) 

End  Listing  One 


Listing  Three 

/*  cypher2.c  Cypher  module  by  F .A. Scacchitti 

**  10/11/85 

**  Complex  cypher  module  -  generates  a  key  of  some  prime  length 

**  between  1024  and  2028  bytes  then 

**  encrypts  the  buffer  with  this  key 

*/ 

♦include  <stdio.h> 

♦define  NEWBUF  2000 
♦define  NUMP RIMES  50 

static  int  i,  n,  index,  length,  sum,  keylength; 


static  char  *newkey; 
static  int  prime []  - 

(1009, 

1999, 

1013, 

1997, 

1019, 

1993, 

1021, 

1987, 

1031, 

1979, 

1033, 

1973, 

1039, 

1951, 

1049, 

1949, 

1051, 

1933, 

1061, 

1931, 

1063, 

1913, 

1069, 

1907, 

1087, 

1901, 

1091, 

1889, 

1093, 

1879, 

1097, 

1877, 

1103, 

1873, 

1109, 

1871, 

1117, 

1867, 

1123, 

1861, 

1129, 

1847, 

1151, 

1831, 

1153, 

1823, 

,  1163, 

1813, 

1171, 

1803) 

cypherl (buffer,  num. 

code) 

char  * 

buffer 

,  *code;  int 

/* 

**  allocate  a  buffer 

for  the  generated 

key 

*/ 

newkey  -  malloc (NEWBUF ) ; 

/* 

**  get  keylength  and  sumcheck  for  each  key 
*/ 

keylength  -  sum  -  0; 
while ( (n  -  code [keylength] )  !-  NULL) { 
sum  +■»  n; 
keylength++; 

} 

/* 

**  Select  a  prime  and  generate  a  new  key  that  length 
*/ 

length  -  prime [sum  %  NUMPRIMES] ; 

printf ("-generating  a  %d  byte  key\n", length) ; 

for(i-0;  i<length;  i++) { 
index  -  i  %  keylength; 
sum  -  code [index]  +  sum  &  255; 
newkey [i]  -  code [index]  *  sum; 

} 

/* 

**  encrypt  the  file  with  the  generated  key 
*/ 

printf ("-encoding/decoding  buffer\n") ; 
for(i-0;  i<-num;  i++) 

buffer [i]  -  buffer [i]  A  newkey [i  %  length]; 

/* 

**  get  rid  of  the  buffer 
*/ 

cfree (newkey) ; 

) 


Listing  Two 

/*  cypher l.c  Cypher  module  by  F .A. Scacchitti 

**  10/10/85 


End  Listing  Three 


**  Simple  cypher  module  -  encodes  directly  with  user  keys 

*/ 

♦include  <stdio.h> 
static  int  i,  n,  keylength; 

cypherl (buffer,  num,  code)  char  ^buffer,  *code;  int  num; ( 

/* 

**  get  keylength  for  each  key 
*/ 

keylength  =  0; 

while (code [keylength++ ]  !-  NULL); 
keylength — ; 

/* 

**  encrypt  the  file  with  each  key 
*/ 

printf ("-encoding/decoding  buffer\n") ; 
for  (i=0 ;  i<**num;  i++) 

buffer [i]  -  buffer [i]  A  code[i  %  keylength]; 

) 


Listing  Four 

/*  cypher 3 . c  Cypher  module  by  F .A. Scacchitti 

**  11/09/85 

*  * 

**  Complex  cypher  module  -  generates  a  key  of  some  prime  length 

**  between  1024  and  2028  bytes  then 

**  encrypts  the  buffer  with  this  key 

**  or 

**  if  key  starts  with  a  (dash) 

**  calculate  a  transposition  block  size 

**  and  invert  (transpose)  the  file  in 

**  this  size  blocks 

*/ 

♦include  <stdio.h> 

♦define  DASH  45 
♦define  NEWBUF  2000 
♦define  NUMPRIMES  50 


End  Listing  Two 
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Listing  Four 

(Listing  continued,  text  begins  on  page  58.) 

static  int  i,  j,  n,  index,  length,  sum,  keylength; 
static  char  ‘tbuff,  c; 


Listing  Five 


allocate  a  buffer  for  the  new  key  or  transposition 
tbuff  -  malloc (NEWBUF) ; 

get  keylength  and  sumcheck  for  each  key 


keylength  -  sum  -  0; 
while ( (n  -  code [keylength] ) 
sum  +-  n; 
keylength++; 


do  we  transpose  or  encode  ? 


if ( (c  -  ‘code)  —  DASH) 

transpose (buffer,  num,  code); 
else 

encode (buffer,  num,  code); 


“  get  rid  of  the  buffer 


cfree  (tbuff)  ; 


“  Here's  where  we  transpose 
*/ 

transpose (buff er,  num,  code)  char  ‘buffer,  ‘code;  int  num; { 
length  -  (((sum  +  keylength)  %  16)  &  15)  +  2; 
printf ("-transposing  file  by  %d\n", length) ; 
index  -  0; 
do{ 

for(i  -  0;  i  <  length;  i++) { 
j  -  length  -  i  -  1; 
tbuff [j]  -  buffer[index  +  i]  ; 

} 

for(i  -  0;  i  <  length;  i++) ( 

buffer [index  +  i]  -  tbuff [i] ; 

) 

index  +-  length; 

}while (index  <  count); 


Here's  where  we  encode 


encode (buffer,  num,  code)  char  ‘buffer,  ‘code;  int  num; { 


“  Select  a  prime  and  generate  a  new  key  that  length 


fv.c  File  View/Compare  Program  by  F .A.Scacchitti  9/11/85 

Written  in  Small-C  Version  2.10  or  later 

Dumps  contents  of  single  file  to  screen 
or 

Dumps  contents  of  2  files  and  xored  difference 
Displays  in  hex  and  ascii  form 


[1009, 

1999, 

1013, 

1997, 

1019, 

1993, 

1021, 

1987, 

1031, 

1979, 

♦include  <stdio.h> 

1033, 

1973, 

1039, 

1951, 

1049, 

♦define  BUFSIZE  1024 

1949, 

1051, 

1933, 

1061, 

1931, 

1063, 

1913, 

1069, 

1907, 

1087, 

int  fdinl,  fdin2;  /*  f 

1901, 

1091, 

1889, 

1093, 

1879, 

1097, 

1877, 

1103, 

1873, 

1109, 

int  i,  j,  k,  val,  count, 

1871, 

1117, 

1867, 

1123, 

1861, 

char  ‘inbufl,  ‘inbuf2,  *i 

1129, 

1847, 

1151, 

1831, 

1153, 

main(argc,argv)  int  argc, 

1823, 

1163, 

1813, 

1171, 

1803); 

code) 

char  * 

buffer. 

‘code 

;  int  num; { 

switch  (argc)  { 
case  2: 

dump  file\n"); 
compare  2  files\n"); 


case  3: 

inbufl  -  malloc (BUFSIZE) ; 

if ( (fdinl  -  fopen(argv[l] , "r") )  --  NULL)  { 
printf ("\nUnable  to  open  %s\n",  argv[l]); 
exit  ()  ; 

) 

numdisp  -  1; 
if(argc  --  2)  break; 
case  3: 

inbuf2  -  malloc (BUFSIZE) ; 
difbuf  -  malloc (BUFSIZE) ; 

if ( ( fdin2  -  fopen(argv[2) , "r") )  —  NULL)  { 
printf ("\nUnable  to  open  %s\n",  argv[2]); 
exit  () ; 

) 

numdisp  -  3; 
break; 
defaults 

printf ("\nfv  usage:  fv  <filel>  -  d 

printf ("  fv  <filel>  <file2>  -  com 

exit{); 

) 

total  -  offset  -  0; 

printf ("\n") ; 

do  {  — 

count  -  read (fdinl, inbufl, BUFSIZE) ; 
if (argc  >-  3) { 

read (fdin2, inbuf2, BUFSIZE)  ; 

for(i-0;  i<  count;  i++) 

difbuf [i]  -  inbufl [i]  A  inbuf2[i]; 


for(i-0;  i<  count;  1+-16) ( 

for(k-l;  k  <-  numdisp;  k++) { 

switch  (k)  { 
case  2: 

offset  -  BUFSIZE; 
break; 
case  3: 

offset  -  2  *  BUFSIZE; 
break; 
default: 

offset  -  0; 
break; 

) 

if (k  <  3) 

printf  ("f-%d",  k); 
else 

printf ("dif") ; 

printf ("  %04x  ",i+total); 

for (j-0;  j<-15;  j++) { 

val  -  inbufl [i  +  j  +  offset]; 

printf ("%02x  ",val  <  0  ?  val  -  65280  :  val); 


if (  (c  -  bdos (6, 255) )  —  19) { 
if((c  -  getchxO)  --  3) 
exit  ()  ; 


/‘  hold  on  AS  */ 

/‘  exit  on  AC  ‘/ 

/*  continue  on  AQ  »/ 


length  -  prime [sum  %  NUMP RIMES] ; 

printf ("-generating  a  %d  byte  key\n", length) ; 

for(i-0;  i<length;  i++) { 
index  -  i  %  keylength; 
sum  -  code [index]  +  sum  &  255; 
tbuff [i]  -  code [index]  A  sum; 


encrypt  the  file  with  the  generated  key 


printf ("-encoding/decoding  buffer\n") ; 


for(i-0;  i<-num;  i++) 

buffer [i]  -  buffer [i]  A  tbuff [i  %  length]; 


printf ("  "); 

for (j-0;  j<— 15;  j++)  { 

c  -  inbufl [i  +  j  +  offset]; 
if  (c  >  31) 

putchar (c) ; 
else 

if  (c— 0) 

putchar  (61) ; 
else 

putchar (94) ; 

) 

printf ("\n")  ; 

if(k  —  3)  printf ("\n") ; 


total  +-  count; 

}  while (count  —  BUFSIZE); 


End  Listing  Four 


(continued  on  na.xt  page) 
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Listing  Five 

(Listing  continued,  text  begins  on  page  58.) 

/*  close  up  shop  */ 


fclose ( fdinl ) ; 
if (argc  —  3) 

fclose ( fdin2) ; 

} 


End  Listing  Five 


Listing  Six 

/* 

“  fstat.c  File  Statistics  Program  by  F. A. Scacchitti  10/8/85 

**  Written  in  Small-C  Version  2.10  or  later 

*  * 

“  Scans  file  and  displays  distribution  of 

“  characters. 

**  Calculates  and  displays  mean,  mode,  median 

**  and  range  of  file. 

**  Displays  histogram  of  distribution. 


♦include  <stdio.h> 

♦define  BUFSIZE  16384 

int  fdin;  /*  file  pointer  */ 

int  i,  j,  temp,  value,  count,  total,  ‘file,  ‘sorted; 

int  sum,  hisum,  meansum,  himeansum,  mean,  eflag,  changing; 

int  median,  oddmedian,  range,  min,  max,  mode; 

int  ‘data,  scale; 

char  c,  ‘inbuf; 

main (argc, argv)  int  argc,  argv[];  { 
if (argc  <  2)  { 

printf ("\nfstat  usage:  fstat  cinput  file>\n") ; 
exit  ( ) ; 

) 

if ((fdin  -  fopen(argv[l] ,"r") )  “  NULL)  { 

printf ("\nUnable  to  open  file  %s\n", argv [1 ] ) ; 
exit ( ) ; 

} 

inbuf  -  calloc (BUFSIZE, 1) ; 
file  -  calloc(256,2) ; 
sorted  -  calloc  (256,2) ; 
data  -  calloc (17, 2) ; 
eflag  -  FALSE; 

sum  -  hisum  -  meansum  -  himeansum  -  mean  -  mode  -  j  -  0; 
printf ("reading  the  file-"); 
do  ( 

count  -  read (fdin, inbuf, BUFSIZE) ; 
for(i-0;  i<  count;  i++) { 
value  -  inbuf [i]; 


if (value  <  0) 

value  -  256  +  value; 
file [value] ++; 
if (++sum  —  10000) { 
hisum++; 
sum  -0; 

) 

if ( (meansum  +-  value)  >-  10000) { 
himeansum++; 
meansum  —  10000; 

) 

) 

}  while (count  “  BUFSIZE); 

/* 

“  Calculate  the  mean 
*/ 


printf ("calculating  mean-"); 
do  ( 

if ( (meansum  —  sum)  <  0) 
if (himeansum  >  0) { 
himeansum — ; 
meansum  +-  10000; 

}else( 

meansum  +-  sum; 
eflag  -  TRUE; 
mean — ; 

) 

if ( (himeansum  —  hisum)  <  0) { 
himeansum  +-  hisum; 
eflag  -  TRUE; 

)else( 

mean++; 

) 

)while (eflag  —  FALSE); 


“  Calculate  range,  find  mode  min  and  max,  fill  the  sorted  array 
*/ 


printf ("calculating  range-"); 

min  -  max  -  file[0]; 

for (i  -  0;  i  <-  255;  i++) ( 
sorted [i]  -  file[i]; 
if (file[i]  >  max) ( 
max  -  file [i] ; 
mode  -  i; 

) 

if (file[i]  <  min) 
min  -  filefi] ; 

) 

range  -  max  -  min  +  1; 


/* 

“  Sort  the  sorted  array  to  calculate  median 
*/ 

printf ("sorting  the  array"); 

changing  -  TRUE; 

while (changing) { 

changing  -  FALSE; 

for (i  -  0;  i  <-  254;  i++) 

if(sorted[i]  >  sorted [i+1] ) { 
temp  -  sorted  [i]; 
sorted [i]  -  sorted [i+1]; 
sorted [i+1]  -  temp; 
changing  -  TRUE; 

) 

) 

median  -  (sorted[128]  +  sorted[127])  /  2; 
oddmedian  -  (sorted[128]  +  sorted[127])  %  2; 

/* 

“  Display  the  results 
*/ 

printf ("\n  01234567 

8  9  A  B  C  D  E  F\n")  ; 

for (i  -  0;  i  <-  255;  i++)  { 
printf ("%5d",  file(ij); 
chkkbd ( ) ; 

) 

printf ("\n  %d%04d  characters  read  from  file  %s\n", 

hisum,  sum,  argv[l]); 

printf ("file  mean  -  %d  ",mean) ; 
if ( (himeansum  ||  meansum)  >  0) 

printf ("%d%04d/%d%04d", himeansum, meansum, hisum, sum) ; 
printf ("  mode  -  %d  (  %x  hex)",  mode,  mode); 

printf ("\n") ; 

printf ("file  median  -  %d",  median); 
if (oddmedian) 

printf ("  1/2  "); 
else 

printf  ("  "); 

printf ("  file  range  -  %d  [  min  -  %d  max  -  %d  ] \n", 

range,  min,  max, ) ; 

printf ("\nDepress  spacebar  to  display  histogram  ") ; 
getchar ( ) ; 

/* 

“  Sum  the  data  in  16  groups  of  16  elements  and  find  max.  value 
*/ 

max  -  0; 

for (i  -  1;  i  <-  16;  i+  +  )  ( 
for ( j  -  0;  j  <-  15;  j++) 

data  [i]  +-  file [ (i  -  1)  *  16  +  j]; 
if (data [ij  >  max) 
max  -  data [i] ; 

} 

/‘ 

“  Calculate  scaling  for  plot 
*/ 

scale  -  max  /  50; 
temp  -  max  %  50; 
if (temp  /  scale  >  7) 
scale++; 

printf ("  scale  -  %4d\n\n",  scale); 

/* 

“  Print  data  and  plot  of  histogram 
for  (i  -  0;  i  <-  15;  i++)  ( 

printf  ("  %3d  to  %3d  -  %5d  |  i ",  i  «  16,  (i  *  16)  +  15, 

data [i  +  1 ] ) ; 

temp  -  data[i  +  1]  /  scale; 
if (data [i  +  1]  %  scale  >  0) 
temp++; 

while (temp —  >  0) 
printf  ("‘")  ; 
printf ("\n") ; 

} 

/* 

“  close  up  shop 
*/ 

fclose (fdin) ; 

) 


(continued  on  next  page) 
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CRYPTOGRAPHER’S 
_ TOOLBOX 

Listing  Six 

(Listing  continued,  text  begins  on  page  58.) 


♦include  <stdio.h> 
♦define  BUFSIZE  16384 


int  fdin;  /*  file  i/o  channel  pointers  */ 

int  i,  j,  n,  block,  start,  depth,  count,  limit; 
char  *c,  * inbuf; 

main (argc, argv)  int  argc,  argvf];  { 


chkkbd  ()(  char  c; 

if ( (c  -  bdos (6, 255) )  ■—  19)  /*  hold  on  ~S  */ 

if((c  -  getchxO)  —  3) 

exit();  /*  exit  on  ~C  */ 

)  /*  continue  */ 


End  Listing  Six 


Listing  Seven 

/• 

**  inakef.c  File  Generator  Program  by  F.A.Scacchitti  10/7/85 
*  * 

**  Written  in  Small-C  Version  2.10  or  later 

**  Creates  a  seqential  file  of  characters  from 

**  0  to  255  in  blocks  of  255  bytes. 

**  The  sequential  characters  can  be  replaced 

**  with  any  single  character  desired. 

*/ 

♦include  <stdio.h> 

♦define  BUFSIZE  256 


int  fdout;  /*  file  i/o  channel  pointers  */ 

int  i,  n,  num.- 

char  *outbuf,  value; 

main (argc, argv)  int  argc,  argv[);  { 

/* 

**  Allocate  memory  for  buffer 
*/ 

outbuf  -  malloc (BUFSIZE) ; 

/* 

**  Check  arguments  passed  and  open  file  stream 
*/ 

if (argc  <  3)  { 

printf ("\nraakef  usage:  raakef  <new  file>  <nnnn>  [ddd]\n"); 
printfC  nnnn  -  file  size  in  256  byte  blocks\n"); 
printf (M  ddd  -  optional  alternate  value  in  decimal\n" ) ; 
exit(); 

) 

if ((fdout  -  f open (argv [ 1 J, "wM ) )  —  NULL)  { 

printf ("\nUnable  to  create  %s\n",  argv[l]); 
exit(); 

) 

/* 

**  Convert  file  size  argument  to  integer 
*1 

if  ( (n  -  atoi  (argv  [2] ) )  —  NULL)  exit(); 

/* 

**  Fill  the  buffer  with  0  to  255  sequence 
*/ 

for (i  -  0;  i  <-255;  i++) 
outbuf [i]  -  i; 

/* 

**  Refill  the  buffer  with  a  single  character  if  directed  by  argument 
*/ 

if (argc  —  4) 

if ((value  -  atoi (argv [3] ) )  <  256) 
for (i  -  0;  i  <-255;  i++) 
outbuf [i]  -  value; 

/* 

**  Write  blocks  to  file 
*/ 

for(i— 1;  i  <-  n;  i++) 

if ( (num  -  write (fdout, outbuf, BUFSIZE) )  <  BUFSIZE)  exit(); 

/* 

**  Close  up  shop 
*/ 

fclose( fdout) ; 

) 

End  Listing  Seven 

Listing  Eight 


/* 

**  Set  defaults 
*/ 

block  -  128; 
depth  -  4; 
start  -  0; 

I* 

**  Allocate  memory  for  buffer 
*/ 

inbuf  -  malloc (BUFSIZE) ; 

/* 

••  Check  arguments  passed  and  open  file  stream 
*/ 

if(argc  <  2)  { 

printf ("\nsp  usage:  sp  <source  file>  (nnnn)  (dddd)  (ssss)  [x]\n"); 
printfC  nnnn  -  block  size  to  search  default  -  128\n")  ; 

printfC  dddd  -  minimum  depth  of  comparison  default  -  4\n"); 

printfC  ssss  -  starting  point  in  buffer  default  -  0\n")  ; 
printfC  x  -  any  char,  gen's  difference  buffer  ( (n+1 ) -n)  \n")  ; 
exit()  ; 

» 

if ( (fdin  -  fopen (argv ( 1 ) , "r") )  —  NULL)  { 
printf ("\nUnable  to  open  %s\n",  argv(l)); 
exit(); 

) 

/* 

••  Convert  optional  inputs  to  integer  and  implement 
•/ 

if(argc  >  2) 

if  ( (n  -  atoi <argv(2] ) )  !-  NULL) 
block  -  n; 

if(argc  >  3) 

if  ( (n  -  atoi  (argv(3)) )  !-  NULL) 
depth  -  n; 

if(argc  >  4) 

if ( (n  -  atoi  (argv(4) ) )  !-  NULL) 
start  -  n; 

/* 

**  Fill  the  buffer  with  as  much  as  possible 

•/ 

count  -  read(fdin. inbuf, BUFSIZE) ; 
limit  -  count  -  depth; 

/* 

**  If  there's  a  sixth  argument,  convert  the  file  to  numerical  sequence 

*/ 

if  (argc  >  5)  { 

for(i  -  0;  i  <  count  -  1;  i++) 

inbuf (i)  -  inbuf (i  +  1)  -  inbuf (i); 

) 

for(i  -  start;  i  <  block;  i++){ 

printf ("%c",  (i  %  10  —  0)  7  'I '  s  '.'); 
chkkbd ( ) ; 

for(j  -  i  +  1;  j  <-  limit;  j++) 
if (inbuf (i)  —  inbuf (j) ) ( 

if((n  -  chkdepthd,  j,  0))  >-  depth) 

print f ("\nmatch  at  %d  (%x  hex)  and  %d  (%x  hex)  - 
%d  deep\n",  i,  i,  j,  j,  n) ; 

if(n  >-  block)  exit(); 

) 

) 

/• 

**  Close  up  shop 
•/ 

printf ("\n") ;  /•  Flush  print  buffer  */ 

fclose ( fdin) ; 

) 

chkdepth (pointer,  offset,  k) int  pointer,  offset,  k; ( 


while(inbuf [pointer)  ~  inbuf (offset)  ii  k  <  count) { 
pointer++ ; 
of  fset»  +  ; 
k+  +  ; 

) 

return (k) ; 

) 

chkkbd ( ) ( 

char  c; 

i f ( (c  -  bdos (6,255))  —  19) (  /*  hold  on  -S  */ 

if((c  -  getchxO)  --  3) 

exit();  /“  exit  on  ~C  •/ 

)  /*  continue  */ 

) 


/* 

**  sp.c  Search  Pattern  Program  by  F.A.Scacchitti  10/15/85 

**  Written  in  Sraall-C  Version  2.10  or  later 

** 

**  Searches  file  for  repetitive  pattern. 

*  * 

*’  End  Listings 
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Listing  One  (Text  begins  on  page  106.) 


name  window 
page  , 132 

title  BIOS  Window  Extension  VI. 1 

comnent  \ 

Copyright  1984  John  J.  Seal 

The  Graphic  Software  Company 
348  East  Pratt  Street 
Franklin,  IN  46131 

This  program  may  be  used  for  any  non-cortmercial  purpose 
provided  that  this  copyright  notice  is  included. 

Commercial  use  is  forbidden  without  the  express  written 
consent  of  The  Graphic  Software  Company. 

This  program  allows  a  window  to  be  defined  on  the  display. 
All  programs  which  use  the  BIOS  Write  TTY  call  for  output 
will  work  within  the  window.  Other  BIOS  calls  may  still  be 
used  for  I/O  to  arbitrary  screen  positions. 

The  window  is  defined  by  a  pair  of  coordinates  specified  on 
the  command  line.  The  only  absolute  format  requirements  are 
that  each  coordinate  pair  start  with  a  left  parenthesis  and 
be  separated  with  a  comma.  Everything  else  is  optional.  The 
suggested  command  format  is: 

window  (ur,  lc)  to  (lr,  rc) 

ur  =  upper  row 
lc  *  left  column 
lr  “  lower  row 
rc  =  right  column 

The  new  functions  serviced  by  the  video  interrupt  (int  10) 
and  their  corresponding  function  codes  are: 


ah  =  14 
ah  =  16 
ah  =  17 
ah  -  18 

\ 

Write  TTY 

Set  window  coordinates 

Get  window  coordinates 

Get  blanking  attribute 

code 

segment 
org  • 

lOOh 

;For  COM  conversion 

assume 

cs : code 

DOS_ent  ry 

label 

jmp 

far 

install 

;D0S  entry  point 

upper  left 

left 

upper 

lower_right 

right 

lower 

label 

db 

db 

label 

db 

db 

word 

0 

0 

word 

79 

24 

; Window  coordinates 

old_int 

dd 

o 

;01d  interrupt  vector 

comment 

\ 

The  new  interrupt  procedure  first 
services  from  the  old,  and  passes 
back  to  the  BIOS. 

filters  out  the  new 
all  old  service  calls 

\ 


interrupt 

proc 

sti 

far 

cmp 

ah,  14 

; Write  TTY 

je 

write  tty 

cmp 

ah,  16 

;Set  window 

je 

set  window 

cmp 

ah,  17 

;Get  window 

je 

get  window 

cmp 

ah,  18 

;Get  blanking 

je 

get  blanking 

bios: 

jmp 

old_int 

comment 

\ 

Set  window  coordinates. 

This  function  call  sets  the  coordinates  of  a  window  in  the 
display  area.  The  window  is  defined  by  specifying  the  upper 
left  and  lower  right  corners  in  terms  of  screen  coordinates 
The  upper  left  comer  of  the  screen  is  position  (0,0).  The 
specified  comers  are  included  in  the  window  area. 

If  the  specified  coordinates  are  legal  then  the  window  is 
cleared,  the  cursor  is  homed  to  the  upper  left  comer,  and 
al  “  0.  Otherwise,  no  action  is  taken  and  al  =  1. 
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16-BIT 

(Listing  continued,  text  begins  on  page  106.) 

push 

ax 

/Save  registers 

push 

bx 

push 

cx 

push 

dx 

push 

ax 

;Save  character 

mov 

ah,  3 

;Read  cursor  position 

int 

lOh 

pop 

ax 

/Recover  character 

<• 

Check 

for  unprintable  control  characters 

cmp 

al,  8 

;  Backspace 

je 

bs 

cmp 

al,  10 

/Line  feed 

je 

If 

cmp 

al,  13 

/Carriage  return 

je 

cr 

Character  is  printable 

mov 

cx,  1 

/Print  character 

mov 

ah,  10 

int 

lOh 

inc 

dl 

/Advance  cursor 

cmp 

dl,  right 

jbe 

set_cursor 

Right 

edge  of  window  exceeded  -  wrap 

to 

next  line 

mov 

dl, left 

If: 

inc 

dh 

cmp 

dh, lower 

jbe 

set_cursor 

-• 

Lower 

edge  of  window  exceeded  -  scroll 

window  up 

push 

bx 

/Save  page 

mov 

ah,  18 

/Read  blank  attribute 

int 

lOh 

mov 

cx, upper  left 

/Scroll  window  up 

mov 

dx,  lower  right 

mov 

ax, 601h 

int 

lOh 

pop 

bx 

/Restore  page 

Return 

cursor  to  left-hand  edge 

cr: 

mov 

dl,  left 

/Carriage  return 

■ 

Set  cursor  to  new  position 

set  cursor: 

mov 

ah,  2 

/Set  cursor 

int 

lOh 

pop 

dx 

/Restore  registers 

pop 

cx 

pop 

bx 

pop 

ax 

iret 

Backspace  does  not  wrap  past  left  edge  of  window 

bs: 

dec 

dl 

/Back  up 

crrp 

dl, left 

/Past  left  edge? 

jb 

cr 

/Yes,  reset  cursor 

jmp 

set_cursor 

/No,  leave  it  alone 

interrupt 

endp 

greeting 

db 

13,10 

db 

218,30  dup  (196), 191,13, 10 

db 

179,'  The  Graphic  Software  Company  ',179,13,10 

db 

179,  '  BIOS  Window  Extension 

VI 

1  ',179,13,10 

db 

192,30  dup  (196), 217, 13, 10, '$' 

error_msg 

db 

13, 10, ' Invalid  window  coordinates ', 13, 10, '$' 

comment 

\ 

The  install  procedure  is  invoked  through  the  DOS  entry  point 

when  the  program  is  first  run.  It  installs  the  new  interrupt 

and  prints  a  message  on  the  console. 

When  done,  it  returns  to 

DOS  and  allows  the  space  it  occupies 

itself  to  be  reclaimed. 

The  program  first  tests  whether  the  BIOS  extensions  are  already 

installed.  If  they  are  not,  this  can 

be 

detected  by  the  fact 

that  a 

call  to  an  illegal  function  will 

return  without  altering 

any  registers. 

assume 

ds: code 

install 

proc 

near 

mov 

ah,  17 

/Read  coordinates 

int 

lOh 

inc 

cl 

/Alter  their  value 
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Entry 

ah  =  16  (function  code) 

cx  =  upper  left  corner 

dx  -  lower  right  corner 

Exit: 

al  -  fail  flag  (see  above) 

All  registers  preserved  except  ax. 

set  window: 

push 

bx 

;Save  registers 

push 

cx 

push 

dx 

mov 

al,  1 

anp 

ch,dh 

; Check  coordinates 

Ja 

exit 

anp 

cl,dl 

ja 

exit 

mov 

upper  left,cx 

/Update  coordinates 

mov 

lower  right, dx 

mov 

ah,  18 

/Read  blank  attribute 

int 

lOh 

mov 

ax, 600h 

/Blank  entire  window 

int 

lOh 

mov 

ah, 15 

/Read  current  page 

int 

lOh 

mov 

dx,  cx 

/Home  cursor 

mov 

ah,  2 

int 

lOh 

mov 

al,  0 

exit: 

pop 

dx 

/Restore  registers 

pop 

cx 

pop 

bx 

iret 

corrment 

\ 

Get  window  coordinates. 

This 

function  call  returns  the  coordinates  of  the  upper  left 

and  lower  right  corners  of  the  current  display  window. 

Entry 

:  ah  -  17  (function  code) 

Exit: 

cx  -  upper  left  corner 

dx  «  lower  right  corner 

All  registers  preserved  except  cx 

and  dx. 

get  window: 

mov 

cx, upper  left 

/Read  coordinates 

mov 

dx, lower  right 

iret 

comment 

\ 

Get  blanking  attribute. 

This 

function  call  returns  the  attribute  of  the  character 

at  the  current  cursor  position,  if  in  alpha  mode,  or  the 

background  color  (0)  if  in  graphics  mode.  The  resulting 

attribute  is  meant  to  be  used  when  scrolling  the  screen. 

Entry 

ah  =  18  (function  code) 

Exit: 

bh  -  blanking  attribute 

All  registers  preserved  except  bx 

get  blanking: 

push 

ax 

/Save  registers 

mov 

ah, 15 

/Read  current  page 

int 

lOh 

xor 

ah,  ah 

/Background  color 

anp 

al,  3 

/Check  for  alpha  modes 

jbe 

alpha 

anp 

al ,  6 

/Check  for  graphics 

jbe 

graphics 

alpha: 

mov 

ah,  8 

/Read  attribute 

int 

lOh 

graphics: 

mov 

bh,  ah 

/Return  attribute 

pop 

ax 

iret 

comment 

\ 

Write 

TTY. 

This  function  call  replaces  the  old  call  of  the  same  name. 

It  performs  the  same  functions  but 

allows  the  current  window 

to  be 

user  defined  instead  of  the 

whole  screen. 

Entry 

ah  =  14  (function  code) 

al  =  character  to  write 

bh  *  page  number  to  write 

on 

bl  =  foreground  color  (in 

graphics  modes) 

All  registers  preserved. 

write  tty: 

anp 

al,  7 

/Let  BIOS  ring  the  bell 

je 

bios 

Dr.  Dobb's  Journal,  May  1986 

366 


104 


mov 

al,  cl 

int 

lOh 

;Read  them  again 

CTip 

al,  cl 

;Test  for  difference 

pushf 

jne 

installed 

Install 

BIOS  extensions 

mov 

dx, offset  greeting 

; Report  installation 

mov 

ah,  9 

int 

21h 

mov 

ax, 3510h 

;Read  old  interrupt 

int 

21h 

mov 

word  ptr  old  int,bx 

;Save  old  interrupt 

mov 

word  ptr  old  int+2,es 

mov 

dx, offset  interrupt 

; Install  new  interrupt 

mov 

ax, 2510h 

int 

21h 

• 

BIOS  extensions  are  installed  now 

installed: 

push 

cs 

; Point  to  comnand  tail 

pop 

es 

mov 

dl,81h 

mov 

cx, 7fh 

/Read  coordinates 

mov 

al,  '  (' 

repne 

scasb 

/Find  first  pair 

call 

num  pair 

push 

dx 

repne 

scasb 

/Find  second  pair 

call 

num_pair 

pop 

cx 

mov 

ah,  16 

/Set  coordinates 

int 

lOh 

or 

al,  al 

/Test  legality 

jz 

legal 

: 

Window 

coordinates  are  illegal 

mov 

dx, offset  error  msg 

/Print  error  message 

mov 

ah,  9 

int 

21h 

; 

Terminate  program  in  appropriate  manner 

legal: 

popf 

/Check  residency 

jne 

resident 

mov 

dx, offset  greeting 

/Make  resident 

int— 

27h 

resident : 

int 

20h 

/Already  resident 

num_pair 

proc 

near 

push 

bx 

call 

number 

/Read  first  number 

mov 

bh,  dl 

call 

number 

/Read  second  number 

mov 

dh,  bh 

pop 

bx 

ret 

/Row/Col  pair  in  dx 

num_pair 

endp 

number 

proc 

near 

push 

ax 

push 

bx 

mov 

al,  '  ' 

/Skip  leading  blanks 

repe 

scasb 

dec 

di 

mov 

bl,  10 

/Decimal  multiplier 

xor 

ax,  ax 

xor 

dx,  dx 

digit: 

xchg 

ax,  dx 

/Multiply  by  10 

mul 

bl 

add 

ax,  dx 

/Add  new  digit 

xchg 

ax,  dx 

mov 

al,es:  [di] 

/Read  next  character 

inc 

di 

sub 

al, 'O' 

/Normalize  it 

cmp 

al, '9' 

/Check  for  digits 

jbe 

digit 

pop 

bx 

pop 

ax 

ret 

/Number  in  dx 

number 

endp 

install 

endp 

code 

ends 

end 

DOS_entry 

/Must  be  far  label 

End  Listing 
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MS  DOS  Reference  Books 

Ithough  books  on  8086/88  as¬ 
sembly-language  programming 
abound,  books  on  programming  in 
the  MS  DOS  environment  have  been 
nearly  nonexistent.  Several  new 
books  on  this  subject  have  appeared 
recently  however,  and  I  would  like 
to  mention  a  few  I  have  looked  at: 

Simrin,  Steven.  MS-DOS  Bible.  India¬ 
napolis:  Howard  W.  Sams  &  Co.,  1985. 
385  pages  with  index. 

I  would  characterize  this  as  an  in¬ 
troductory  systems  guide  to  MS  DOS. 
Exposition  of  the  MS  DOS  hierarchical 
file  structure,  I/O  redirection  and 
pipes,  installation  of  a  fixed  disk, 
batch  files,  the  MS  DOS  intrinsic  and 
extrinsic  commands,  and  use  of  ED- 
LIN,  LINK,  and  DEBUG  comprise  the 
majority  of  the  book.  Two  brief 
chapters  discuss  disk  formats,  direc¬ 
tories,  the  file  allocation  table,  and 
device  drivers;  the  actual  MS  DOS 
function  calls  are  relegated  to  an  ap¬ 
pendix.  The  book  contains  virtually 
no  programming  examples. 

Jump,  Dennis  N.  Programmer's  Guide 
to  MS-DOS.  Bowie,  MD:  Brady  Com¬ 
munications  Co.,  1984.  244  pages 
with  index. 

Although  this  book  carries  a  1984 
copyright  date,  I  did  not  see  it  in  the 
bookstores  until  a  few  months  ago.  It 
is  aimed  at  beginning  assembly-lan¬ 
guage  programmers  and  discusses 
the  various  MS  DOS  function  calls  by 
category  (traditional  character  I/O 
calls,  traditional  file  management 
calls,  extended  file  management 
calls,  and  so  on).  There  is  minimal 
coverage  of  MS  DOS  loading,  struc¬ 
ture,  or  disk  control  areas.  The  expla- 


by  Ray  Duncan 

nations  of  memory  management,  the 
MS  DOS  EXEC  call,  and  installable  de¬ 
vice  drivers  are  reasonable  though 
incomplete.  The  last  30  or  so  pages  of 


the  book  are  devoted  to  IBM  PC-spe¬ 
cific  topics,  mainly  the  ROM  BIOS 
driver  calls.  Programming  examples 
are  chiefly  in  the  form  of  assembly- 
language  functions  to  be  called  from 
Pascal,  except  for  an  example  char¬ 
acter  device  driver.  This  book,  to¬ 
gether  with  the  MS-DOS  Bible  by  Sim¬ 
rin  would  be  a  good  starting  point  for 
beginning  MS  DOS  assembly-language 
programmers  as  the  two  books  have 
little  overlap  in  content. 

King,  Richard  A.  The  MS-DOS  Hand¬ 
book.  Berkeley  CA:  Sybex  Computer 
Books,  1985.  319  pages  with  index. 

This  book  is  written  for  beginning 
assembly-language  programmers;  it 
covers  most  of  the  same  material  as 
the  previous  two  books  combined  ex¬ 
cept  that  disk  structures  and  control 
areas  are  discussed  in  a  rather  gener¬ 
al  way  and  device  drivers  are  barely 
mentioned.  It  contains  few  program¬ 
ming  examples.  My  biggest  com¬ 
plaint  about  this  book  is  that  material 
applicable  to  generic  MS  DOS  systems 
and  material  pertinent  only  to  IBM 
PCs  is  jumbled  together  with  very  lit¬ 
tle  distinction. 

Norton,  Peter.  The  Peter  Norton  Pro¬ 
grammer's  Guide  to  the  IBM  PC.  Belle¬ 
vue,  WA:  Microsoft  Press,  1985.  426 
pages  with  index. 

As  you  would  expect,  this  book  is 
heavily  slanted  toward  the  IBM  PC 
family  with  extensive  discussion  of 
the  IBM  video  adapter,  keyboard, 
sound  generation,  and  ROM  BIOS.  It 
may  best  be  viewed  as  a  well-orga¬ 
nized,  highly  readable  replacement 
for  both  the  IBM  PC  DOS  Technical  Ref¬ 
erence  and  the  IBM  PC  Hardware  Refer¬ 


ence  manuals.  It's  directed  at  program¬ 
mers  of  intermediate  experience. 

Information  on  the  generic  MS  DOS 
services  occupies  less  than  a  quarter 
of  Norton's  book  but  is  still  relatively 
thorough;  additional  quick-refer¬ 
ence  tables  are  well  laid  out.  The 
book  has  clear  explanations  of  the  MS 
DOS  disk  structure  and  control  areas, 
file  control  blocks,  and  program  seg¬ 
ment  prefixes.  The  section  on  the 
EXEC  function  is  inadequate  to  make 
it  work  (unless  the  reader  already 
knows  how)  because  the  special  use 
of  the  modify  memory  block  func¬ 
tion  4ah  with  register  ES  pointing  to 
the  calling  program’s  PSP  is  not  de¬ 
tailed;  also,  the  author's  comment  on 
registers  destroyed  by  EXEC  and  the 
method  of  saving  and  restoring  the 
SS  and  SP  registers  are  not  correct. 
Coverage  of  device  drivers  is  limited 
to  some  discussion  and  (deserved) 
criticism  of  ANSI.SYS;  there  is  no  mate¬ 
rial  on  the  structure  or  programming 
of  device  drivers.  Assembly-language 
examples  are  sparse  and  simplistic 
and  are  nearly  all  from  the  point  of 
view  of  Pascal  or  C  subroutines. 

Lafore,  Robert.  Assembly  Language 
Primer  for  the  IBM  PC  and  XT.  New 
York:  New  American  Library  1984. 
501  pages  with  index. 

Like  the  Norton  book,  this  book  is 
strongly  biased  toward  the  IBM  PC 
hardware  and  ROM  BIOS  software, 
but  about  a  quarter  of  it  is  devoted  to 
discussion  of  general  MS  DOS  topics. 
The  layout  of  DOS  and  the  structure 
of  executable  program  files  are  dis¬ 
cussed  briefly.  File  I/O  is  well  cov¬ 
ered,  but  advanced  subjects  such  as 
device  drivers,  memory  allocation, 
and  the  EXEC  call  are  completely  ab¬ 
sent.  This  book  makes  extensive  use 
of  hex  memory  dumps  and  assem¬ 
bly-language  examples,  including 
complete  working  programs — a 
style  that  should  be  commended. 

MS-DOS  Programmer's  Reference. 
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Bellevue,  WA:  Microsoft  Press,  1984. 

This  book  is  rarely  seen  in  its  origi¬ 
nal  Microsoft  form.  It  is,  however, 
commonly  available  in  various  MS 
DOS  OEM  editions,  the  most  prevalent 
(of  course)  being  the  IBM  PC  DOS  Tech¬ 
nical  Reference.  Versions  are  also  ex¬ 
tant  from  Hewlett-Packard,  Zenith, 
and  Intel,  among  others.  The  Intel 
book  is  the  best  of  the  bunch;  it  has 
been  extended  with  assembly-lan¬ 
guage  examples  for  each  MS  DOS  sys¬ 
tem  function,  source  code  for  simple 
block  and  character  device  drivers, 
and  a  lengthy  appendix  describing 
the  Intel  relocatable  object  record 
format.  It  can  be  ordered  from  the 
Literature  Department,  Intel  Corp., 
3065  Bowers  Ave.,  Santa  Clara,  CA 
95051  (part  number  135555-001). 

DDJ  readers  are  invited  to  send  fur¬ 
ther  comments  on  the  above  books  to 
this  column  and  to  provide  informa¬ 
tion  on  other  books  they  have  found 
useful.  Two  additional  books  on  MS 
DOS  programming,  aimed  at  interme¬ 
diate  to  advanced  assembly-language 
programmers,  are  due  from  Micro¬ 
soft  Press  about  the  time  this  column 
will  appear  in  print.  The  first  is  my 
own  book  Advanced  MS-DOS.  The 
other  is  the  MS-DOS  Technical  Refer¬ 
ence  Encyclopedia,  Volume  I  (collabo¬ 
ration  of  several  authors,  preface  by 
Bill  Gates,  about  1200  pages,  $134.95, 
June  publication  date  expected). 

The  EXEC  Function  and 
FORTRAX 

Chris  Dunford,  author  of  the  popular 
CED  command  line  editor,  sent  a  com¬ 
ment  on  the  interface  between  FOR¬ 
TRAN  and  the  EXEC  call  that  was 
printed  in  the  January  1986  16-Bit 
Toolbox:  "I  wonder  if  you're  aware 
that  there  is  an  easier  way  to  find  the 
PSP  of  a  program:  DOS  function  62h  re¬ 
turns  (in  register  by)  the  PSP  address 
of  the  currently  executing  process. 
Function  62h  is  not  available  under 
DOS  2.x,  but  undocumented  function 
51h  performs  the  same  service.  You 
want  to  avoid  using  undocumented 
features,  of  course,  but  I  don’t  fore¬ 
see  new  releases  of  DOS  2.X  in  the 
near  future! 

“It  seems  to  me  quite  safe  to  check 
the  DOS  version  under  which  your 
program  is  running,  then  use  func¬ 
tion  51h  or  62h  as  appropriate.  Of 
course,  another  advantage  of  this 


method  over  Sybek’s  is  that  it’s  com¬ 
piler  independent." 

The  SO  Files  Problem 

Dan  Daetwyler’s  description  of  his 
problem  with  DOS’  limit  of  20  open 
files  per  process,  which  appeared  in 
the  December  1985  16-Bit  Toolbox 
column,  provoked  several  helpful  re¬ 
sponses  from  DDJ  readers. 

Sean  McDowell  of  Marietta,  Geor¬ 
gia,  said:  “I  am  writing  in  response  to 
Mr.  Daetwyler’s  letter  about  DOS  3.0 
and  the  20  file  handle  limit.  We  have 
had  this  problem  since  handles  were 
first  introduced.  I  am  very  curious 
about  why  Mr.  Daetwyler  didn’t  run 
into  this  problem  sooner.  The  prob¬ 
lem  seems  to  stem  from  the  amount 
of  room  available  in  the  program  seg¬ 
ment  prefix  (PSP).  If  you  look  at  the 
memory  map  of  the  PSP  in  the  IBM 
Technical  Reference,  there  is  an  area 
from  offset  18h  to  2bh  marked  as  re¬ 
served.  This  appears  to  be  where  DOS 
stores  the  allocated  file  handle  num¬ 
bers.  Because  there  are  20  bytes, 
there  are  20  file  handles  for  the  cur¬ 
rent  process.  DOS  seems  to  use  the 
segment  address  of  the  current  PSP 
(see  DOS  3.0  function  62h )  as  the  pro¬ 
cess  ID.  Because  an  interrupt  to  a  resi¬ 
dent  database-handling  module 
would  not  change  this  value,  that 
would  explain  why  splitting  the  da¬ 
tabase  and  allowing  the  resident  task 
to  own  part  would  not  correct  the 
problem.  .  .  .  Currently  we  are  open¬ 
ing  and  closing  handles  with  a  least- 
recently-used  algorithm  within  our 
file  access  routines,  even  though  that 
can  be  painfully  slow  at  times.” 

Inspecting  the  PSPs  of  some  of  my 
own  programs,  it  does  seem  evident 
that  the  PSP  handle  table  positions 
correspond  to  handle  numbers.  The 
byte  at  a  given  table  position  contains 
0FFH  if  the  handle  is  not  in  use  for 
the  process.  If  the  handle  is  opened 
to  a  file  or  device,  the  byte  contains  a 
small  integer  number  that  is  proba¬ 
bly  an  index  to  DOS’  internal  table  of 
file  control  blocks  for  the  “extended” 
file  functions. 

Ross  Nelson  of  San  Jose,  California, 
took  this  a  little  further:  “The  DOS 
equivalent  of  the  process  ID  is  the  PSP 
paragraph  number.  This  is  how  DOS 
keeps  track  of  who  owns  memory 
blocks,  and  I  suspect  it  manages  open 
files  in  this  way  as  well.  It  keeps  an 
internal  variable  to  track  the  'cur- 
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rently  active  PSP,'  and  there  are  two 
(undocumented  naturally)  calls  to 
get/set  this  variable. 

"Executing  an  interrupt  21h  with 
ah=51h  will  return  the  currently  ac¬ 
tive  PSP  in  the  by  register.  Loading  by 
with  a  PSP  and  executing  an  interrupt 
21h  with  ah=50h  will  set  a  new  ac¬ 
tive  PSP.  The  pseudotasking  solution 
to  the  file  problem  is  then  handled  in 
this  way: 

Task  A:  open  initial  files,  do  process¬ 
ing,  EXEC  Task  B 

Task  B:  open  new  files,  call  (via  soft¬ 
ware  interrupt?)  to  Task  A 
Task  A:  save  active  PSP,  set  active  to 
Task  A’s  PSP,  do  processing,  re¬ 
store  previous  PSP,  return 
Task  B:  continue  processing.  . 

An  unsigned  note  from  another 
reader,  along  with  a  labeled  hexa¬ 
decimal  dump  of  a  program  segment 
prefix,  also  took  Mr.  McDowell’s  ob¬ 
servation  on  the  PSP  a  little  further. 
The  anonymous  reader  pointed  out 
that  the  words  at  PSP+0032h,  0034h, 
and  0036h  contain  the  maximum 
number  of  handies  allowed  for  the 
process,  the  offset  of  the  handle  ta¬ 
ble,  and  the  segment  of  the  handle 
table,  respectively.  The  note  said: 
"To  open  more  than  20  handles,  pro¬ 
vide  an  area  in  your  program  consist¬ 
ing  of  one  byte  per  handle.  Move  the 
first  five  handles  from  the  table  at 
PSP+0018h  to  the  new  handle  table. 
Then,  change  the  handle  table  point¬ 
ers  at  PSP+0034h  to  point  to  the  new 
table,  and  change  the  value  at 
PSP+0032h  to  the  number  of  entries 
in  the  new  table." 

PC/AT  Interrupts 

Brett  Salter  of  Data  Base  Decisions 
wrote:  "In  regard  to  the  AT  problem 
you  mentioned  in  your  May  1985  col¬ 
umn,  I’m  afraid  Intel's  nasty  habit  of 
referring  to  interrupt  numbers  as 
decimal  instead  of  hex  has  caused 
some  confusion.  Interrupt  13  decimal 
(not  hex)  is  the  segment  overrun  ex¬ 
ception  interrupt.  Because  this  inter¬ 
rupt  ( Odh )  was  not  previously  used,  it 
won’t  cause  anything  as  disastrous  as 
zapping  a  hard  disk. 

“IBM  has  most  of  the  new  excep¬ 
tion  interrupts  vectored  to  a  routine 
that  sets  a  flag  and  then  IRETs  back  to 
the  user’s  program.  On  return,  the 
instruction  that  caused  the  exception 


is  reexecuted,  putting  the  system  into 
an  enabled  loop.  The  oniy  way  out 
on  a  normal  PC/AT  is  to  use  Ctrl-Alt- 
Del  to  reboot. 

"If  you  have  my  Periscope  debug¬ 
ger  installed  on  an  AT,  interrupts  Odh 
(segment  overrun)  and  06h  (invalid 
opcode)  point  to  Periscope.  This 
means  that  the  instruction  sequence 
shown  in  your  column  will  put  the 
user  into  Periscope,  where  you  can 
modify  the  registers  as  needed  to  re¬ 
cover  the  system. 

"Another  new  twist  on  the  PC/ 
AT — if  your  program  uses  the  array 
BOUND  instruction,  an  exception 
causes  INT  5  to  be  performed,  print¬ 
ing  the  screen  to  a  parallel  printer. 
Then  control  returns  to  the  BOUND 
instruction  that  caused  the  interrupt, 
which  prints  the  screen  over  and 
over  until  you  reboot  the  system. 
Once  again,  Periscope  can  be  set  to 
intercept  this  interrupt,  letting  you 
regain  control  of  the  system.” 

Macro  Assembler, 

Version  4.0 

The  new  speedy  Version  4.0  of  the 
Microsoft  Macro  Assembler  also  has 
a  completely  new  bug!  It  seems  that 
the  include  function  has  been 
changed  in  such  a  way  that  it  ignores 
end-of-file  marks  ( lah )  and  uses  the 
size  of  the  file  as  recorded  in  the  disk 
directory  instead.  If  you  use  an  editor 
(such  as  WordStar  in  nondocument 
mode),  which  rounds  the  size  of  the 
file  up  to  the  next  block  boundary 
and  pads  the  last  block  out  with  EOF 
marks,  you  will  get  an  “extra  charac¬ 
ters  on  line”  error  for  the  include 
statement.  The  listing  file  cannot  be 
typed  or  printed  past  the  point  of  the 
error  because  the  macro  assembler 
copies  all  of  the  extra  EOF  marks  into 
the  listing  file!  A  work-around  sug¬ 
gested  by  Microsoft  is  to  invoke  ED- 
LIN  with  the  name  of  the  source  file, 
then  enter  the  E  command  to  imme¬ 
diately  exit  from  the  line  editor.  ED- 
LIN  will  scan  for  the  first  EOF  mark 
and  create  a  new  file  with  the  cor¬ 
rect  size,  renaming  the  original  file 
with  a  BAK  extension. 

IBM  PC  Window  Control 

John  J.  Seal,  of  the  Graphics  Software 
Co.,  contributed  a  resident  window 
manager  for  the  IBM  PC  to  this 
month’s  16-Bit  column  (see  Listing 
One,  page  102).  The  program  is  in¬ 


voked  with  a  command  in  the  form:  | 

C>  WINDOW  (R,C)  TO  (R,C) 

which  specifies  a  window  on  the 
screen  in  which  all  subsequent  activ-  | 
ity  will  take  place.  The  window  coor¬ 
dinates  are  given  as  the  upper-left 
and  lower-right  row  and  column.  Co¬ 
ordinate  (0,0)  is  the  upper-left  corner 
of  the  screen. 

WINDOW  makes  itself  resident  and 
captures  the  IBM  BIOS  video  driver  in¬ 
terrupt,  filtering  out  some  calls  and 
passing  the  others  on  to  the  ROM 
driver.  The  areas  outside  the  current 
window  may  be  written  to  directly 
by  any  of  the  usual  commands  (in 
your  favorite  language)  that  allow  di-  \ 

'■  rect  coordinate  specification;  the  , 
WINDOW  program  affects  only  char-  J 
acters  that  are  displayed  with  the  j 
“TTY  Output”  ROM  BIOS  call  (function  J 
Oeh).  The  WINDOW  program  illus-  j 
trates  several  useful  PC  DOS  program- 
ming  techniques: 

•  installation  of  a  new  resident  pro¬ 
cess  with  the  terminate  and  stay  resi-  ' 

|  dent  function 

•  chaining  on  to  an  existing  interrupt 
handler 

•  using  the  MS  DOS  get  interrupt  and 
set  interrupt  functions  to  inspect  and 
modify  the  hardware  interrupt  table 

Although  I  have  not  changed  Mr. 
Seal’s  code,  it  should  be  noted  that 
the  preferred  method  to  terminate 
and  stay  resident  for  DOS,  Version  2 
and  later,  is  use  of  interrupt  21h  func¬ 
tion  31h,  rather  than  interrupt  27h.  Si¬ 
milarly,  the  preferred  method  of  fi¬ 
nal  exit  is  now  interrupt  21h  function 
4ch,  rather  than  interrupt  20h. 


DDJ 


(Listing  begins  on  page  102.) 
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THE  RIGHT  TO  ASSEMBLE 

Code  Compression  with  Mini-Interpreters 


Code  crunching  is  an  arcane  art, 
something  like  squeezing  ele¬ 
phants  into  phone  booths.  When  I 
was  a  game  designer  at  Atari,  I  con¬ 
stantly  had  to  squeeze  my  6502  code 
down  further  and  further  to  fit  into  a 
pitifully  small  4K  ROM  space.  Even  af¬ 
ter  Atari  invented  a  bank-switching 
ROM  cartridge,  we  still  came  up 
against  the  memory  limit  very  quick¬ 
ly.  One  of  our  sayings  was  that  it's 
always  possible  to  squeeze  another 
byte  out  of  an  assembly-language 
program.  Some  of  the  feats  we  ac¬ 
complished  were  truly  remark¬ 
able — the  world’s  smallest  chess  pro¬ 
gram  (as  far  as  I  know)  runs  on  the 
2600  VCS  game  machine  with  only  4K 
of  ROM  and  128  bytes  of  RAM!  When  I 
left  Atari,  I  thought  I  would  never 
have  to  worry  about  crunching  my 
code  again.  I  was  entering  the  world 
of  "big”  machines,  with  huge  64K 
RAM  spaces!  That  was  at  best  a  very 
temporary  release,  though.  Soon  I 
was  dealing  with  truly  "enormous" 
programs  (operating  systems),  and 
once  again  I  had  to  start  crunching 
my  code. 

Some  of  the  techniques  for  effec¬ 
tive  code  crunching  are  actually 
quite  simple — for  example,  variables 
can  frequently  be  moved  into  low 
memory,  where  most  processors  can 
access  them  with  fewer  bytes  of  ad¬ 
dress  information.  On  the  6502  this  is 
a  particularly  large  saving — an  in¬ 
struction  that  loads  a  byte  from 
memory  location  $1000  requires  3 
bytes,  but  if  you  load  the  information 
from  $10  you  use  up  only  2.  Another 


by  Nick  Turner 


trick  is  to  use  register  variables  wher¬ 
ever  possible  because  register  in¬ 
structions  are  usually  shorter.  On  the 
first  crunching  pass,  though,  all  these 
simple  tricks  are  usually  used  up.  At 
Atari,  this  first  pass  usually  reduced 


the  size  of  the  game  program  by  no 
more  than  15  percent.  Because  the 
"raw”  programs  were  about  twice  as 
large  as  the  space  into  which  they 
had  to  be  shoehorned,  there  was  still 
a  lot  of  crunching  to  be  done. 

Using  a  Mini-Interpreter 

The  technique  I'll  talk  about  here 
was  used  with  some  success  in  many 
of  my  operating  system  designs.  It's 
best  applied  when  you  have  a  lot  of 
code  that  contains  repetitive  calls  to 
several  different  subroutines.  In  one 
particular  case,  I  was  writing  a  sys¬ 
tem  that  would  be  accessed  over  the 
phone  by  users  with  serial  terminals. 
It  was  important  to  be  able  to  trans¬ 
mit  various  sequences  of  control 
characters  and  also  to  be  able  to  re¬ 
ceive  and  interpret  similar  se¬ 
quences,  setting  and  clearing  various 
flags  and  changing  the  modes  of  in¬ 
put  and  output.  To  do  this  with  tradi¬ 
tional  code  would  have  worked,  but  I 
managed  to  chop  the  size  of  the  re¬ 
quired  code  by  more  than  half  using 
what  I  call  a  mini-interpreter. 

A  mini-interpreter  is  a  subroutine 
that  pops  the  stack  to  find  out  where 
it  was  called  from,  then  reads  the 
bytes  immediately  following  the  call¬ 
ing  instruction  and  performs  various 
tasks  based  on  what  is  sees  there.  At 
some  point  it  will  see  a  return  token 
and  will  perform  a  jump  to  the  next 
valid  instruction  following.  In  the 
case  of  a  machine  in  which  the  in¬ 
structions  must  be  word-aligned, 
such  as  the  68000,  it  would  return  to 
the  next  even-addressed  byte. 

The  mini-interpreter  I  wrote  for 
my  dial-up  system  was  originally 
created  as  a  print  routine  that  would 
read  an  ASCII  string  immediately  af¬ 


ter  the  invoked  instruction,  then 
print  it  out.  A  null  ($00)  was  used  to 
terminate  the  string.  (A  6502  routine 
by  Chris  Espinoza  that  does  just  this 
was  published  in  the  September  1976 
issue  of  DDJ.)  Here's  a  typical  calling 
sequence  for  the  routine  as  described 
so  far: 


;code  preceding  the 
call 


JSR 

PRINT  ;call  the  print 

routine 

ASC 

"This  text  would  be  printed 

out.” 

HEX 

00 

;code  following  the 

call 

Note  that  the  calling  sequence  re¬ 
quires  4  bytes;  3  for  the  JSR  instruc¬ 
tion  and  1  for  the  null-token  termina¬ 
tor.  I  felt  that  this  4-byte  overhead 
was  excessive.  How  could  l  shave  it 
down? 

The  answer  occurred  to  me  one 
day  while  I  was  setting  a  breakpoint 
to  debug  a  program:  The  BRK  instruc¬ 
tion,  which  is  used  by  debuggers  to 
wrest  control  from  the  executing 
program  when  it  reaches  a  $00  in  the 
program,  occupies  only  1  byte  and 
can  cause  execution  to  vector  to  any 
point  in  memory.  The  only  problem 
was  that  the  BRK  instruction  was 
used  extensively  during  debugging. 
So,  I  created  a  conditional  macro  that 
would  assemble  the  PRINT  call  as  a 
JSR  or  a  BRK,  depending  on  whether  I 
was  debugging  or  not.  Then  I  added  a 
small  routine  in  the  initialization  that 
placed  the  address  of  my  print  rou¬ 
tine  into  the  BRK  vector.  Of  course, 
the  PRINT  routine  itself  also  had  to 
have  some  conditionally  assembled 
code  because  the  BRK  instruction 
puts  some  status  information  on  the 
stack  that  I  needed  to  pop  and  ignore. 
Only  a  few  extra  instructions  were 
needed,  however.  The  new  method 
worked  beautifully.  Now  I  could 
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print  any  text  I  wanted  with  only  a  2- 
byte  overhead.  Of  course,  the  routine 
that  handled  the  PRINT  calls  took  up 
some  space  of  its  own,  but  with  doz¬ 
ens  of  calls  in  my  code,  the  extra 
overhead  was  more  than  compensat¬ 
ed  for  by  the  code  savings  in  my 
PRINT  calls. 

Further  Refinements 

I  was  quite  pleased  with  the  results, 
but  I  still  needed  to  shave  the  pro¬ 
gram  down  further.  I  discovered  that 
there  were  about  a  dozen  macro  ex¬ 
pansions  that  frequently  occurred 
adjacent  to  the  PRINT  calls.  Many  of 
them  were  used  to  set,  test,  or  clear 
various  print  format  flags — for  ex¬ 
ample,  there  was  a  protocol  with 
which  the  user  could  send  a  Control- 
C  to  inhibit  furthur  output  until  the 
beginning  of  the  next  logical  block  of 
text.  To  implement  this  protocol,  I 
created  an  output-inhibit  flag  and 
tested  the  status  of  the  flag  before 
sending  each  character.  The  flag  was 
reset  at  the  beginning  of  each  block 
of  text  and  set  whenever  a  Control-C 
was  detected  from  the  user.  The 
problem  was  that  the  flag  reset  often 
occurred  in  the  middle  of  a  stream  of 
text,  requiring  a  code  sequence 
something  like  this: 


;text  being  output 

ASC 

"The  last  text  in  the  first 

HEX 

block.” 

00  ;marks  end  of  text 

LDA 

TXTFLAG  ;clear  output  sup- 

AND 

TXTFLAG  press  flag 

#255-OUTSUP 

STA 

TXTFLAG 

PRINT 

;macro  that  in 

BRK 

ASC 

vokes  print  inter¬ 
preter  (JSR  or  BRK) 

"First  text  in  the  next  block.” 

;more  text 

Look  at  all  those  bytes!  Including  the 
end  token  of  the  previous  block,  the 
code  to  clear  the  flag,  and  the  BRK  to 
call  the  interpreter  again,  I  used  up  8 
bytes!  How  could  I  cut  that  down? 

The  answer  became  obvious  as 
soon  as  I  realized  that  the  text-output 
interpreter  could  easily  be  increased 
in  size  without  adding  very  much  to 
the  overall  size  of  the  program.  Be¬ 
cause  there  were  quite  a  few  8-bit 
values  that  could  never  be  encoun¬ 
tered  in  the  middle  of  a  text  stream,  I 


simply  appropriated  one,  equated  it 
to  CLCTLC  (CLear  ConTroL  C),  and 
stuck  it  into  the  text  stream.  After 
adding  the  appropriate  code  to  the 
interpreter,  I  reduced  the  above 
monstrosity  to: 

;text 

ASC  "The  last  text  in  the  first 

block.” 

BYTE  CLCTLC  ;clear  output 

suppression 

ASC  "First  text  in  the  next  block." 

;more  text 

This  was  the  start  of  something  big 
(or,  rather,  something  small!).  There 
were  several  other  flags  whose  en¬ 
tire  manipulation  could  be  com¬ 
pressed  in  the  same  way.  Eventually 
I  added  a  lot  more  to  the  routine.  I 
added  escape  codes  that  would 
switch  to  a  different  interpreter  alto¬ 
gether.  I  added  a  set  of  conditional 
test  codes  that  allowed  me  to  output 
one  of  two  strings  depending  on  the 
state  of  various  flags.  I  even  added  a 
code  that  allowed  me  to  call  any  ma¬ 
chine-language  subroutine  any¬ 
where  and  then  return  to  interpret¬ 
ed  execution  upon  encountering  the 
RTS  from  the  called  routine  (an  inter¬ 
preted  JSR  instruction).  This  one  was 
particularly  useful  because  it  al¬ 
lowed  me  to  perform  special-pur¬ 
pose  routines  without  the  code  over¬ 
head  of  leaving  the  text  output 
interpreter. 

I  never  ran  into  any  difficulties 
with  this  heavily  interpreted  ap¬ 
proach,  and  I  was  able  to  reduce  the 
code  overhead  vastly  for  "stupid  lit¬ 
tle  stuff”  that  I  had  to  do  repeatedly. 
If  your  application  is  time  critical, 
you  might  not  want  to  use  a  mini-in¬ 
terpreter,  But  because  code  size  was 
far  more  important  to  me  than  the 
time  required  to  execute  the  instruc¬ 
tions,  this  approach  was  perfect  for 
my  on-line  system,  which  you  can 
dial  up  today  at  (408)  338-9511. 
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The  theme  of  this  month's 
column  is  user-interface 
design. 

The  Research  Group 

has  announced  SayWhat?!, 
a  productivity  tool  de¬ 
signed  to  shorten  the  time 
required  for  screen  design 
and  at  the  same  time  in¬ 
crease  the  impact  of  screen 
displays  for  dBASE  II  and  III, 
BASIC,  and  Turbo  Pascal 
programs.  It  is  an  unpro¬ 
tected  menuless  system 
that  allows  users  to  create 
and  edit  displays  on  the 
screen  without  writing 
any  programming  com¬ 
mands  or  modules.  The 
program  requires  an  IBM 
PC/XT/AT  or  compatible 
with  a  minimum  of  128K 
(384K  required  for  dBASE 
III),  DOS  2.0  or  later,  one 
disk  drive,  and  a  mono¬ 
chrome  or  color  monitor. 
It  retails  for  $39.95. 

Wendin  is  offering  three 
new  products:  Operating 
System  Toolbox,  PCVMS, 
and  PCUnix.  Operating  Sys¬ 
tem  Toolbox  allows  users  to 
modify  and  tailor  operating 
system  software.  Full 
source  code  is  available.  All 
enhanced  system  services, 
paged  memory  manage¬ 
ment,  concurrent  input/ 
output,  and  a  multitasking 
scheduler  can  be  used  to 
construct  powerful  person¬ 
al  operating  systems  for  the 
IBM  PC/XT/ AT.  The  price  is 
$99.  PCVMS  is  an  operating 
system  that  provides  multi¬ 
ple  processes,  networking 
software,  and  a  command 
set,  plus  a  set  of  VAX-like 
system  services.  The  price 
with  source  code  included 


is  $49.  PCUnix  features  utili¬ 
ties  such  as  at,  grep,  mail, 
nice,  and  who.  The  price  is 
$49. 

For  C 

Gimpel  Software  has  an¬ 
nounced  Amiga-Lint,  a  di¬ 
agnostic  facility  for  the  C 
programming  language 
that  runs  on  the  Commo¬ 
dore  Amiga.  Amiga-Lint 
analyzes  C  programs  and 
reports  on  bugs,  glitches, 
and  inconsistencies. 
Among  the  errors  reported 
on  by  Amiga-Lint  are  type 
inconsistencies  across 
modules,  parameter-argu¬ 
ment  mismatches,  library 
usage  irregularities,  unini¬ 
tialized  variables,  value-re¬ 
turn  inconsistencies,  vari¬ 
ables  declared  but  not 
used,  suspicious  use  of  op¬ 
erators,  and  unreachable 
code.  Amiga-Lint  runs  un¬ 
der  Amiga's  CL1  interface 
and  is  available  for  $98. 

Retrieval  Technology 
Corp.  (RTC)  has  available 
the  All-Hands-on  C  Video 
Workshop,  a  six-module, 
five-hour  workshop  de¬ 
signed  to  teach  the  full  fea¬ 
tures  of  C. 

Desktop  A. I.  has  re¬ 
leased  a  translator  that  al¬ 
lows  users  to  move  dBASE 
programs  into  C.  The  dBx 
Translator  system  includes 
a  language  translator  for 
processing  dBASE  source 
code  and  a  run-time  li¬ 
brary  toolbox  to  replace 
the  dBASE  screen  handler. 
The  system  is  designed  to 
work  with  any  C  database 
manager.  In  addition,  ap¬ 
plications  can  be  moved  to 
machines  on  which  dBASE 
is  not  available,  such  as  the 
AT&T  3B2  under  Unix,  Al¬ 
tos  under  Xenix,  and  Mac¬ 
intosh  or  Amiga  systems. 
The  package  price  ranges 
from  $350  to  $1,000,  de¬ 
pending  on  configuration. 

The  C-Board  is  a  stand¬ 


alone  C  language  develop¬ 
ment  system  from  HiTech 
Equipment  that  can  be 
used  on  a  single  STD  bus- 
compatible  board.  The  C- 
Board  requires  a  5V  0.5A 
power  source  or  unregu¬ 
lated  7— 9V  DC  using  an  op¬ 
tional  on-card  regulator. 
The  product  features  a  CPU 
with  parallel  and  serial  1/ 
O,  timer/counters  with 
PWN  output,  EPROMs  and 
EEPROMs,  a  threaded  inter¬ 
preter,  and  interactive  de¬ 
velopment.  The  OEM  ver¬ 
sion  of  the  card  without 
memory  devices  or  man¬ 
uals  costs  $199.  Volume  dis¬ 
counts  are  available. 

A  PC-  and  VAX-hosted  C 
cross-compiler  supporting 
Intel’s  8-bit  MCS-51  micro¬ 
controller  family  is  avail¬ 
able  from  Archimedes 
Software.  The  C-based  soft¬ 
ware  development  kit  im¬ 
plements  the  proposed 
ANSI  standard  for  C  compil¬ 
ers  and  also  comes  with  an 
assembler.  The  software  is 
available  for  IBM  PC/XT/ AT 
or  compatible  systems 
equipped  with  at  least 
512K  RAM  and  using  MS  DOS 
2.0  or  later.  Initially,  the 
software  is  also  available 
for  Digital  Equipment’s 
VAX/Unix  minicomputer. 
The  PC-based  version  is 
$851;  the  VAX/Unix  version 
is  $3,500.  VAX/VMS  and  Mi- 
croVAX  versions  will  also 
be  available. 

Alcyon  has  expanded  its 
optimizing  C  compiler  line 
to  include  cross-develop¬ 
ment  versions  for  the  IBM 
PC/XT/ AT.  The  C68  compil¬ 
er,  priced  at  $795,  produces 
optimized  code  for  the 
M68000/010.  The  C68/020, 
priced  at  $995,  produces 
optimized  code  for  the 
M68020/68881.  Minimum 
requirements  are  an  IBM 
PC/XT/ AT,  5-megabyte  hard 
disk,  512K,  and  PC  DOS/MS 
DOS  3.0  or  later.  In  addition 


to  the  IBM  PC,  Alcyon 's  C 
compilers  can  be  hosted  on 
systems  with  Motorola  Ver- 
saDOS,  DEC  VAX/VMX,  and 
DEC  VAX/Unix. 

The  C  Trainer  Interpret¬ 
er  from  Catalytix  provides 
users  with  an  interactive 
interpreter  for  the  full  C 
language.  The  interpreter 
enables  users  to  run  C  code 
without  compiling  it.  Fur¬ 
thermore,  the  interpreter’s 
design  permits  users  to  run 
program  fragments  with¬ 
out  requiring  that  all  func¬ 
tions  and  libraries  be  pre¬ 
sent  at  run  time.  The  book 
The  C  Trainer,  published 
by  Prentice-Hall,  accompa¬ 
nies  the  interpreter  and 
combines  a  step-by-step  tu¬ 
torial  with  a  separate  refer¬ 
ence  section  explaining 
many  aspects  of  C.  The  tu¬ 
torial’s  format  is  such  that 
readers  build  upon  existing 
programs  that  help  them 
understand  C  in  an  interac¬ 
tive  fashion.  The  C  Trainer 
Interpreter  runs  on  the  IBM 
PC  and  compatibles,  as  well 
as  the  Macintosh.  Versions 
are  also  available  for  Unix 
and  for  VAX/VMS  computer 
systems. 

CDEBUG  (Version  2)  from 
Complete  Software  is  a 
portable  C  language  debug¬ 
ger  that  shows  all  C  objects 
according  to  their  name 
and  type  and  lets  users  set 
unlimited  break  and  trace 
points  by  using  regular  ex¬ 
pressions.  Requiring  mini¬ 
mal  overhead,  the  interac¬ 
tive  program  consists  of  a 
preprocessor  to  insert  sym¬ 
bol  tables  into  source  code 
and  a  run-time  library  to 
interpret  and  integrate 
with  a  user  environment. 
CDEBUG  is  available  for  MS 
DOS,  Lattice,  Computer  In¬ 
novations,  Wizard,  VAX/ 
VMS,  Unix,  and  Xenix  oper¬ 
ating  systems  on  disk  or 
tape  media  and  will  be 
ported.  The  new  version  is 
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priced  from  $350  for  PCs 
and  $750  for  the  Unix  port¬ 
ing  service. 

Fortrix-C  from  Rapitech 
Systems  is  designed  to  rec¬ 
ognize  and  convert  most 
FORTRAN  VMS  extensions 
and  translate  a  typical 
50,000-line  program  into  C 
code  on  VMS.  All  comment 
lines  remain  in  place  so  in¬ 
ternal  documentation  is 
retained. 

For  the  IBM  PC 

Midwest  Micro-Tek  has 

released  Circuit  Design 
Mate,  a  software  product 
for  the  IBM  PC  and  compati¬ 
bles  that  includes  schemat¬ 
ic  capture,  automatic  parts 
list  generation,  TTL  compo¬ 
nent  library  and  editor, 
and  schematic  printing  on 
any  Epson-compatible  dot¬ 
matrix  printer.  The  system 
requires  an  IBM  PC/XT/AT 
or  compatible  with  256K,  a 
640  X  200  IBM-compatible 
graphics  card,  two  double¬ 
sided  disk  drives  or  one 
disk  drive  and  hard  disk, 
and  PC  DOS/MS  DOS  2.0  or 
later.  A  single  copy  with 
TTL  library  is  $295. 

Macmillan  Software 
has  unveiled  a  menu-driv¬ 
en  software  package  for 
PCs.  Called  Asystant 
Ready-to-Run  Scientific 
Software,  the  package  is  a 
high-level  programming 
language  with  acquisition, 
analysis,  and  graphics  ca¬ 
pabilities.  Asystant  runs  on 
IBM  PCs  and  compatibles, 
including  the  Hewlett- 
Packard  Vectra,  and  uses 
the  8087  coprocessor.  A 
second  version  of  the  prod¬ 
uct,  called  Asystant  +, 
adds  data  acquisition  and 
includes  built-in  interac¬ 
tive  data  manipulation, 
analysis,  and  high-resolu¬ 
tion  color  graphics.  Asys¬ 
tant  is  priced  at  $495,  and 
Asystant  +  costs  $895. 

Dasoft  Design  Systems’ 
PC2  features  an  auto-rout¬ 
er,  expandable  symbol  li¬ 
brary  enhanced  footprint 


editor  with  six  pad  shapes 
and  user-definable  pad 
layouts,  and  a  component 
"data  book”  library  of  600 
commonly  used  parts.  The 
PC2  can  be  used  on  the  IBM 
XT/AT  and  compatibles 
with  512K,  a  monochrome 
graphics  card,  hard-disk 
storage,  and  a  mouse.  The 
software  also  runs  on  the 
AT&T  6300  and  the  NEC 
9801.  It  drives  most  plotters 
including  those  from  Hew¬ 
lett-Packard,  Houston  In¬ 
struments,  Western 
Graphtek,  Ioline,  and  com¬ 
patibles.  The  software  is 
available  for  $3,495. 

The  PC-NTDS  Adapter 
Card,  a  full  32-bit  parallel 
NTDS  (MIL-STD  1397)  inter¬ 
face  board,  is  available 
from  Sabtech  Industries. 
The  adapter  installed  in  an 
IBM  PC/AT  utilizes  the  full 
16-bit  data  path  of  the  AT 
and  can  output  data  at 
speeds  of  up  to  one  32-bit 
word  every  1.2  microsec¬ 
onds.  This  represents  a 
transfer  rate  of  up  to  834K 
32-bit  words  per  second. 
Software  included  with 
the  NTDS  Adapter  Card  has 
its  own  interface  control 
language,  including  high- 
level  commands  such  as 
loop,  repeat,  and  compare. 

Utilities 

Sophco  has  released  Sybil, 
a  collection  of  utilities  that 
can  unerase  files,  edit  sec¬ 
tors,  modify  file  and  direc¬ 
tory  attributes,  and  find 
files.  Sybil  comes  with  a 
print  spooler,  a  RAMdisk,  a 
general-regulation  expres¬ 
sion  parser,  and  a  graphics 
editor  called  ASCIIGEN  (for 
RGB  and  IBM  mono¬ 
chrome).  It  runs  on  the  IBM 
PC/XT/ AT  and  compatibles 
and  on  both  8088  and  80286 
computers.  Sybil  is  priced 
at  $49.95. 

Avocet  Systems  has  re¬ 
leased  AVSIM09,  a  software 
simulator/debugger  for 
the  6809  microprocessor. 
Running  on  any  IBM  PC 
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look-alike,  AVSIM09  inter- 
pretively  executes  6809  ob¬ 
ject  code  under  control  of  a 
full-screen  symbolic  de¬ 
bugger.  Devices  supported 
include  the  6821  PIA  (Paral¬ 
lel  Interface  Adaptor),  6840 
PTM  (Programmable  Timer 
Module),  and  6850  ACIA 
(Asynchronous  Communi¬ 
cations  Interface  Adapter). 
AVSIM09  is  priced  at  $299. 

Modula-2  has  been  added 
to  the  list  of  languages  rec¬ 
ognized  by  Source  Print, 
Aldebaran  Laboratories’ 
multifunction,  source-code 
formatting  utility.  For  Mo¬ 
dula-2,  Source  Print  can 
draw  lines  to  indicate  mod¬ 
ule  and  procedure  nestings 
as  well  as  nestings  of  if, 
while,  for,  case,  loop,  and 
repeat  structures.  Automat¬ 
ic  indentation  can  also  be 
performed.  Additional  fea¬ 
tures  include  facilities  for 
indexes,  tables  of  contents, 
pagination,  line  number¬ 
ing,  keyword  emphasis,  ex¬ 
traction  of  routines,  and  ex¬ 
tensive  printer  control. 
Source  Print  is  for  IBM  PC/ 
XT/ AT  and  compatibles. 
The  source  formatting  utili¬ 
ty  with  88-page  manual  is 
$97. 

Written  in  RM  COBOL, 
Myte  Myke  Software  from 
M  &  D  Systems  supports 
both  single-user  and  mul¬ 
tiuser  microcomputers  as 
well  as  the  more  advanced 
local-area  networks  in¬ 
cluding  Novell  and  is  de¬ 
signed  to  take  advantage  of 
the  expanding  computing 
power  of  various  micro¬ 
computing  systems.  The 
software  can  be  used  with 
Unix  Version  V  on  Sperry 
5000,  AT&T  3B  Series,  and 
NCR  Tower  Installations. 

ZLKO  from  Elliam  Asso¬ 
ciates  is  used  to  link  relo¬ 
catable  object  files  created 
by  ZMAC  or  other  assem¬ 
blers  that  use  the  Microsoft 
REL  format.  ZLKO  can  be 


used  with  compilers  for 
FORTRAN,  BASIC,  COBOL,  or 
C.  ZLKO  links  the  program 
on  disk  rather  than  in 
memory  and  thus  links  a 
program  that  will  fill  the 
entire  available  memory 
space.  It  produces  a  sym¬ 
bol  table  for  debugging 
and  can  be  used  to  segment 
a  program  that  will  not  fit 
into  memory  into  a  tree 
structure  of  overlays.  The 
price  for  the  disk  and  in¬ 
struction  manual  is  $49.95. 

CompuMagic  has  re¬ 
leased  a  package  of  20  su¬ 
perutility  programs  for 
anyone  using  CP/M  2.2. 
There  are  three  sets  of  pro¬ 
grams.  The  File  Manage¬ 
ment  programs  CMCopy, 
Erase,  Rename,  Compare, 
Sort,  DoubleSpace,  and 
WordCount  allow  wild¬ 
cards,  multiple  commands 
on  a  line,  and  ask-me  and 
test  options,  in  addition  to 
user-area  switching.  The 
Director  programs  MDIR 
and  MDIRS  take  multiple 
file  specifications.  DIRBAK 
provides  a  list  of  all  backup 
files,  and  DIRSPACE  reveals 
how  many  directory  en¬ 
tries  are  left.  UDIR  lists  all 
the  files  in  user  areas,  and 
DiskDlF  tells  what  files  are 
on  one  disk  but  not 
another. 

In  the  Special  Utilites 
programs,  CMAuto  allows 
the  creation  of  programs  to 
run  other  programs;  TYPIT 
turns  a  computer  into  an 
electronic  typewriter;  and 
A. COM  corrects  the  com¬ 
mon  A;program  typo  and 
turns  it  into  A:program. 
Screen  puts  everything  on 
the  screen  into  a  file,  and 
R/O  and  R/W  are  replace¬ 
ments  for  STAT's  command 
to  convert  files  to  read/ 
only  or  read/ write.  Min- 
iera  is  a  IK  program  that 
allows  erasing.  The  com¬ 
plete  package  is  $45. 

Computer-Guru  has  in¬ 
troduced  Salt  &  Pepper,  a 
software  program  that  con¬ 
tains  29  subroutine  mod¬ 


ules  in  MS  DOS-compatible 
BASIC.  The  modules  are 
saved  in  ASCII  format  and 
can  be  lifted  from  disk  and 
merged  into  a  user's  pro¬ 
gram.  The  programmer 
can  then  use  single-line 
commands  to  accomplish 
tasks  such  as  creating  pro¬ 
fessional  menus  and  input 
screens,  processing  dates, 
changing  strings  to  upper¬ 
case  or  lowercase,  creating 
''walking”  strings,  trapping 
errors,  and  issuing  Caps- 
Lock  on/off.  The  package  is 
available  for  $59.95. 

UX  Software  has  an¬ 
nounced  the  UX-BASIC  Na¬ 
tive  Code  Compiler  to  com¬ 
plement  the  UX-BASIC 
Interpreter  (Version  2.1). 
UX-BASIC  features  struc¬ 
tured  code;  modular  pro¬ 
gramming;  sequential,  di¬ 
rect,  and  ISAM  files;  and 
editing  and  debugging 
tools.  It  is  functionally  com¬ 
patible  with  IBM’s  IX  BASIC. 
Prices  vary  according  to  the 
class  of  target  computer. 

Software  Products  & 
Services  (SPS)  has  expand¬ 
ed  its  EPOS  engineering  and 
software  development  en¬ 
vironment  to  include  tools 
for  the  automatic  genera¬ 
tion  of  Pascal  code.  The 
EPOS  software  system  sup¬ 
ports  project  design  and 
development  from  the  for¬ 
mulation  of  requirements 
to  a  complete  design  and 
system  maintenance 
throughout  the  entire  life 
cycle  of  a  project.  It  also 
contains  integrated  man¬ 
agement  tools  for  project 
control.  The  system  is  lan¬ 
guage-independent  and 
supports  seven  design 
methodologies. 

For  Apple 

SuperMac  Technology 

has  introduced  three  Mac¬ 
intosh  add-on  boards.  En¬ 
hancements  include  Meg, 
a  1-megabyte  memory  ex¬ 
pansion  board  designed  to 
coexist  with  internal  hard 
disks;  SuperDrive  20,  a 


high-performance,  20-me¬ 
gabyte,  3V2-inch  internal 
hard  disk  designed  to  im¬ 
prove  the  Macintosh's  file 
access  speed  up  to  ten 
times;  and  Enhance,  a  clip- 
on  board  that  gives  the 
original  Macintosh  2  mega¬ 
bytes  of  contiguous  RAM 
and  a  Macintosh  Plus-com¬ 
patible  Small  Computer 
System  Interface  (SCSI) 
port.  Meg  is  available  for 
$849  for  upgrading  from 
128K  and  for  $699  for  up¬ 
grading  from  a  512K  Mac¬ 
intosh.  SuperDrive  costs 
$1,299.  Enhance  can  be  ex¬ 
panded  to  4  megabytes  or 
more;  its  price  has  not  yet 
been  announced. 

ProFiler  2.1,  a  data  man¬ 
ager/report  generator  for 
Apple  II  series  computers, 
now  has  its  utility  program 
integrated  into  the  overall 
program.  The  utility  fea¬ 
ture  allows  transfer  of  data 
between  ProFiler  and 
AppleWorks.  ProFiler  2.1 
can  design,  organize,  file, 
search,  sort,  merge,  calcu¬ 
late,  and  print  reports  and 
run  on  either  floppy  or 
hard  disks.  The  menu-driv¬ 
en  program  can  store  up  to 

I, 500  records  on  a  floppy 
disk  or  up  to  65,000  records 
on  a  hard  disk.  No  addition¬ 
al  data  entry  is  required  to 
transfer  data  from  one  me¬ 
dium  to  another.  The  en¬ 
tire  program,  including 
the  utility  program,  sells 
for  $99.95  and  is  available 
from  PM  Software. 

Transwarp,  an  accelera¬ 
tor  card  that  speeds  up 
both  the  main  and  auxilia¬ 
ry  memory  of  an  Apple  He 
computer,  is  available  from 
Applied  Engineering.  The 
accelerator  works  with  all 
Apple  II  +  and  lie  software, 
including  AppleWorks,  Su- 
perCalc  3a,  and  VisiCalc, 
and  is  compatible  with  all 
standard  peripheral  cards. 
The  $279  board  plugs  into 
any  available  slot  in  Apple 

II,  II  + ,  and  He  computers. 

Odesta  has  unveiled 
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four  Helix  products  for  the 
Macintosh  Plus.  Helix  is  a 
database  information- 
management  and  decision- 
support  system  that  allows 
individuals  to  build  appli¬ 
cations  tailored  to  their 
specific  needs.  Double  He¬ 
lix  allows  users  to  create 
custom  menus  and  install 
security  to  protect  the 
structure  of  their  applica¬ 
tions.  Value-added  resel¬ 
lers  and  application  pub¬ 
lishers  can  build 
stand-alone  vertical  pack¬ 
ages  with  Run-Time  Helix. 
Multiuser  Helix  allows 
networked  users  to  work 
simultaneously  with  a  cus¬ 
tomized  Helix  application. 
Helix  and  Double  Helix  for 
the  Macintosh  Plus  and 
512K  Macintosh  are  avail¬ 
able  for  $395  and  $495,  re¬ 
spectively.  Run-Time  Helix 
for  both  Macintosh  prod¬ 


ucts  can  be  licensed  for  a 
fee  of  $500  for  ten  applica¬ 
tions.  The  price  has  not  yet 
been  determined  for  Mul¬ 
tiuser  Helix. 

Communications 

Practical  Peripherals’ 

Modem  1200  is  Hayes-com¬ 
patible  and  supports  pulse 
or  touch-tone  dialing  in 
full-  or  half-duplex  opera¬ 
tion.  It  self-adjusts  to  vary¬ 
ing  transmission  speeds 
from  300  to  1,200  bits  per 
second.  The  product  con¬ 
forms  to  all  Bell  212A  and 
103  standards  and  com¬ 
plies  with  the  require¬ 
ments  of  FCC  Part  68  for  di¬ 
rect  connection  to  public 
phone  lines.  The  4X5- 
inch  card  is  installed  in  ei¬ 
ther  a  short  or  long  slot 
within  IBM  PC/XT/ AT  or 
compatible  computers. 

The  Dual  Serial  Port 


Manager  (DSPM)  is  a  hard¬ 
ware/software  interface 
program.  Available  from 
Akron  Software,  DSPM  has 
a  full-interrupt  drive,  auto¬ 
matically  buffers  all  re¬ 
ceived  and  transmitted 
data,  and  allows  users  to 
specify  the  size  of  each 
buffer  independently.  It 
also  allows  an  application 
program  to  use  both  COM1 
and  COM2  simultaneously 
and  supports  three  data- 
transfer  protocols.  The 
DSPM  package  provides  in¬ 
terfaces  to  programs  writ¬ 
ten  in  Pascal,  C,  compiled 
or  interpreted  BASIC,  FOR¬ 
TRAN,  and  assembly  lan¬ 
guage.  It  costs  $99. 

Quasitronics  has  an¬ 
nounced  the  Pipe  Six,  an 
intelligent  data  switch  that 
has  six  RS-232  I/O  ports 
that  provide  communica¬ 
tions  between  dissimilar 


systems  and/or  peripher¬ 
als  operating  with  differ¬ 
ent  baud  rates,  word  struc¬ 
tures,  and  flow  control 
techniques.  The  system 
features  54K  of  allocated 
memory  for  speed  conver¬ 
sion,  printer  buffering, 
message  storage,  and  pri¬ 
vate  mail.  It  can  handle 
concurrent  communcia- 
tions  between  all  of  its 
fully  interactive  ports. 

Unlimited  Processing 
has  announced  Team-Up,  a 
Total  Environment  for  Ap¬ 
plication  Management. 
Team-Up  adds  application 
management  to  data  man¬ 
agement  functions  by 
managing  up  to  32,000  ap¬ 
plications  containing  up  to 
700,000  files.  It  tracks  file 
existence,  file  names,  serv¬ 
er/directory  file  locations, 
and  user-access  authoriza- 
1  tions.  Prices  range  from 
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$795  to  $4,495,  depending 
on  configuration. 

Miscellaneous 

USecure,  a  system  security 
and  administration  prod¬ 
uct  for  Unix-based  comput¬ 
ers,  is  available  from  Uni¬ 
tech  Software.  USecure  is 
menu-driven  and  provides 
automated  system  access 
control  and  audit  trails  of 
system  changes,  file  modi¬ 
fications,  access  permis¬ 
sions,  deleted  files,  and 
start-up  and  shutdown  ac¬ 
tivity.  Pricing  varies  from 
$300  on  a  PC  to  $2,500  on  a 
mainframe. 

Logicraft’s  GraVAX 
brings  high-scale  resolution 
graphics  and  PC  compati¬ 
bility  to  the  VAX  environ¬ 
ment  while  maintaining 
the  VT-100  DEC  terminal  ca¬ 
pabilities.  Graf  VAX  is  a  bus 
extension  of  the  company’s 
Cardware  product  line  and 
consists  of  two  compo¬ 
nents.  The  Q-bus  version, 
which  plugs  directly  in  the 
DEC  Q-bus,  is  priced  at 
$2,990  per  user,  and  the  Un¬ 
ibus  version,  which  can  be 
located  up  to  4,000  feet 
from  the  CPU,  is  priced  at 
$5,980  per  unit. 

The  MII-1  Bubbl-Board,  a 
bubble-memory  system 
from  Bubbl-tec  allows 
Multibus  II  machines  to 
make  use  of  solid-state 
mass  storage  in  applica¬ 
tions  for  which  electrome¬ 
chanical  media  such  as 
disk  and  tape  are  unsuit¬ 
able.  The  MII-1  system  pro¬ 
vides  512K  of  nonvolatile 
mass  storage  on  a 
singlewide  Multibus  II 
module  and  incorporates 
an  intelligent  controller 
that  handles  device  for¬ 
matting  and  control,  inter¬ 
faces  the  bubble-memory 
system  to  the  Multibus  II 
bus  structure,  and  pro¬ 
vides  for  both  soft-  and 
hard-error  detection  and 


correction.  The  system  is 
also  expandable  to  32  me¬ 
gabytes.  The  512K  version 
is  priced  at  $2,899  in  quan¬ 
tities  of  ten.  Versions  with 
smaller  amounts  of  on¬ 
board  storage  capacity  are 
also  available. 
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ocean  depths.  Michael  Ham  will 
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tured  Programming  and  even 
Ray  Duncan  will  get  in  on  die 
party  For  a  change  of  pace,  well 
review  a  number  of  "turbo' 
boards  for  the  IBM  PC 
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Do  you  know 
the  meaning 

of  "morf"? 

Does  mean  any¬ 
thing  to  you?  These 
are  just  two  of  the 
ASCII  shorthand  nota¬ 
tions  sent  over  the 
public  on-line  net¬ 
works  by  modern  us¬ 
ers.  A  whole  new  cul¬ 
ture  seems  to  be 
developing  in  which  people  who 
never  hear  each  other's  voices  meet, 
get  to  know  each  other,  and  trade 
even  the  most  intimate  of  secrets.  An¬ 
onymity  is  the  rule.  You  need  reveal 
your  true  identity  only  if  you  want 
to.  The  new  teleculture  is  just  one  fac¬ 
et  of  the  rapidly  growing  consumer 
telecommunications  industry. 

Recent  estimates  by  various 
sources  put  the  amount  of  data  traffic 
on  the  nation's  phone  networks  at  30 
percent  of  total  usage.  In  downtown 
Manhattan,  data  traffic  is  thought  to 
be  around  50  percent.  Within  a  few 
years,  those  percentages  will  rise 
dramatically.  Most  of  the  new  use  is 
business  related,  but  the  consumer 
market  is  also  expanding  rapidly.  Re¬ 
cently,  CompuServe  announced  that 
it  now  has  more  than  250,000  sub¬ 
scribers  and  is  gaining  between  4,000 
and  7,000  new  users  every  month. 
The  Source  is  adding  useful  new  fea¬ 
tures  (such  as  special  interest  groups) 
and  attracting  lots  of  new  subscrib¬ 
ers.  Delphi,  People/Link,  the  WEU. 
(Whole  Earth  Lectronic  Link),  Dow 
Jones,  and  many  others  are  also 
growing  rapidly. 

New,  exotic  features  seem  to  be 
among  the  main  selling  points  for  the 
big  on-line  services.  Many  ’coast  that 
they  can  provide  more  on-line  data¬ 
bases  or  this  encyclopedia  or  that 
travel  reservation  service.  Every¬ 
thing  from  weather  forecasting  to  as¬ 
trological  predictions  seems  to  be 
available.  You  can  even  buy  cars, 
boats,  and  houses  on  line. 

1  can  ’t  help  but  wonder  what  per¬ 


centage  ot  the  ser¬ 
vices  offered  are  ac¬ 
tually  used.  What 
part  of  the  revenues 
of  the  big  systems  ac¬ 
tually  comes  from 
their  '  useful”  ser¬ 
vices?  I  suspect  that 
most  of  the  on-line 
time  is  spent  in  inter¬ 
active  chat  mode, 
in  which  two  or 
more  users  send  lines  of  text  back 
and  forth  in  real  time.  I  think  the 
next  largest  amount  of  time  is  spent 
reading  messages  in  SlGs  and  forums. 
This  is  not  necessarily  a  bad  sign — in 
fact,  1  think  it's  a  sign  of  the  new  cul¬ 
ture  emerging.  But  the  novice  may 
not  be  getting  a  very  accurate  picture 
of  what  to  expect  from  some  of  the 
current  advertisements.  People  are 
being  let!  to  join  on-line  services  by  ; 
grand  visions  that  don’t  necessarily 
reflect  the  reality.  Why  do  only  a  few 
of  the  on-line  services  advertise  (and 
even  celebrate)  the  features  that  peo¬ 
ple  actually  use  most? 

Bv  the  way,  “MORF’’  means  "male 
or  female?"  and  is  used  as  an  initial 
greeting  by  many  chat  mode  afficio- 
nados.  The  symbol  ":-)”  is  a  happy 
face  turned  on  its  side  and  is  append¬ 
ed  to  a  sentence  to  indicate  good  feel¬ 
ings  or  humorous  intent,  as  in  , 
"You’re  such  a  nerd!  Sometimes 
the  symbol  is  used  to  show  that 
the  sender  is  winking.  Can  you  guess 
what  ~-0“  means? 

ODJ  is  always  interested  in  your  ar¬ 
ticle  ideas.  Right  now  we  re  particu¬ 
larly  interested  in  articles  for  Sep¬ 
tember  (algorithms)  and  October 
i80286  and  80386).  Give  me  a  call  at 
(415)  366-3600  if  you've  got  a  nifty  i 
idea,  or  send  me  a  proposal  (with  an 
outline,  please)  at  the  address  in  the 
masthead 
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Ada 

Dear  DDJ, 

As  you  may  be  aware,  Su- 
perSoft  has  always  been  a 
supporter  of  DDJ.  I  was  par¬ 
ticularly  interested  in  the 
February  1986  issue,  which 
included  an  article  that 
concerned  our  Ada  compil¬ 
er.  (See  "Learning  Ada  on  a 
Micro.”)  I  was  sorry  to  see, 
however,  that  there  was 
no  information  on  how  to 
purchase  our  Ada  in  the  ar¬ 
ticle.  We  would  like  to  of¬ 
fer  the  readers  of  DDJ  a  30 
percent  discount  if  they 
mention  the  magazine 
when  they  order  Ada  by 
calling  (800)  762-6629. 
Margie  Foote 
SuperSoft 
P.O.  Box  1628 
Champaign,  IL  61820 

STAGES 

Dear  DDJ, 

Years  ago,  in  the  late  70s,  I 
used  a  version  of  STAGE2,  a 
remarkable  macro-con¬ 
verter  program,  on  a  DEC 
PDP-8/E. 

More  recently,  I  could 
see  in  the  CPMUG  Library  a 
STAGE2  for  the  8080  by  Dick 
Curtiss. 

Do  you  know  of  the 
availability  of  such  a  mac¬ 
ro-converter  written  for 
PC-DOS? 

Guy  Dewarichet 
Ave.  George  Bergmann, 
33 

B  - 1050  Brussels 
Belgium 

8080  Simulator 

Dear  DDJ, 

While  I  was  looking 
through  my  article  "COM: 


An  8080  Simulator  for  the 
MC68000”  in  DDJ  (January 
1986),  I  noticed  that  I  nad 
some  pretty  bad  code  in 
the  logical  instructions. 
COM  originally  had  all  the 
8080  registers  in  memory; 
with  Version  1.2  I  moved 
all  the  accumulator  and 
flags  into  68000  data  regis¬ 
ters.  Unfortunately  I  didn’t 
take  advantage  of  all  the 
68000  instructions  that  I 
now  could.  The  sequences 
in  Table  1,  page  10  (from 
Version  1.1)  could  now  be 
written  as  appears  in  Table 
2,  page  10,  instead  of  the 
way  they  were  pub¬ 
lished — provided  that  the 
high  byte  of  dO.w  is  always 
assured  to  be  zero.  (This  is 
the  case  with  the  pub¬ 
lished  code.) 

Similar  improvements 
can  be  made  to  all  yra,  ora, 
ana,  sui,  ani,  yn,  and  sub  in¬ 
structions.  Add  and  adc  in¬ 
structions  don’t  get  shorter 


because  of  the  daa  logic, 
and  sbb  doesn’t  because  of 
subjc.b  restrictions.  The 
XOR  simulations  aren’t  as 
short  as  the  others  are  be¬ 
cause  the  68000  requires 
the  source  operand  of  eor.b 
to  be  a  data  register.  Along 
with  some  short  improve¬ 
ments  to  my  ral,  rar,  and 
daa  instructions  (suggested 
by  Edmund  Ramm  of  Ger¬ 
many),  changing  dad  h  to  a 
shift  instruction,  and  re¬ 
moving  an  extraneous  in¬ 
struction  from  jmp,  I  ended 
up  with  no  perceptable  dif¬ 
ference!  As  I  had  figured 
before,  the  real  bottlenecks 
in  this  program  are  the  op¬ 
code  dispatcher  and  the 
call,  jmp,  and  ret  simula¬ 
tions. 

The  only  way  1  see  to 
really  speed  this  up  is  with 
a  68020.  As  well  as  having  a 
speed  four  times  faster  on 
68000  programs,  the  68020 
has  an  additional  address¬ 


ing  mode  of  memory  indi¬ 
rection  that  should  speed 
up  the  opcode  dispatcher, 
and  it  allows  word  accesses 
to  odd  byte  addresses.  Ta¬ 
ble  3,  page  10,  shows  what 
call  would  be  trimmed  to. 

Perhaps  someone  with  a 
68020  machine  would  care 
to  implement  this  program 
and  report  back  the  results. 

Jim  Cathey 

ISC  Systems  Corp. 

TAF-C8 

Spokane,  WA  99220 

Inefficient  C 

Dear  DDJ, 

I’d  like  to  comment  on  Hal 
Hardenbergh's  Viewpoint 
column  entitled  "Ineffi¬ 
cient  C"  in  the  January 
1986  issue  of  DDJ.  Although 
I  agree,  for  the  most  part, 
that  C  isn’t  as  efficient  as  as¬ 
sembly  language,  I  feel  that 
he  overlooked  some  very 
important  facts: 

1.  There  are  many  C  com¬ 
pilers  on  the  market,  par¬ 
ticularly  for  the  8086/8088 
processor.  The  quality  of 
the  code  produced  by 
these  compilers  ranges 
from  decent  (Manx  Aztec 
C86)  to  rotten  (Lattice  C). 
The  size  and  speed  of  the 
code  produced  by  these 
compilers  varies  for  sever¬ 
al  reasons,  the  simplest  be¬ 
ing  that  the  8086  has  an  odd 
(read:  difficult  to  use)  in¬ 
struction  set  and  architec¬ 
ture  (I  never  liked  segment¬ 
ed  memory),  making  opti¬ 
mizer  writing  a  complex 
task.  Other  reasons  are 
poor  use  of  registers  and 
high  overhead  in  subrou¬ 
tine  calls  (especially  in  pro¬ 
grams  whose  text  seg¬ 
ments  exceed  64K). 

On  PDP-ll-type  ma¬ 
chines  (where  C  originat¬ 
ed),  we’ve  found  that  there 
is  about  a  30  percent  over¬ 
head  to  C  vs.  assembler. 
Most  system  designers  con- 
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sider  this  quite  good  com¬ 
pared  to  other  high-level 
languages  (even,  dare  I  say 
it  in  the  same  breath, 
FORTRAN). 

On  other  types  of  archi¬ 
tectures,  C  is  better  or 
worse  depending  on  how 
well  the  instruction  set 
matches  the  operators  in  C, 
and  on  how  much  time 
and  effort  is  put  into  the 
compiler  design  and  the 
optimizer. 

2.  The  paragraph  that  talks 
about  the  market  voting 
with  its  wallet  and  not  car¬ 
ing  about  "how  hard  it  was 
to  produce  a  program  or 
how  long  it  took,”  etc.,  is 
true  in  essence.  Users  are 
interested  in  two  basic  fac¬ 
tors  when  purchasing  soft¬ 
ware:  cost  and  functiona¬ 
lity.  Speed  is  an  important 
factor  in  functionality.  Mr. 
Hardenbergh  has  obvious¬ 
ly  not  gone  to  market  with 


Table  1:  The  original  AND 


Table  2:  The  improved  AND 


many  products,  however; 
otherwise  he’d  know  that 
the  “market  window" 
makes  or  breaks  a  product. 

A  program  that  works, 
however  slowly,  is  better 
than  one  that  is  still  being 
written.  Being  first  can  be 
much  more  important 
than  being  fastest!  Proto¬ 
typing  in  C  and  rewriting 
parts  in  assembly  language 
is  an  accepted  method  of 
software  design;  it  also  al¬ 
lows  a  product  (alpha  or 
beta  version)  to  be  placed 
in  the  market  ASAP.  If  cod¬ 
ing  in  C  can  reduce  the  de¬ 
velopment  time  for  a  prod¬ 
uct,  then  this  may  also 
bring  down  the  cost  so  that 
even  if  the  product  is  slow¬ 
er  than  its  assembly  sibling, 
it  will  be  less  expensive. 
(Somehow,  this  doesn't 
seem  to  happen,  though.  I 
wonder  if  corporate  greed 
enters  into  play  here?) 

3.  An  example  of  an  appli¬ 
cation  in  which  C  has  made 
a  firm  stand  is  in  the  area  of 


operating  systems.  Consid¬ 
er  that  the  Unix  system  is 
about  90  percent  C  and  10 
percent  assembly  (interest¬ 
ing  that  this  particular  ratio 
pops  up,  isn't  it?);  it  com¬ 
prises  about  100K  of  in¬ 
structions  and  about  anoth¬ 
er  100K  of  data  (give  or  take 
a  little  depending  on  the 
number  of  device  drivers 
installed  and  the  amount  of 
memory  devoted  to  buffer 
caches).  Now  consider  that 
mainframe  opesating  sys¬ 
tems  written  in  assembly 
are  much  larger  (MVS  is 
around  130K  without  TSO, 
which  is  necessary  if  you 
want  to  have  an  interactive 
system.) 

Whether  Unix  is  more  or 
less  functional  than  other 
operating  systems  is  a  long¬ 
standing  dispute;  however, 
in  looking  at  Amdahl’s  UTS 
system  (a  Unix  System  V  im¬ 
plementation  for  IBM  main¬ 
frames),  I’ve  seen  a  system 
that  can  support  more  us¬ 
ers  than  can  MVS/TSO  or 
VM/CMS  on  the  same  pro¬ 
cessor.  Not  only  is  UTS  fast¬ 
er,  but  it  also  has  a  feature 
that  no  IBM  mainframe  has: 
full-duplex  asynchronous 
communications  (which 
we’re  so  used  to  that  we 
forget  how  annoying  half¬ 
duplex  is). 

I  guess  that  the  point 
here  is  that  even  though 


Unix  is  coded  mostly  in  C,  it 
has  enough  functionality 
to  make  a  dent  in  a  market¬ 
place  dominated  by  prod¬ 
ucts  coded  in  assembly  lan¬ 
guage;  enough  functional¬ 
ity  to  force  companies  to 
offer  it  as  an  option  even 
though  it  competes  with 
their  own  operating 
systems. 

Anyway,  there  is  no 
question  that  assembly 
produces  faster  code  than 
C  does  in  practically  every 
application;  the  questions 
are  whether  the  overhead 
that  goes  along  with  C  is 
worth  the  reduction  in  de¬ 
velopment  time  and  over¬ 
all  product  cost  and  wheth¬ 
er  having  the  time  to  add 
greater  functionality  to  the 
product  is  desirable. 

Patrick  Wood 

Pipeline  Associates  Inc. 

49  Manito  Ave. 

Lake  Hiawatha,  NJ  07034 

Correction 

Listing  Five  of  Brian  R.  An¬ 
derson’s  article,  "A  68000 
Cross  Assembler — Part  1,” 
(April  1986)  was  incom¬ 
plete.  The  complete  listing 
is  shown  in  Table  4,  below. 

DDJ 


and  b  move.b  regb(regs),d0  ;  A0  Ana  B 

and.b  rega(regs),d0 
move.b  dO.rega(regs) 
and.w  regconff.dO 
move.b  1 6(flagptr,d0.w),regf(regs) 
jmp  (return) 


and.b  and.b  regb(regs),rega  ;  A0  Ana  B 

move.b  1 6(flagptr,rega.w),regf 
jmp  (return) 


DEFINITION  MODULE  CodeGenerator ; 

(*  Uses  information  supplied  by  Parser,  OperationCodes,  *) 

(*  and  SyntaxAnalyzer  to  produce  the  object  code.  *) 

FRCW  Parser  IMPORT 
TOKEN,  OPERAND; 

FRCM  LongN umbers  IMPORT 
LONG; 

EXPORT  QUALIFIED 

LZero,  AddrCnt,  Pass2,  BuildSymTable,  AdvAddrCnt,  GetOb jectCode; 


LZero,  AddrCnt  :  LONG; 
Pass 2  :  BOOLEAN; 


PROCEDURE  BuildSymTable  (VAR  AddrCnt  :  LONG; 

Label,  CpCode  :  TOKEN;  SrcOp,  Destp  :  OPERAND); 

(*  Builds  symbol  table  from  symbolic  information  of  Source  File  *) 

PROCEDURE  AdvAddrCnt  (VAR  AddrCnt  :  LONG) ; 

(*  Advances  the  address  counter  based  on  the  length  of  the  instruction  *) 

PROCEDURE  GetOb jectCode  (Label,  OpCode  :  TOKEN; 

SrcOp,  DestOp  :  OPERAND; 

VAR  AddrCnt,  ObjOp,  ObjSrc,  ObjDest  :  LONG; 

VAR  nA,  nO,  nS,  nD,  :  CARDINAL) ; 

(*  Determines  the  object  code  for  the  operation  as  well  as  the  operands  *) 
(*  Returns  each  (up  to  3  fields) ,  along  with  their  length  *) 


END  CodeGenerator . 


Table  4 


call  move.w(pseudopc)+,d0 

rol.w  #8,d0  ;  Byte  reversal,  but 

move.1  pseudopc.dl 
sub.1  targbase,  dl 

rol.w  #8, dl  ;  barrel  shifter  is  quick! 

move.wdl,— (sp) 
lea.l  0(targbase,d0.1),pseudopc 
jmp  (return) 


Table  3:  CAll  using  68020  instructions 
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What’s  Wrong 
with  C 


Conventional  wisdom  is 
something  that  ought  to  be 
questioned  periodically. 
The  selection  of  C  as  the 
language  of  choice  for  mi¬ 
crocomputer  system  soft¬ 
ware  development  has  ar¬ 
guably  attained  the  status 
of  conventional  wisdom. 
After  all,  what  is  good 
enough  for  Bill  Gates  and 
his  crew  ought  to  be  good 
enough  for  us,  right? 

I  realize  that  criticizing  a 
programmer’s  favorite  lan¬ 
guage  is  likely  to  provoke  a 
defensive  reaction  more 
visceral  than  rational,  and  I 
expect  some  controversy. 

My  first  criticism  is  that 
the  code  produced  by  most 
people  using  C  as  a  tool  is 
(hang  on  to  your  hat!)  bulky 
and  slow.  Furthermore,  it  is 
not  just  bulky  and  slow 
compared  with  assembly 
language;  it  is  inefficient 
compared  with  the  output 
of  an  average  production- 
quality  optimizing  compil¬ 
er. 

Conventional  wisdom 
Lsays  that  the  reward  for 
working  in  an  inherently 
low-level  language  such  as 
C  is  efficiency.  This  is  not 
necessarily  so.  In  C,  as  in  as¬ 
sembly  language,  optimi¬ 
zation  is  the  responsibility 
of  the  individual  program¬ 
mer.  The  whole  C  philoso¬ 
phy  would  have  you  be¬ 
lieve  this  is  the  correct 
emphasis.  Unfortunately 
hand  optimization,  like 


by  David  Carew 

David  Carew  is  a  systems 
analyst  developing  banking 
applications  at  Inc.,  2864 
South  Circle  Dr.,  Ste.  200, 
Cheyenne  Centre,  Colorado 
Springs,  CO  80906. 


documentation,  never  gets 
done  (unless  of  course,  the 
product  is  about  to  become 
obsolete). 

The  brutal  fact  is  that  an 
average  optimizing  com¬ 
piler  will  outdo  the  hand- 
coded  assembler  imple¬ 
mentation  of  80  percent  of 
the  programming  popula¬ 
tion;  the  other  20  percent 
would  take  from  three  to 
ten  times  longer  to  get  a 
better  implementation  up 
and  running.  A  second  bru¬ 
tal  fact  is  that  C,  with  its 
low-level  philosophy  and 
direct  implementation  of 
pointers  and  machine-lev¬ 
el  constructs,  simply 
doesn’t  allow  the  use  of 
standard  compiler  optimi¬ 
zation  techniques.  Object 
code  generated  by  a  C  com¬ 
piler  almost  never  beats 
hand-coded  assembly. 

If  better  quality  compil¬ 
ers  were  demanded,  better 
quality  would  be  deliv¬ 
ered.  The  fact  that  good 
quality  optimizing  compil¬ 
ers  seem  scarce  in  the  mi¬ 
crocomputer  market 
should  not  be  an  excuse  for 
sticking  with  C. 

My  second  criticism  of  C 
is  also  directed  at  some¬ 
thing  usually  regarded  as  a 
strength,  or  at  least  as  an 
opportunity  for  the  pro¬ 
verbial  "experienced  pro¬ 
grammer":  C’s  operator  set 
is  too  rich.  Taken  with  the 
operator  characters  in  C's 
omnipresent  preproces¬ 
sor,  all  those  special  opera¬ 
tors  (  +  +,&,,*, ,  and  so 

forth)  and  their  accompa¬ 
nying  precedence  rules 
form  a  little  "language 
within  a  language.”  The 
programmer  is  rewarded 
for  knowing  the  nuances 
and  tricks  of  this  "lan¬ 
guage" — rewarded  with 
much  more  efficient  code. 

Thus  guided  by  the  in¬ 
visible  hand  of  the  compil¬ 
er,  the  programmer  inev¬ 


itably  tends:  (a)  to  write  less 
understandable,  less  sup¬ 
portable  code;  and  (b)  to  be¬ 
come  distracted  from  the 
task  of  contriving  an  opti¬ 
mal  solution  to  the  prob¬ 
lem  at  hand.  I  am  often 
struck  by  the  impression 
that  a  given  C  program  is 
an  elegant  example  of  C 
and  its  operators  but  misses 
the  point  as  a  solution.  On 
the  one  hand,  here  is  a  con¬ 
cordance  generator  that 
builds  a  binary  tree  instead 
of  using  a  faster,  shorter, 
and  more  robust  sort,  but 
its  use  of  pointer  operators 
in  building  the  tree  is  ex¬ 
pertly  done.  On  the  other 
hand,  there  is  a  grep-style 
search  utility  in  which  ex¬ 
pert  use  of  C's  nuances  is 
made  in  the  service  of  a 
hard-wired,  "look-ahead” 
style  parser  that  is  admit¬ 
tedly  slower  (and  probably 
bulkier)  than  a  good  table- 
driven  parser. 

From  the  standpoint  of 
the  software  designer,  a 
good  compiler  might  allow 
the  programmer  to  say  ei¬ 
ther 

b  =  +  +i 
or 

i  =  i+1 
b  =  i 

as  long  as  the  object  code 
generated  is  the  same. 
When  one  construct  gener¬ 
ates  radically  better  code 
(and  when  there  are  doz¬ 
ens  or  hundreds  of  such 
tricks  and  trade-offs),  it  is 
natural  for  the  program¬ 
mer  to  expend  effort  opti¬ 
mizing  his  or  her  use  of  the 
progamming  notation  as 
well  as  devising  an  effi¬ 
cient  solution  to  the  prob¬ 
lem  at  hand.  Because  the 
compiler  is  well-defined, 
consistent,  and  approach¬ 
able  and  the  application 


problem  is  likely  to  be  ill- 
defined,  inconsistent,  and 
messy,  it  is  very  easy  for 
the  emphasis  to  become 
misplaced. 

Make  no  mistake  about 
it,  better  algorithms  and 
data  structures  for  solution 
of  the  application  problem 
are  far  more  important 
than  is  ideal  use  of  a  com¬ 
plex  programming  nota¬ 
tion.  To  see  this  for  your¬ 
self,  benchmark  a  quick- 
and-dirty,  compiled  BASIC 
quick  sort  against  the  tight¬ 
est,  best-coded,  C  language 
selection  sort  you  can  de¬ 
vise  or  find. 

C  is  tending  to  create  a 
new  computer  elite,  a  bar¬ 
rier  to  those  who  haven't 
the  time  or  inclination  to 
master  its  complexity  (and, 
devotees  would  say,  its  at¬ 
tendant  "power”).  Because 
the  investment  in  learning 
C  is  so  high,  there  is  a 
strong  psychological  addic¬ 
tion  factor.  C  wizards  like 
being  C  wizards,  and  the 
sociology  of  this  under¬ 
standable  bias  may  be  dan¬ 
gerously  close  to  creating 
an  unnecessary,  artificial 
barrier  to  further  progress 
in  microcomputer  soft¬ 
ware  technology. 

The  measure  of  a  com¬ 
piler-based  programming 
language  is  in  the  quality  of 
its  output  object  code  and, 
perhaps  even  more  impor¬ 
tant,  in  the  productivity  of 
average  (nongenius,  non¬ 
wizard)  programmers, 
who  produce  and  main¬ 
tain  the  vast  bulk  of  all 
source  code  in  any  lan¬ 
guage.  By  these  measures, 
C  is  a  surprisingly  poor  lan¬ 
guage,  given  its  unques¬ 
tioned  acceptance.  It  may 
be  the  best  choice  we  have 
at  the  moment — though 
even  that  contention  may 
be  open  to  debate. 
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The  following  was  written 
and  uploaded  to  Data  Li¬ 
brary  0  by  Forum  member 
John  A.  Thomas.  The  on¬ 
line  discussion  ignited  by 
this  article  and  tended  by 
John,  which  is  in  DLO  as  well 
(Type  KEYWORDS:ENCRYPT 
THREAD,),  is  generating  a 
good  deal  of  heat  and  light. 
Feel  free  to  add  your  com¬ 
ments  to  the  message  board 
there. 

Survey  of  Data 
Encryption 

This  article  is  a  survey  of 
data  encryption.  It  is  in¬ 
tended  to  provoke  discus¬ 
sion  among  the  members 
of  this  forum  and  perhaps 
lead  to  a  creative  exchange 
of  ideas.  Although  the  ba¬ 
sics  of  the  subject  seem  to 
be  known  to  few  program¬ 
mers,  it  embraces  many  in¬ 
teresting  and  challenging 
programming  problems, 
ranging  from  the  optimiza¬ 
tion  of  machine  code  for 
maximum  throughput  to 
the  integration  of  encryp¬ 
tion  routines  into  editors, 
communications  packages, 
and  perhaps  products  not 
yet  invented.  Governments 
have  dominated  this  tech¬ 
nology  until  the  last  few 
years,  but  now  the  need 
for  privacy  and  secrecy  in 
the  affairs  of  a  computer¬ 
using  public  has  made  it  es¬ 
sential  that  programmers 
understand  and  apply  the 
fundamentals  of  data  en¬ 
cryption. 


by  John  A.  Thomas 
CIS  75236,3536 


Some  Cryptographic 
Basics 

A  few  definitions  are  ap¬ 
propriate  first.  We  use  the 
term  encryption  to  refer  to 
the  general  process  of  mak¬ 
ing  plain  information  se¬ 


cret  and  making  secret  in¬ 
formation  plain.  To 
encipher  a  file  is  to  trans¬ 
form  the  information  in 
the  file  so  that  it  is  no  long¬ 
er  directly  intelligible.  The 
file  is  then  said  to  be  in  ci¬ 
phertext.  To  decipher  a  file 
is  to  transform  it  so  that  it  is 
directly  intelligible — that 
is,  to  recover  the  plaintext. 

The  two  general  devices 
of  encryption  are  ciphers 
and  codes.  A  cipher  works 
on  the  individual  letters  of 
an  alphabet,  whereas  a 
code  operates  on  some 
higher  semantic  level,  such 
as  whole  words  or  phrases. 
Cipher  systems  may  work 
by  transposition  (shuffling 
the  characters  in  a  message 
into  some  new  order),  by 
substitution  (exchanging 
each  character  in  the  mes¬ 
sage  for  a  different  charac¬ 
ter  according  to  some  rule), 
or  by  a  combination  of 
both.  In  modern  usage, 
transposition  is  often 
called  permutation.  A  ci¬ 
pher  that  employs  both 
transposition  and  substitu¬ 
tion  is  called  a  product  ci¬ 
pher.  In  general,  product 
ciphers  are  stronger  than 
those  using  transposition 
or  substitution  alone.  Shan¬ 
non1  refers  to  substitution 
as  "confusion”  because  the 
output  is  a  nonlinear  func¬ 
tion  of  the  input,  thus  cre¬ 
ating  confusion  as  to  the  set 
of  input  characters.  He  re¬ 
ferred  to  transposition  as 
"diffusion”  because  it 
spreads  the  dependence  of 
the  output  from  a  small 
number  of  input  positions 
to  a  larger  number. 

Every  encryption  sys¬ 
tem  has  two  essential  parts: 
an  algorithm  for  encipher¬ 
ing  and  deciphering  and  a 
key,  which  consists  of  in¬ 
formation  to  be  combined 
with  the  plaintext  accord¬ 
ing  to  the  dictates  of  the  al¬ 
gorithm.  In  any  modern 


encryption  system,  the  al¬ 
gorithm  is  assumed  to  be 
known  to  an  opponent, 
and  the  security  of  the  sys¬ 
tem  rests  entirely  in  the  se¬ 
crecy  of  the  key. 

Our  goal  is  to  translate 
the  language  of  the  plain¬ 
text  to  a  new  "language” 
that  cannot  convey  mean¬ 
ing  without  the  additional 
information  in  the  key. 
Those  familiar  with  the 
concept  of  entropy  in  phys¬ 
ics  may  be  surprised  to 
learn  that  it  is  also  useful  in 
information  theory  and 
cryptography.  Entropy  is  a 
measure  of  the  amount  of 
disorder  in  a  physical  sys¬ 
tem  or  the  relative  absence 
of  information  in  a  commu¬ 
nication  system.  A  natural 
language  such  as  English 
has  a  low  entropy  because 
of  its  redundancies  and  sta¬ 
tistical  regularities.  Even  if 
many  of  the  characters  in  a 
sentence  are  missing  or  gar¬ 
bled,  we  can  usually  make 
a  good  guess  as  to  its  mean¬ 
ing.  Conversely,  we  want 
the  language  of  our  cipher- 
text  to  have  as  high  an  en¬ 
tropy  as  possible;  ideally,  it 
should  be  utterly  random. 
Our  guiding  principle  is 
that  we  must  increase  the 
uncertainty  of  the  cryptan¬ 
alyst  as  much  as  possible. 
His  uncertainty  should  be 
so  great  that  he  cannot 
make  any  meaningful  state¬ 
ment  about  the  plaintext  af¬ 
ter  examining  the  cipher- 
text;  also,  he  must  be  just  as 
uncertain  about  the  key, 
even  if  he  has  the  plaintext 
itself  and  the  correspond¬ 
ing  ciphertext.  (In  practice, 
it  is  impossible  to  keep  all 
plaintext  out  of  his  hands.) 

A  prime  consideration  in 
the  security  of  an  encryp¬ 
tion  system  is  the  length  of 
the  key.  If  a  short  key  (that 
is,  short  compared  with  the 
length  of  the  plaintext)  is 
used,  then  the  statistical 


properties  of  the  language 
will  begin  to  "show 
through”  in  the  ciphertext 
as  the  key  is  used  over  and 
over,  and  a  cryptanalyst 
will  be  able  to  derive  the 
key  if  he  has  enough  ci¬ 
phertext  to  work  with.  On 
the  other  hand,  we  want  a 
relatively  short  key  so  that 
it  can  be  stored  easily  or 
even  be  remembered  by  a 
human.  The  government 
or  a  large  corporation  may 
have  the  means  to  generate 
and  store  long  binary  keys, 
but  we  cannot  assume  that 
the  personal  computer  user 
will  be  able  to  do  so. 

The  other  important  fact 
about  the  keys  is  that  there 
must  be  very  many  of 
them.  If  our  system  allows 
only  10,000  different  keys, 
for  example,  it  is  not  secure 
because  our  opponent 
could  try  every  possible 
key  in  a  reasonable  amount 
of  time.  This  introduces  the 
concept  of  the  "work  fac¬ 
tor”  required  to  break  an 
encryption  system.  We 
may  not  have  a  system  un¬ 
breakable  in  principle,  but 
if  we  can  make  the  work 
factor  for  breaking  so  high 
it  is  not  practical  for  our  op¬ 
ponent  to  do  so,  then  it  is 
irrelevant  that  the  system 
may  be  less  strong  than  the 
ideal.  What  constitutes  an 
adequate  work  factor  de¬ 
pends  essentially  on  the 
number  of  uncertainties 
the  cryptanalyst  must  re¬ 
solve  before  he  can  derive 
plaintext  or  a  key.  In  these 
days  of  constantly  improv¬ 
ing  computers,  that  num¬ 
ber  should  probably  exceed 
2128.  It  is  easy  to  quantify  the 
work  factor  if  we  are  talk¬ 
ing  about  exhaustive  key 
trial,  but  few  modern  ci¬ 
phers  are  likely  to  be  bro¬ 
ken  by  key  trial  because  it  is 
too  easy  to  make  the  key 
space  very  large.  Most  like¬ 
ly  they  will  be  broken  be- 
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cause  of  internal  periodici¬ 
ties  and  subtle  dependency 
of  output  on  input,  which 
give  the  cryptanalyst 
enough  information  to  re¬ 
duce  his  uncertainty  by  or¬ 
ders  of  magnitude. 

A  corollary  to  work  fac¬ 
tor  is  the  rule  that  a  system 
need  only  be  strong  enough 
to  protect  the  information 
for  however  long  it  has  val¬ 
ue.  If  a  system  can  be  bro¬ 
ken  in  a  week,  but  not  soon¬ 
er,  then  it  may  be  good 
enough  if  the  information 
has  no  value  to  an  oppo¬ 
nent  after  a  week. 

Cryptanalysis 

Cryptanalysis  is  the  science 
of  deriving  plaintext  with¬ 
out  the  key  information. 
Anyone  intending  to  de¬ 
sign  an  encryption  system 
must  be  acquainted  to 
some  degree  with  cryptan- 
alytic  methods.  The  meth¬ 
ods  of  attack  may  range 
from  sophisticated  statisti¬ 
cal  analysis  of  ciphertext  to 
breaking  into  the  oppo¬ 
nent's  office  and  stealing 
his  keys  ("practical  crypt¬ 
analysis”).  There  are  no 
rules  of  fair  play.  The 
cryptanalyist  is  free  to  use 
his  puzzle-solving  ingenu¬ 
ity  to  the  utmost,  even  to 
the  point  of  applying  the 
knowledge  that  your  dog's 
name  is  Pascal  and  that  you 
might  be  lazy  enough  to 
use  that  as  your  key  for  the 
day. 

The  cryptanalyst  may 
have  only  ciphertext  to 
work  with,  he  may  have 
both  ciphertext  and  the  cor¬ 
responding  plaintext,  or  he 
may  be  able  to  obtain  the 
encipherment  of  chosen 
plaintext.  Some  crypto¬ 
graphic  systems  are  fairly 
strong  if  the  analyst  is  limit¬ 
ed  to  ciphertext  but  fail 
completely  if  he  has  corre¬ 
sponding  plaintext.  Your 
system  should  be  strong 


enough  to  resist  attack  even 
if  your  opponent  has  both 
plaintext  and  ciphertext. 

Computer  power  can 
greatly  aid  cryptanalysis, 
but  many  systems  that  ap¬ 
pear  strong  can  be  broken 
with  pencil-and-paper 
methods.  The  Vigenere 
family  of  polyalphabetic  ci¬ 
phers,  for  example,  was 
generally  believed  to  be  un¬ 
breakable  up  until  the  late 
nineteenth  century.  A  po¬ 
lyalphabetic  cipher  is  a  sub¬ 
stitution  cipher  in  which  a 
different  alphabet  is  used 
for  each  character  of  plain¬ 
text.  In  these  systems,  the 
key  determines  the  order 
of  the  substitution  alpha¬ 
bets,  and  the  cycle  repeats 
with  a  period  equal  to  the 
length  of  the  key.  This  peri¬ 
odicity  is  a  fatal  weakness 
because  fairly  often  a  re¬ 
peated  letter  or  word  of 
plaintext  will  be  enci¬ 
phered  with  the  same  key 
letters,  giving  identical 
blocks  of  ciphertext.  This 
exposes  the  length  of  the 
key.  Once  we  have  the 
length  of  the  key,  we  use 
the  known  letter  frequen¬ 
cies  of  the  language  to  grad¬ 
ually  build  and  test  hypoth¬ 
eses  about  the  key. 
Vigenere  ciphers  can  be  im¬ 
plemented  easily  on  com¬ 
puters,  but  they  are  worth¬ 
less  today.  Designers 
without  knowledge  of 
cryptanalysis,  however, 
might  be  just  as  ignorant  of 
this  fact  as  their  colleagues 
of  the  last  century.  Please 
see  the  references  at  the 
end  of  this  article  for  infor¬ 
mation  on  cryptanalytic 
techniques. 

A  Survey  of  Crypto¬ 
graphic  Systems 

I’ll  now  review  some  rep¬ 
resentative  encryption 
schemes,  starting  with  tra¬ 
ditional  ones  and  proceed¬ 
ing  to  the  systems  that  are 
only  feasible  when  imple¬ 
mented  on  computers. 

The  infinite-key  cipher, 


also  known  as  the  "one 
time  pad,”  is  simple  in  con¬ 
cept.  First,  we  generate  a 
key  that  is  random  and  at 
least  the  same  length  as  our 
message.  Then,  for  each 
character  of  plaintext,  we 
add  the  corresponding 
character  of  the  key  to  give 
the  ciphertext.  By  addition, 
we  mean  some  reversible 
operation;  the  usual  choice 
is  the  exclusive-OR.  A  little 
reflection  will  show  that, 
given  a  random  key  at  least 
the  size  of  the  plaintext 
(that  is,  "infinite”  with  re¬ 
spect  to  the  plaintext  be¬ 
cause  it  is  never  repeated), 
the  resulting  cipher  is  un¬ 
breakable,  even  in  princi¬ 
ple.  This  scheme  is  in  use 
today  for  the  most  secret 
government  communica¬ 
tions,  but  it  presents  a  seri¬ 
ous  practical  problem  with 
its  requirement  for  a  long 
random  key  for  each  mes¬ 
sage  and  the  need  to  some¬ 
how  send  the  lengthy  key 
to  the  recipient.  Thus  the 
ideal  infinite-key  system  is 
not  practical  for  large  vol¬ 
umes  of  message  traffic.  It 
is  certainly  not  practical 
for  file  encryption  on  com¬ 
puters  because  where 
would  the  key  be  stored? 
Be  wary  of  schemes  that 
use  software  random- 
number  generators  to  sup¬ 
ply  the  infinite  key.  Typi¬ 
cal  random-number 
algorithms  use  the  preced¬ 
ing  random  number  to 
generate  the  succeeding 
number  and  can  thus  be 
solved  if  only  one  number 
in  the  sequence  is  found. 

Some  ciphers  have  been 
built  to  approximate  the  in- 
finite-key  system  by  ex¬ 
panding  a  short  key.  The 
Vernam  system  for  tele¬ 
graph  transmission  used 
long  paper  tapes  contain¬ 
ing  random  binary  digits 
(Baudot  code,  actually)  that 
were  exclusively-ORed 
with  the  message  digits.  To 
achieve  a  long  key  stream, 
Vernam  and  others  used 


two  or  more  key  tapes  of 
relatively  prime  lengths, 
giving  a  composite  key 
equal  to  their  product.  The 
system  is  still  not  ideal  be¬ 
cause  eventually  the  key 
stream  will  repeat,  allow¬ 
ing  the  analyst  to  derive 
the  length  and  composi¬ 
tion  of  the  keys  given 
enough  ciphertext.  There 
are  other  ways  to  ap¬ 
proach  the  infinite-key  ide¬ 
al,  some  of  which  are  sug¬ 
gested  in  my  article  (with 
Joan  Thersites)  in  the  Au¬ 
gust  1984  issue  of  DDJ.  (See 
sidebar  on  page  20.) 

Rotor  systems  take  their 
name  from  the  electrome¬ 
chanical  devices  of  World 
War  II,  the  best  known  be¬ 
ing  perhaps  the  German 
ENIGMA.  The  rotors  are 
wheels  with  characters  in¬ 
scribed  on  their  edges  and 
with  electrical  contacts 
corresponding  to  the  let¬ 
ters  on  both  sides.  A  plain¬ 
text  letter  enters  on  one 
side  of  the  rotor  and  is 
mapped  to  a  different  let¬ 
ter  on  the  other  side  before 
passing  to  the  next  rotor 
and  so  on.  All  the  rotors 
(and  there  may  be  few  or 
many)  are  then  stepped  so 
that  the  next  substitution  is 
different.  The  key  is  the  ar¬ 
rangement  and  initial  set¬ 
ting  of  the  rotor  disks. 
These  devices  are  easy  to 
implement  in  software 
and  are  fairly  strong.  They 
can  be  broken,  however; 
the  British  solution  of  the 
ENIGMA  is  an  interesting 
story  outside  the  scope  of 
this  article.  If  you  imple¬ 
ment  a  rotor  system,  con¬ 
sider  having  it  operate  on 
bits  or  nybbles  instead  of 
bytes,  consider  adding  per¬ 
mutation  stages,  and  con¬ 
sider  how  you  are  going  to 
generate  the  rotor  tables 
because  you  must  assume 
these  will  become  known 
to  an  opponent. 

In  1977  the  National  Bu¬ 
reau  of  Standards  promul¬ 
gated  the  Data  Encryption 
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Standard  (DES)  as  the  en¬ 
cryption  system  to  be  used 
by  all  federal  agencies  (ex¬ 
cept  for  those  enciphering 
data  classified  under  any  of 
the  national  security  acts). 
The  standard  is  available  in 
a  government  publication 
and  also  in  several  books. 
The  DES  was  intended  to  be 
implemented  only  in  hard¬ 
ware,  probably  because  its 
designers  did  not  want  us¬ 
ers  to  make  changes  to  its 
internal  tables.  DES  has 
been  implemented  in  soft¬ 
ware,  however,  and  is 
available  in  several  micro¬ 
computer  products  (such 
as  Borland's  SuperKey  or 
IBM’s  Data  Encoder). 

The  DES  is  a  product  ci¬ 
pher  using  16  stages  of  per¬ 
mutation  and  substitution 
on  blocks  of  64  bits  each. 
The  permutation  tables  are 
fixed,  and  the  substitutions 
are  determined  by  bits 
from  a  56-bit  key  and  the 
message  block.  This  short 
key  has  caused  some  ex¬ 
perts  to  question  the  secu¬ 
rity  of  DES.  Controversy 
also  exists  regarding  the  in¬ 
volvement  of  the  National 
Security  Agency  in  parts  of 
the  DES  design.  The  issues 
are  interesting  but  beyond 
the  scope  of  this  article. 

Because  DES  was  intend¬ 
ed  for  hardware  imple¬ 
mentation,  it  is  relatively 
slow  in  software.  Software 
implementations  of  DES  are 
challenging  because  of  the 
bit  manipulation  required 
in  the  key  scheduling  and 
permutation  routines  of  the 
algorithm.  Some  imple¬ 
mentations  gain  speed  at 
the  expense  of  code  size  by 
using  large,  precomputed 
tables. 

The  public-key  cipher  is 
an  interesting  new  devel¬ 
opment  that  shows  poten¬ 
tial  for  making  other  en¬ 
cryption  systems  obsolete. 
It  takes  its  name  from  the 


fact  that  the  key  informa¬ 
tion  is  divided  into  two 
parts,  one  of  which  can  be 
made  public.  A  person 
with  the  public  key  can  en¬ 
cipher  messages,  but  only 
one  with  the  private  key 
can  decipher  them.  All 
public-key  systems  rely  on 
the  existence  of  certain 
functions  for  which  the  in¬ 
verse  is  very  difficult  to 
compute  without  the  infor¬ 
mation  in  the  private  key. 
These  schemes  do  not  ap¬ 
pear  to  be  practical  for  mi¬ 
crocomputers — at  least  for 
8-bit  machines — if  their 
strength  is  to  be  exploited 
fully.  One  variety  of  the 
public-key  system  (the 
knapsack)  has  been  broken 
by  solution  of  its  encipher¬ 
ing  function,  but  this  is  no 
reflection  on  other  sys¬ 
tems,  such  as  the  RSA 
scheme,  which  use  differ¬ 
ent  enciphering  functions. 
All  public-key  systems  pro¬ 
posed  to  date  require 


From  the  Data 
Library 

Listings  One  and  Two,  page 
66,  are  the  68000  versions 
of  the  permutation  rou¬ 
tines  described  in  Z80  code 
in  the  article  “Designing  a 
File  Encryption  System”  in 
the  August  1984  issue  of 
DDJ.  Permf  performs  the 
forward  permutation  of 
the  bits  in  a  256-bit  block  as 
specified  by  a  table  of 
bytes.  Permg  performs  the 
inverse  permutation. 

For  example,  if  the  per¬ 
mutation  table  has  the 
values 

1  15  115  57  ...  0 

then  the  forward  permuta¬ 
tion  means  to  put  the  1st  bit 
of  the  block  in  the  0th 
place,  the  15th  bit  in  the  1st 
place,  the  115th  bit  in  the 
2nd  place,  and  so  on  until 
the  0th  bit  goes  in  the  255th 
place. 


heavy  computation,  such 
as  the  exponentiation  and 
division  of  very  large  num¬ 
bers  (200  decimal  digits  for 
the  RSA  scheme).  On  the 
other  hand,  a  public-key 
system  that  worked  at  only 
10  bytes/second  might  be 
useful  if  all  we  are  sending 
are  the  keys  for  some  other 
system,  such  as  the  DES. 

Some  Random 
Thoughts 

•  Must  we  operate  on 
blocks  instead  of  bytes? 
Block  ciphers  seem  stron¬ 
ger  because  they  allow  for 
permutation.  On  the  other 
hand,  they  make  life  diffi¬ 
cult  when  file  size  is  not  an 
integral  multiple  of  the 
block  size. 

•  Can  we  make  a  file  en¬ 
cryption  system  OS-inde¬ 
pendent?  This  is  related  to 
the  question  above  on 
blocks  vs.  bits.  How  do  we 
define  the  end  of  file  if  the 
plaintext  is  ASCII  and  the  ci- 


The  inverse  permutation 
with  the  same  table  means 
to  place  the  0th  bit  of  the 
block  in  the  1st  place,  the 
1st  bit  in  the  15th  place,  the 
2nd  bit  in  the  115th  place, 
and  so  on  until  the  255th  bit 
goes  in  the  0th  place. 

In  the  original  crypto¬ 
graphic  use,  the  permuta¬ 
tion  table  was  assumed  to 
be  cycled  to  its  next  permu¬ 
tation  after  the  encryption 
of  each  block.  I  will  upload 
the  cycle  routine  that  does 
this  fairly  soon. 

The  routines  address  bits 
in  the  block  by  deriving  a 
bit  index  from  the  byte  val¬ 
ue  of  the  permutation  ta¬ 
ble.  The  upper  five  bits  of 
that  value  index  to  the  par¬ 
ticular  byte  in  the  block, 
and  the  lower  three  bits 
then  index  to  the  particu¬ 
lar  bit  within  that  byte. 

The  routines  run  about 
three  times  faster  than  the 
Z80  versions. 


phertext  can  be  any  8-bit 
value? 

•  Can  we  find  an  efficient 
way  to  generate  and  store  a 
random  key  for  the  infi¬ 
nite-key  system?  Hard¬ 
ware  random-number 
generators  are  not  hard  to 
build,  but  would  they  be  of 
any  use? 

•Bit  fiddling  is  expensive. 
Can  it  be  avoided  and  still 
leave  a  secure  system? 

•  No  file-encryption  system 
can  erase  a  file  logically  and 
be  considered  secure.  The 
information  can  be  recov¬ 
ered  until  it  is  overwritten. 
Overwriting  files  adds  to 
processing  time.  I  am  in¬ 
formed  that  it  is  possible  to 
reliably  extract  informa¬ 
tion  even  from  sectors  that 
have  been  overwritten.  Is 
this  so?  If  it  is,  what  is  the 
solution? 

•  How  do  we  integrate  en¬ 
cryption  systems  into  dif¬ 
ferent  tools?  Should  a  tele¬ 
communications  program 
encrypt  data  transparently 
if  the  correspondent  is 
compatible?  What  about  an 
editor-encryption  system 
wherein  plaintext  would 
never  exist  on  the  disk, 
only  on  the  screen?  How 
would  we  manage  to  enci¬ 
pher/decipher  text  as  we 
scroll  through  it  and  make 
changes  and  still  get  ac¬ 
ceptable  performance? 

•  By  their  nature,  encryp¬ 
tion  schemes  are  difficult 
to  test.  What  test  might  we 
subject  a  system  to  that 
would  increase  our  confi¬ 
dence  in  it? 

Note 

1.  Claude  Shannon,  “Com¬ 
munication  Theory  of  Se¬ 
crecy  Systems,”  Bell  Sys¬ 
tem  Technical  Journal  (Oct. 
1949):  656  -  715. 
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_ C  CHEST _ 

Sort — A  General-Purpose  Sorting  Program 


As  tax  time  rolls  around  again 
(I’m  writing  this  column  in 
March),  the  dreaded  task  of  organiz¬ 
ing  my  tax  records  rears  its  ugly 
head.  The  year  before  last  I  used 
dBASE  to  do  this  organizing,  and  last 
year  I  used  Lotus  1-2-3.  Neither  pro¬ 
gram  is  really  satisfactory.  It's  too 
hard  to  enter  data  using  dBASE,  and 
the  Lotus  spreadsheet  does  just  that, 
spread  out  all  over  my  dining  room 
table.  Both  programs  are  designed  to 
do  much  more  than  needed  anyway. 
All  I  want  to  do  is  create  a  normal  file, 
with  a  normal  editor,  in  which  each 
line  represents  a  deductible  item. 
The  line  is  split  up  into  several  fields 
(date,  category,  description,  amount, 
check  number),  and  the  entire  file 
must  be  sorted  first  by  category  and 
then  by  date  (that  is,  all  lines  for  a 
single  category  have  to  be  grouped 
and  the  lines  within  the  category 
need  to  be  sorted  by  date). 

So,  my  solution  to  this  problem  was 
to  dust  off  an  old  sort  utility  and  mod¬ 
ify  it  so  that  it  could  handle  files  larg¬ 
er  than  the  amount  of  available 
memory.  This  month,  I’ll  discuss  this 
program,  which  is  called  sort. 

Sort  sorts  the  lines  of  an  ASCII  file 
(or  collection  of  files) — that  is,  the  in¬ 
dividual  lines  are  rearranged  but  the 
words  on  a  line  aren’t  changed.  Its 
command-line  syntax  is: 

sort  [  —  options]  [file  . .  .] 

If  no  files  are  given  on  the  command 
line,  standard  input  is  used.  If  several 
files  are  listed,  they  are  treated  as  if 
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they  were  one  big  file  and  then  sort¬ 
ed.  It’s  as  if  sort  merged  them  all  to¬ 
gether  into  a  single  file  and  then  sort¬ 
ed  that  single  file. 

Various  command-line  options  are 
supported  (see  Table  1,  page  24). 
These  are: 


—  b — Ignore  leading  white  space 
(blanks,  tabs,  form-feeds,  and  so 
on).  If  you're  sorting  on  fields  (see 
below),  then  white  space  follow¬ 
ing  the  field  delimiter  is  ignored 
(even  if  the  field  delimiter  itself  is  a 
space  or  tab). 

— d — Sort  in  dictionary  order.  That  is, 
all  characters  except  letters  and 
numbers  are  ignored  for  the  pur¬ 
poses  of  comparison — for  exam¬ 
ple,  hand  puppet  will  be  between 
handmade  and  handsaw  in  the 
output. 

—  f — Fold  uppercase  letters  into  low¬ 

ercase  before  comparing.  Normal¬ 
ly  uppercase  letters  have  a  higher 
value  than  lowercase — foo  will 
follow  Foo  in  the  output  file. 

—  n — This  flag  is  treated  in  a  very  dif¬ 

ferent  way  from  the  way  the  Unix 
sort  utility  treats  it.  Here,  if  two 
numbers  (with  an  optional  leading 
—  sign)  appear  in  the  same  posi¬ 
tion  on  two  lines,  they  are  treated 
as  a  single  number  rather  than  as  a 
collection  of  ASCII  characters.  For 
example,  the  list 

2 

1 

20 

10 

will  normally  be  sorted  as  a  collec¬ 
tion  of  ASCII  characters,  yielding 

1 

10 

2 

20 

If  —  n  is  given  on  the  command 


line,  they’ll  be  sorted  as 

1 

2 

10 

20 

Numbers  are  treated  specially 
wherever  they’re  found,  even  if 
they’re  imbedded  in  a  word,  so 
the  list 

word2 

wordl 

word20 

wordlO 

will  sort  to 

wordl 

word2 

wordlO 

word20 

if  —  n  is  specified.  Note,  though, 
that  the  numbers  have  to  be  at  the 
same  relative  place  on  the  line,  so 

word  1 
word  2 
word  10 
word  20 

sorts  to 

word  10 
word  20 
words  1 
words  2 

unless  —  d  is  also  specified. 

Note  that  a  version  of  stoi(  ),  the 
number-processing  routine  used 
for  numeric  processing,  was  origi¬ 
nally  published  in  the  May  1985  C 
Chest.  (See  Listing  Two,  page  83.) 
The  version  given  here  differs 
from  the  original  in  that  it's  been 
scaled  down  to  accept  only  deci¬ 
mal  numbers  (the  original  accept¬ 
ed  hex  and  octal  numbers  too). 

— t<c> — The  single  character  <c> 
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specifies  a  field  separator  charac¬ 
ter  (the  default  is  a  tab,  thus  the  t ). 
For  example,  —  t,  tells  sort  to  use  a 
comma  as  a  field  separator. 

—  p<num> — Sort  field  <num> 
only  where  fields  are  delimited  by 
the  character  specified  with  the 
—t  argument.  The  leftmost  field  is 
field  1.  For  example,  the  file 

ant,  bat,  cow 
bat,  cow,  ant 
cow,  ant,  bat 

when  sorted  with  the  command 
line 

sort  —  t,  —  p2  file 


Table  1:  Sort  command-line  options 


will  yield 

cow,  ant,  bat 
ant,  bat,  cow 
bat,  cow,  ant 

Only  the  second  field,  rather  than 
the  entire  line,  is  looked  at  by  sort. 
—  s<num> — Specify  a  secondary 
key.  When  sorting  fields,  if  the 
contents  of  the  fields  specified  by 
the  primary  key  are  the  same, 
then  the  secondary  field  is  used  to 
resolve  differences.  For  example, 
the  file 

ant,  cow,  cow 
bat,  cow,  ant 
cow,  ant,  bat 

when  sorted  with  the  command 
line 


sort  —  t,  —  p2  —  s3  file 

will  yield 

cow,  ant,  bat 
bat,  cow,  ant 
ant,  cow,  cow 

Here,  the  last  two  lines  both  have 
cow  in  the  primary  sort  field  (field 
2),  so  they  are  ordered  depending 
on  what  sort  finds  in  the  second¬ 
ary  sort  field  (field  3).  Given  a  file 
containing  lines  of  the  form 

<date>,  <category>, 

<other  stuff> 

my  tax  preparation  can  be  done 
with  the  command  line 

sort  —  n  —  t,  —  p2  —si  ledger 

>outfile 

Here  the  —  n  causes  the  dates  to  be 
sorted  numerically,  a  comma  is 
used  to  separate  fields  (— t,),  the 
primary  sort  field  is  the  category 
(— p2),  and  the  secondary  sort  field 
is  the  date  ( — si).  The  other  fields 
on  the  line  are  ignored.  The  de¬ 
fault  primary  field  is  1  (the  left¬ 
most)  if  — s  but  no  —p  is  given  on 
the  command  line. 

—  r — Do  a  reverse  sort  (sort  in  de¬ 
scending  rather  than  ascending 
order). 

— T<str> — The  <str>  is  prefixed  to 
all  intermediate  file  names.  Inter¬ 
mediate  files  are  usually  called 
merge.l,  merge. 2,  and  so  on.  If  you 
say 

sort  —  T/tmp/  file 

then  the  temporary  files  will  be 
called  /tmp/merge.l,  /tmp/ 
merge.2,  and  so  on.  Remember  to 
put  the  trailing  slash  on  the  string 
if  you're  specifying  a  directory 
name  (as  compared  to  a  RAMdisk 
designator  or  whatever). 

—  u — Delete  duplicate  lines  in  the 
output.  After  the  file  is  sorted, 
only  one  of  a  series  of  identical 
lines  is  output. 

Sorting  Large  Files 

Two  general-purpose  sort  routines 
have  been  printed  in  this  column:  a 
quicksort  routine  ( qsortl  ))  was  print¬ 
ed  in  April  1985  and  a  shell  sort 


-b 

ignore  leading  white  space  (blanks) 

-d 

sort  in  dictionary  order 

-f 

fold  uppercase  into  lowercase 

-n 

sort  numbers  by  numeric  value 

— p<num> 

use  field  <num>  as  primary  key 

-r 

do  a  reverse  sort 

-s<num> 

use  field  <num>  as  secondary  key 

—  t<c> 

use  <c>  to  separate  fields 

-T<str> 

prepend  <str>  to  temp  file  names 

-u 

delete  duplicate  lines  in  output 

ssort(array,  nel,  elsize,  cmp) 

char 

'array;  /'  Pointer  to  array  being  sorted  7 

int 

nel;  /*  Number  of  elements  in  array  */ 

int 

elsize;  /*  Size  of  one  element  in  bytes  7 

int 

(*cmp)( );  /*  Pointer  to  a  comparison  function  7 

Ssortf )  sorts  the  array  using  a  shell  sort.  Cmp  is  a  pointer  to  a  comparison  function  that 
acts  like  strcmpf )  does.  Cmp(a.b)  must  return  a  negative  number  if  a<b ,  zero  if  a==b, 
and  a  positive  number  if  a>b.  It  is  passed  pointers  to  two  array  elements.  Argv  can  be 

sorted  with 

acmp(a,  b) 
char 

/ 

**a,  **b; 

\ 

} 

return(  strcmpfa,  ’b) ); 

main(  argc,  argv 
int 

) 

argc; 

char 

/ 

**argv; 

\ 

} 

ssort(  argv,  argc,  sizeof(*argv),  acmp ); 

Table  2:  Calling  syntax  to  ssort 
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( ssort(  ))  was  printed  in  March  1986. 
Both  algorithms  were  discussed  in 
the  April  1985  column.  The  qsortf  )■ 
j  subroutine  is  also  included  in  many 
compilers'  I/O  libraries.  All  these 
routines  have  an  identical  calling 
syntax  so  they  can  be  used  inter- 
|  changeably. 

[  These  sort  routines  all  have  one  ma¬ 
jor  limitation.  The  entire  array  being 
sorted  has  to  be  in  memory  at  once. 
Sometimes  you  need  to  sort  files  that 
are  larger  than  the  amount  of  avail¬ 
able  memory,  however.  This  limita¬ 
tion  is  circumvented  by  using  tempo- 
j  rary  merge  files.  Sort  reads  as  much 
input  as  it  can,  sorts  that  input,  and 
then  writes  the  sorted  lines  to  a  tem¬ 
porary  file.  It  continues  in  this  man- 
j  ner  until  the  input  is  exhausted,  creat- 
j  ing  a  bunch  of  temporary  files,  one 
for  each  pass.  The  program  then 
merges  the  temporary  files,  writing 
the  results  to  standard  output.  Finally, 
the  temporaries  are  delete cT. 

The  process  is  best  illustrated  with 
an  example.  Say  that  at  most  three 
input  lines  can  be  held  in  memory 
and  a  file  containing 

good 

every 

boy 

favor 

deserves 

has  to  be  sorted.  Sort  reads  in  the  first 
|  three  lines,  sorts  them,  and  then  cre¬ 
ates  a  temporary  file.  It  then  repeats 
the  process  with  the  remaining  two 
lines.  The  temporary  files  look  like 

MERGE.l  MERGE.2 

boy  deserves 

every  favor 

good 

!  They  are  both  sorted.  The  program 
now  merges  the  files.  It  reads  in  the 
first  line  of  each  merge  file 

boy 

deserves 

outputs  the  lesser  line  (boy)  and  re¬ 
places  it  with  the  next  line  from  the 
temporary  file  that  originally  con¬ 
tained  boy  (merge.l): 

every 

deserves 


The  program  now  repeats  the 
same  process  on  the  two  current 
lines,  outputting  deserves  and  replac¬ 
ing  it  with  the  next  line  from 
j  merge. 2: 

every 

favor 

every  is  output  and  replaced  by  the 
last  line  in  merged: 

good 

favor 

favor  is  now  output.  Because  merged 
!  is  now  empty,  no  input  is  fetched  and 
the  list  contains  the  single  word  good, 
which  is  output  in  turn.  Because  all 
I  merge  files  are  now  empty,  the  pro¬ 
gram  ends. 

The  same  process  can  be  used 
when  there’s  more  than  one  merge 
file.  The  program  reads  in  one  line 
from  each  file,  outputs  the  line  hav¬ 
ing  the  lowest  value,  and  then  re¬ 
places  that  line  with  the  next  line 
from  the  appropriate  merge  file,  con¬ 
tinuing  the  process  until  all  the 
merge  files  are  empty. 

The  problem  here  is  selecting  the 
line  having  the  smallest  value.  The 
simplest  method  is  to  keep  an  argv- 
like  array  of  pointers  to  strings, 
where  each  string  is  one  line  from  a 
merge  file.  The  array  is  sorted  on 
each  pass,  and  the  lowest  element  is 
output.  Sorting  the  array  each  time 
isn't  very  efficient,  though.  You're 
constantly  resorting  an  almost-sorted 
array.  A  better  way  to  store  the  lines 
is  in  a  data  structure  called  a  heap.  A 
heap  is  an  array  that  has  the  proper¬ 
ty  that  the  Kth  element  is  always  less 
than  the  (2K)th  and  (2K+l)th  ele¬ 
ments.  For  example,  array  [1]  is  less 
than  both  array[2]  and  array  13],  ar- 
ray[2]  is  less  than  both  array [4]  and 
array[5],  array[3j  is  less  than  both  ar¬ 
ray/6/  and  array[7],  and  so  on.  You 
can  look  at  a  heap  as  a  sort  of  binary 
tree,  where  the  Kth  element  is  the 
parent  node  and  the  (2K)th  and 
(2K Tilth  elements  are  the  children. 
All  sorted  arrays  are  heaps;  on  the 
other  hand,  a  heap  is  not  necessarily 
a  sorted  array. 

Heaps  have  two  additional  proper¬ 
ties  that  are  of  use  here:  The  first  ele¬ 
ment  is  always  the  smallest  element, 
and  a  new  element  can  be  inserted  in 
the  heap  in  O(logN)  time,  where  N  is 
the  heap  size. 


|  Implementation  Details  ! 

1  Sort  is  presented  in  Listing  One,  page 
68.  Various  # defines  are  on  lines  ; 
18— 28.  MAXBUF  is  the  maximum  line 
length  (now  132  columns).  Lines  long¬ 
er  than  this  will  be  treated  as  if  they 
were  two  lines.  MAXLINEC  (now  1024) 
is  the  maximum  number  of  input 
lines  than  can  be  read  before  a  merge 
file  is  created.  MAXTMP  (now  18)  is 
the  maximum  number  of  temporary 
files  that  can  be  open  at  once.  This 
number  is  limited  by  either  your 
compiler  or  the  operating  system. 
Two  file  descriptors  are  needed  for 
stdout  and  stderr,  so  I'm  assuming 
here  that  20  files  may  be  open  at  one 
time.  This  assumption  isn’t  true  in 
some  CP/M  systems  that  only  allow 
eight  files.  In  DOS,  to  have  20  file  de¬ 
scriptors  available,  you  must  say 

files=20 

in  your  config.sys  file.  It  will  speed 
up  your  I/O  to  put 

buffers =20 

up  there  too. 

The  global  variables  on  lines  36 — 45 
are  all  set  by  getargsf  ),  depending  on  ; 
what  it  finds  on  the  command  line. 
(The  source  for  getargsf  )  isn’t  in  the 
listing;  see  below  for  availability.) 
The  Argtab  on  lines  47—61  is  also 
used  by  getargsf  ).  Global  variables  , 
not  concerned  with  command-line 
switches  are  declared  on  lines 
70  —  88.  Options  is  set  to  true  by 
mainf )  if  any  of  the  command-line 
switches  that  affect  the  sort  order  are 
present.  Lines  and  Linec  are  used  in  | 
the  same  way  as  argv  and  argc.  Lines 
holds  pointers  to  the  input  lines  read 
in  during  the  initial  sorting  passes 
(not  the  merge  passes).  Linec  is  the 
number  of  valid  lines  in  Lines.  Argv 
and  Argc  are  just  global  copies  of  the 
argv  and  argc  used  by  mainf  ). 

The  HEAP  structure  defined  on 
lines  80— 85  is  used  to  define  the  heap 
needed  in  merge-file  processing.  You 
need  to  remember  two  things  about 
every  heap  entry — the  contents  of 
the  current  line  in  the  merge  file  and 
the  FILE  pointer  associated  with  that 
merge  file.  So  you  use  a  structure 
having  two  fields:  string  and  file.  The 
heap  itself  is  an  array,  MAXTMP  ele¬ 
ments  long,  of  pointers  to  HEAP  struc¬ 
tures.  I  chose  to  use  an  array  of  point-  I 
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|  ers  rather  than  an  array  of  structures 
because  it  takes  much  less  time  to  ex¬ 
change  two  pointers  than  it  does  to 
exchange  two,  rather  large,  struc¬ 
tures.  This  pointer  array  is  created 
using  mallocf  ),  and  it  is  pointed  at  by 
the  global  variable  Heap  (defined  on 
line  87). 

The  routine  pheapf  )  (lines  95—108) 
is  a  debugging  routine  that  prints  out 
the  current  heap  contents.  Note  that 
if  DEBUG  isn’t  * defined ,  then  pheapf ) 
will  be  * defined  as  a  null  macro  (one 
that  expands  to  a  null  string).  This 
way  you  don’t  have  to  put  #ifdef  DE¬ 
BUG  /#endif  directives  around  all  the 
calls  to  pheapf  ). 

Lines  are  read  into  memory  by 
gtejctf  )  (line  358f).  It  loads  the  input 
lines  into  an  argv-like  array  of  point¬ 
ers  to  strings  (Lines).  The  routines  that 
call  gtext  don't  know  that  it  may  be 
getting  input  from  several  files  (as  list¬ 
ed  on  the  command  line).  Gtejct  [or 
rather  ne^tfilef )  (line  324f),  which  is 
i  called  by  gtejctf )]  takes  care  of  all  the 
I  argv  processing  needed  to  open  and 
read  the  various  files  when  appropri¬ 
ate. 

Skipping  forward,  the  initial  sort¬ 
ing  of  the  Lines  array  is  done  by  the 
call  to  ssortf )  on  line  617.  The  calling 
syntax  for  ssortf  )  is  shown  in  Table 
2,  page  24. 

The  beauty  of  passing  a  pointer  to  a 
subroutine  becomes  obvious  when 
looking  at  a  routine  such  as  ssortf ). 
Not  only  can  an  array  of  pointers  to 
strings  be  sorted  with  the  routine 
shown  in  Table  2  but  also  a  more 
complicated  sort  (such  as  the  one  re¬ 
quired  by  my  sorting  program)  can 
be  performed  by  the  same  sort  sub¬ 
routine.  Just  pass  it  a  pointer  to  a 
more  complicated  comparison  func¬ 
tion.  The  comparison  function  used 
here  is  actually  several  subroutines 
J  defined  on  lines  172  —  320. 
Argvcmpf  )  (line  172f)  is  used  when 
no  command-line  switches  that  af¬ 
fect  the  sort  order  are  specified; 
qcmpf  )  (line  180f)  is  called  when 
command-line  switches  are  speci¬ 
fied.  Both  routines  are  passed  point¬ 
ers  to  string  pointers  (that  is,  the  ad¬ 
dresses  of  two  elements  of  Lines )  and 
both  call  a  workhorse  function  to  ac¬ 
tually  do  the  work.  Argvcmpf  )  calls 
I  strcmpf )  after  stripping  off  one  level 
of  indirection;  qcmpf  )  calls  qcmplf  ) 
(line  194f>,  which  in  turn  calls  qcmpZ 
(line  228f).  The  former  takes  care  of 


sort  fields,  whereas  the  latter  does 
the  actual  comparisons— doing 
things  such  as  skipping  white  space, 
mapping  uppercase  into  lowercase 
characters,  and  so  forth — as  specified 
by  command-line  switches. 

Once  the  lines  are  sorted,  they  are 
written  out  via  the  subroutine  out- 
tejctf )  (line  422f).  Outtetf  will  write  to 
standard  output  if  no  merge  files 
need  to  be  created;  otherwise  it  will 
write  to  a  temporary  file.  It  outputs 
the  entire  Lines  array  and  deletes  the 
memory  used  by  the  strings  them¬ 
selves  (as  compared  to  the  memory 
used  by  the  pointers  to  those  strings). 

As  the  last  step  in  the  sort,  all  the 
temporary  files  are  merged  together 
and  the  result  sent  to  standard  out¬ 
put.  The  actual  merging  is  done  in 
mergef )  (line  542f).  The  routine  open 
—mergefilesf  )  (line  455f )  creates  the 
heap,  opens  all  the  merge  files,  and 
reads  the  first  line  from  each  merge 
file  into  the  heap.  The  heap  is  then 
initialized  with  the  ssort  call  on  line 
546  (remember,  a  sorted  array  is  a  le¬ 
gal  heap).  The  while  loop  on  lines 
548  —  566  prints  the  smallest  element 
of  the  heap  (the  one  pointed  to  by 
*Heap )  and  then  reads  another  line 
from  the  appropriate  file.  If  there  are 
no  more  lines  to  read,  the  file  is 
closed  and  the  heap  is  made  smaller 
by  copying  the  entire  heap,  over¬ 
writing  the  first  entry,  and  decre¬ 
menting  nfiles.  Finally,  reheapf )  is 
called  to  put  the  new  entry  at  its 
proper  place  in  the  heap. 

Reheapf )  (line  507f)  reorders  the 
heap  in  a  manner  similar  to  a  binary- 
tree  search  (except  that  reheapf )  isn’t 
recursive).  It  compares  the  parent  el¬ 
ement  to  the  two  children  and,  if  the 
parent  is  smaller  than  a  child,  trans¬ 
poses  the  two  elements.  The  process 
is  then  repeated  with  the  newly 
transposed  child  used  as  the  parent 
node.  This  way  the  new  entry  perco¬ 
lates  to  its  proper  position  in  the 
heap.  Unlike  other  "percolating" 
strategies,  such  as  bubble  sort,  reheap 
is  efficient,  using  at  most  log2N  swaps, 
where  N  is  the  heap  size  rounded  up 
to  the  nearest  power  of  2. 

Limitations 

There  are  practical  limits  on  the 
amount  of  data  that  can  be  sorted.  Be¬ 
cause  each  merge  file  can  contain  at 
most  1,024  lines  and  18  merge  files 
are  permitted,  only  18,432  lines  can 


be  sorted  (split  up  into  as  many  input 
files  as  you  like).  Another  consider¬ 
ation  is  the  amount  of  space  available 
to  malloc  (about  58K  in  my  version  of 
sort).  Again,  because  this  number  lim¬ 
its  the  size  of  a  merge  file,  there  can 
be  no  more  than  58K  X  1,024  bytes  in 
the  combined  source  files  (about  a 
megabyte).  Of  course  this  last  num¬ 
ber  will  vary  a  little  depending  on 
the  line  lengths,  but  it’s  close.  In  prac-  J 
tice,  these  limits  haven’t  been  a  prob¬ 
lem,  but  you  may  need  to  go  to  a 
large-model  version  of  this  program 
(to  increase  the  amount  of  space 
available  from  malloc )  or  use  a  more 
sophisticated  merge  algorithm. 

Availability 

The  source  code  for  the  entire  pro¬ 
gram  this  month  (including  the  ge- 
targsf  ),  ssortf  j,  and  stoif  J  routines)  is 
available  on  CompuServe  in  the  DDJ 
Forum.  It’s  also  available  on  an  IBM 
PC-compatible  disk  for  $25  from  Soft¬ 
ware  Engineering  Consultants,  P.O. 
Box  5679,  Berkeley,  CA  94705.  The 
disk  comes  with  an  executable  ver¬ 
sion  and  source  code. 

Getargsf )  and  stoif )  were  original¬ 
ly  published  in  the  May  1985  C  Chest; 
ssortf )  was  published  in  the  March 
1986  C  Chest.  The  source  for  all  three 
routines  is  also  available  as  part  of  the 
/Util  utility  program  package.  It  costs 
$29.95  and  is  available  from  DDJ.  (See 
the  ad  in  the  DDJ  ad  catalog  in  this 
issue,  page  73.)  ddj 
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ARTICLES 


How  to  Fix 
Line  Glitches 

by  Joe  Marasco 


Most  telecom¬ 
munications 
users  are  ac¬ 
customed  to  getting  er¬ 
ror-free  messages 
when  moving  blocks 
of  data  during  file 
transfer  operations. 

This  situation  differs  greatly  from  normal  bulletin  board 
operations  or  from  using  a  remote  computer  interactive¬ 
ly.  In  these  situations,  most  people  don’t  even  flinch 
when  Ma  Bell  routes  their  call  over  barbed  wire,  and  the 
ubiquitous  ~  appears.  Glitches  on  the  line  are  almost  tak¬ 
en  for  granted,  and  rightly  so,  because  the  "error”  is  obvi¬ 
ous  and  immediately  discounted.  When  transferring 
files,  and  in  particular  binary  files,  however,  one  bit  error 
can  be  fatal,  and  more  important,  there  is  no  easy  way  to 
detect  it.  It  is  for  this  reason  that  error-checking  mecha¬ 
nisms  are  a  fact  of  life  in  the  telecommunications  world. 

The  most  common  forms  of  error  checking  are  the  sim¬ 
ple  parity  check  and  the  CRC  (cyclical  redundancy  code) 
check.  (  For  an  extensive  discussion  of  CRC  techniques,  see 
Terry  Ritter's  article,  "The  Great  CRC  Mystery, "  in  the  Feb¬ 
ruary  1986  issue  of  DDJ. — ed.)  In  these  schemes,  one  or 
more  bits  are  computed  when  each  block  is  sent;  the 
block  then  contains  the  message  bits  and  the  appended 
computed  bits.  The  receiver  recomputes  the  check  bit  or 
bits  using  the  message  bits  only  and  compares  the  result 
to  the  computed  bits  sent.  If  they  match,  an  ACK  is  sent  to 
the  transmitter.  If  there  is  no  match,  a  NAK  is  sent.  The 
transmitter  must  then  send  the  block  again.  CRCs  provide 
a  high  degree  of  robustness  for  a  small  overhead. 

In  some  applications,  however,  retransmissions  are 
prohibitively  expensive.  When  data  is  coming  from  very 
far  away — say,  from  Saturn — and  in  large  blocks,  the 
time  lag  to  resend  the  block  can  be  significant.  If  the  data 
has  a  real-time  aspect  to  it,  retransmission  can  in  effect  be 
worthless  because,  by  the  time  it  is  evident  that  old  data 
needs  to  be  resent,  new  data  may  already  be  in  the  queue. 
Forward  error  correction  addresses  these  problems. 


Joe  Marasco,  Billy  bob  Software,  P.O.  Boy.  363,  Belmont,  CA 
94002-0363. 

®  1986,  Billybob  Software.  All  rights  reserved. 


The  key  idea  is  that  by 
giving  up  some  of  the 
transmission  band¬ 
width  —  sacrificing 
more  message  bits  for 
overhead  bits— we  can 
not  only  detect  the 
presence  of  an  error 
but  also  correct  the  error  at  the  receiver.  The  basic  notion 
is  that  we  never  do  a  retransmission;  we  design  the  sys¬ 
tem  subject  to  a  known  noise  environment  such  that  we 
can  "fix”  all  "broken"  packets  when  we  get  them. 

Single-Bit  Errors 

Let's  demonstrate  this  principle  with  a  concrete  example 
using  the  simplest  of  these  codes,  the  Hamming  code.1 
The  Hamming  code  enables  you  not  only  to  detect  the 
presence  of  one  bit  error  in  a  block  but  also  to  locate  its 
position  and  hence  correct  it.  For  now  let’s  assume  we  are 
only  concerned  with  single-bit  errors. 

For  the  sake  of  example,  let  us  assume  that  we  are  going 
to  transmit  a  15-bit  block.  It  turns  out  (we’ll  show  you  how 
later)  that  it  takes  4  bits  of  “parity”  check  for  a  Hamming 
code  for  this  block  size,  so  we  have  only  11  bits  of  data  left 
for  the  "message.”  Although  this  is  a  high  overhead,  it  is 
purely  a  result  of  having  such  a  small  block;  the  situation 
improves  radically  as  we  go  to  larger  blocks.  We  use  a 
small  message  here  for  ease  of  exposition. 

Because  we  are  going  to  send  15  bits,  we  are  going  to 
have  to  localize  the  bit  error  to  one  of  15  positions.  If  we 
make  a  table  of  the  15  positions  and  their  binary  repre¬ 
sentations,  we  can  add  a  third  column  that  addresses  the 
question  of  which  one  of  the  four  parity  checks  should  be 
applied  to  each  bit.  (See  Table  1,  page  33.) 

Notice  that  the  entries  in  the  parity  check  column  are 
unique,  as  well  they  should  be.  All  we  have  done  really  is 
to  say  that  if  the  "one  bit”  is  in  error,  it  will  affect  all  the 
"positions”  that  have  a  "one  bit,”  and  so  on.  We  can  re¬ 
write  Table  1  by  noting  explicitly  which  bits  or  positions 
are  governed  by  each  parity  check  (Cl,  C2,  C3,  or  C4),  as 
shown  in  Table  2,  page  33. 

We're  now  almost  ready  to  encode  a  message!  The  trick 
is  to  reserve  bits  1,  2,  4,  and  8  for  the  check  bits,  leaving  3, 
5,  6,  7,  9, 10, 11, 12, 13, 14,  and  15  for  the  message  bits.  Let’s 
also  decide  that  the  total  number  of  bits  governed  by  any 


Forward  error  correction  deals 
with  data-transmission  errors  by 
correcting  them  as  the  data  are 
received. 
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check  must  be  even.  Here’s  an  arbitrary  message: 

1  2  3  4567  8  9  10  11  12  13  14  15 
C1C2  1C3  011C4  0  1  1  0  1  0  1 

Now  let's  compute  Cl,  which  is  governed  by  the  parity 
of  the  bits  shown  in  Table  2.  Looking  at  the  odd  bits  from  3 
to  15,  we  count  five  Is,  so  for  the  parity  to  be  even,  Cl 
must  be  a  1.  Our  message  now  looks  like  this: 

1  23  4567  8  9  10  11  12  13  14  15 
1C2  1C3  011C4  0  1  1  0  1  0  1 

To  compute  C2,  we  do  the  same  thing  for  the  bits  listed 
under  C2  in  Table  2.  Looking  at  all  the  bits  except  for  2, 
which  we  are  trying  to  find,  we  count  six  Is,  which  is 
even.  So  C2  must  be  a  0.  This  yields: 

1  2  3  4  5  6  7  8  9  10  11  12  13  14  15 

101C3  011C4  0  1  1  0  1  0  1 

You  can  do  C3  and  C4  by  yourself.  The  final  block,  con¬ 
taining  the  message  and  check  bits,  should  look  like  this: 

1  2  3  4  5  6  7  8  9  10  11  12  13  14  15 

101001100  1  1  0  1  0  1 

So  the  message  sent  would  be  "101001100110101.” 

What  happens  at  the  receiver?  Clearly,  if  the  message  is 
received  with  no  errors,  each  parity  check  will  pass,  and, 
by  definition,  we  ascribe  a  0  to  a  good  parity  check.  When 
we  make  a  number  out  of  the  four  binary  digits  from  the 
parity  check,  we  get  0000  for  the  location  of  the  error. 
This  value  is  called  the  syndrome;  a  zero  value  for  the 
syndrome  means  there  were  no  errors. 

Now  let  us  suppose  that  an  error  is  made  in  transmis¬ 
sion.  Suppose  that  the  error  occurs  in  the  fifth  bit  sent. 
Our  table  then  looks  like  the  one  shown  in  Table  3,  right. 
Applying  the  parity  checks  as  given  in  Table  3,  one  by 
one,  we  have  the  table  shown  in  Table  4,  right.  And  when 
we  construct  the  syndrome  (C4C3C2C1),  we  get 

0101  —  >  5  —  >  error  is  in  the  fifth  bit 

So  now  we  know  that  all  we  have  to  do  to  correct  the 
message  is  to  invert  the  fifth  bit,  making  it  a  0  instead  of  a 
1.  The  original  message  is  recovered. 

There  is  something  very  nice  about  the  Hamming  code 
and  all  forward  error  correction  codes  in  general.  Note 
that  once  the  encoding  is  done,  Ihere  is  a  total  equality 
between  the  original  message  bits  and  the  computed 
check  bits.  It  doesn't  matter  at  all  if  during  the  transmis¬ 
sion  a  data  bit  or  a  check  bit  gets  squashed — they  are  all 
on  an  equal  footing.  If  a  check  bit  gets  reversed,  it  will  be 
corrected;  in  effect  the  original  message  gets  through  OK 
and  doesn’t  need  "correcting.” 

Ttvo-Bit  Errors  and  More 

What  happens  with  this  simple  code  when  two  bit  errors 
occur?  Try  it!  You'll  find  that  2-bit  errors  in  the  channel 
will  cause  the  decoder  to  "miscorrect,”  introducing  yet  a 
third  bit  in  error.  This  is  indeed  a  sad  state  of  affairs. 


At  the  cost  of  one  additional  check  bit  we  can  improve 
the  situation,  however.  Let  the  zeroth  bit  be  the  total  pari¬ 
ty  after  the  other  15  bits  have  been  encoded.  Now  we 
have  an  interesting  situation.  If  the  syndrome  is  zero  and 
the  parity  bit  is  OK,  we  have  a  good  message.  If  we  have 
one  bit  error  in  the  15  bits,  we  have  a  nonzero  syndrome 
and  a  bad  parity  bit;  we  can  locate  the  bad  bit  as  before.  If 
just  the  parity  bit  itself  gets  reversed,  the  syndrome  will 
be  zero,  so  we'll  know  it's  just  the  parity  bit.  Finally,  and 
most  important,  if  there  are  2-bit  errors  anywhere,  we 
will  get  a  nonzero  syndrome  and  a  good  parity  bit.  That  is 
the  unmistakable  signature  of  a  2-bit  error.  So  what  we 
now  have  is  much  better:  a  code  that  corrects  any  single¬ 
bit  error  and  detects  all  2-bit  errors. 

To  let  you  try  this  out,  I've  written  a  blatant  hack.  (See 
Listing  One,  page  84.)  You  input  an  11-bit  message,  and  the 
program  computes  and  displays  the  completed  16-bit 
block  that  would  be  transmitted.  You  can  then  type  in  the 
"received”  message,  corrupting  one  or  more  of  the  bits, 
and  the  decoder  will  tell  you  which  bit  is  in  error  and 
display  the  corrected  message. 

We’ve  just  scratched  the  surface.  Hamming  codes  are 
the  first  step  in  doing  forward  error  correction.  You've 


Position 

Binary  Representation 

Parity  Check 

1 

000  1 

1 

2 

0010 

2 

3 

001  1 

1,2 

4 

0  100 

3 

5 

0101 

1,3 

6 

0110 

2,3 

7 

0  111 

1,2,3 

8 

1000 

4 

9 

1  001 

1,4 

10 

1010 

2,4 

11 

10  11 

1,2,4 

12 

1  1  00 

3,4 

13 

1101 

1,3,4 

14 

1110 

2.3,4 

15 

1111 

1,2,  3,4 

Table  1:  The  bit  position  itself  tells  which  parity  checks  to  apply. 


Cl  ->  1,3,  5, 7, 9, 11, 13, 15 
C2  — >  2,  3,  6,7,10,11,14,15 
C3— >4,5,  6,7,12,13,14,15 
C4  ->  8,9, 10, 11, 12, 13, 14, 15 


Table  2:  Each  parity  check  affects  a  unique  set  of  bit  positions. 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

1 

0 

1 

0 

0 

E 

1 

1 

0 

0 

1 

1 

0 

1 

0 

1 

xmit 

1 

0 

1 

0 

1 

1 

1 

0 

0 

1 

1 

0 

1 

0 

1 

recvd 

Table  3:  Here  a  transmission  error  occurs  at  bit  position  5. 


Cl  — >  1, 3,  5,  7,  9, 11, 13, 15 ->  fails ->  1 
C2  —  >2,  3,  6,  7, 10, 11, 14, 15  — >  passes— >  0 
C3  —  >  4,  5,  6,  7, 12, 13, 14, 15  —>  fails  —  >  1 
C4  ->  8,  9, 10, 11, 12, 13, 14, 15  ->  passes->  0 


Table  4:  The  parity  checks  locate  the  error  (0101  =  5  in  binary). 
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(continued  from  page  33) 


probably  deduced  by  now  that  you  can  correct  2m  —  1  bits 
of  total  information  with  m  bits  of  parity  check  (subject  to 
only  1-bit  errors,  of  course!).  So  with  10  bits  set  aside  to  do 
the  checks,  you  have  1023  —  10,  or  1013  bits  of  informa¬ 
tion  sent.  Even  if  you  include  the  additional  parity  bit  for 
2-bit  errors,  this  represents  an  overhead  of  about  1  per¬ 
cent,  which  is  not  bad  when  you  consider  that  you  will 
correct  all  1-bit  errors  at  the  receiver  and  detect  blocks 
with  2-bit  errors. 

The  real  power  of  forward  error  correction  comes  from 
being  able  to  do  better,  however.  More  complicated  codes 
can  correct  not  only  single-bit  errors  but  also  multiple-bit 
errors.  And,  because  for  some  channels  the  predominant 
mode  is  not  single-bit  errors  but  errors  that  come  in  bunch¬ 
es,  there  are  codes  that  are  better  suited  to  correcting  burst 
errors.  There  are  also  codes  that  handle  both  single-bit 
errors  and  multiple  bursts.  If  you  are  interested,  you  can 
learn  more  by  looking  up  the  BCH  and  Reed  Solomon  codes 
in  the  references  at  the  end  of  this  article. 

One  Last  Note 

Communications  is  often  thought  of  as  getting  informa¬ 
tion  from  here  to  there.  Another  way  of  looking  at  it  is 
getting  information  from  then  to  now — that  is,  all  these 
forward  error  correction  schemes  can  be  applied  to  disk 
writing  and  reading.  When  you  fetch  a  block  from  a  disk, 


good  disk  controller  software  can  do  an  FEC  maneuver 
and  fix  up  the  block  if  it  was  written  or  read  incorrectly. 

Use  of  these  schemes  enables  the  cost  of  disk  hardware 
to  come  down  because  lower  precision  mechanical  assem¬ 
blies  can  be  used;  systems  can  be  designed  to  have  higher 
rates  of  read/write  errors  if  we  know  we  can  correct  for 
them.  Perhaps  the  most  stunning  demonstration  of  this 
phenomenon  is  the  audio  compact  disc  player.  The  digital 
music  that  is  retrieved  is  encoded  with  a  sophisticated 
Reed  Solomon  forward  error  correction  code  that  enables 
magnificent  sound  with  less  than  perfect  media.  That  you 
can  buy  one  of  these  at  less  than  $200  is  a  remarkable 
example  of  intelligent  hardware  and  software  integration. 

Note 

1.  R.  W.  Hamming,  Coding  and  Information  Theory  (Engle¬ 
wood  Cliffs,  N.J.:  Prentice-Hall,  1980). 
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The  CompuServe 
B  Protocol: 

A  Better  Way  to  Send  Files 


Talking  to  the  Big  Boys 

f  you’ve  tried  to  use  a  commer¬ 
cial  telecommunications  pack¬ 
age  to  upload  or  download  files 
to  or  from  a  mainframe  computer, 
you  may  have  experienced  a  few  dif¬ 
ficulties.  The  most  popular  file-trans¬ 
fer  protocols  all  have  problems  deal¬ 
ing  with  the  "big  boys" — XMODEM, 
for  example,  has  a  tendency  to  "time 
out”  when  the  host  system  experi¬ 
ences  a  momentary  delay  in  trans¬ 
mission.  Other  problems  also  get  in 
the  way.  Many  protocols  require  a 
file  length  that  is  an  exact  multiple  of 
some  block  size.  We've  run  into  these 
problems  here  at  DDJ  while  upload¬ 
ing  listings  for  the  DDJ  Forum  on 
CompuServe. 

In  1980,  a  programmer  at  Compu¬ 
Serve  wrote  one  of  the  first  programs 
that  tried  to  fix  some  of  these  prob¬ 
lems,  calling  it  the  CompuServe  A 
protocol.  It  had  numerous  glitches 
and  design  problems.  The  B  protocol, 
designed  about  the  same  time  as 
Ward  Christensen  designed  XMODEM, 
is  the  next  generation.  For  a  while 
CompuServe  afficionados  wanted  to 
keep  both  the  A  and  B  protocols  pro¬ 
prietary,  but  CompuServe  B  is  now  in 
the  public  domain,  supported  by 
CompuServe.  Because  it  was  de¬ 
signed  with  the  idea  of  communicat¬ 
ing  between  micros  and  mainframes 
over  packet-switching  networks,  it 
incorporates  several  improvements 
that  largely  eliminate  the  problems 
of  the  other  protocols.  With  the  B 
protocol,  unlike  the  others,  you  let 
the  mainframe  do  all  the  work. 

With  the  B  protocol,  the  host  (usual¬ 
ly  a  mainframe)  activates  the  proto¬ 
col  in  your  micro  automatically,  as 
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soon  as  you  have  invoked  the  proto¬ 
col  through  your  commands  to  the 
host.  You  must  have  a  terminal  pro¬ 
gram  running  in  your  local  system 
that  recognizes  the  host's  initial  B 
protocol  query  and  automatically  in¬ 
vokes  its  own  “slave”  program  to  ac¬ 
cept  or  supply  the  data.  The  host  also 
has  the  ability  to  interrogate  your  mi¬ 
cro  to  find  out  what  features  your 
program  supports.  B  protocol  sup¬ 
ports  error-corrected  file  transfer  be¬ 
tween  computers,  chiefly  text  file 
transfer  between  microcomputers 
and  mainframes  and  binary  file 
transfer  between  microcomputers 
with  possible  intermediate  storage 
on  mainframes.  B  protocol  can  trans¬ 
fer  files  of  arbitrary  size  and  supports 
character  mapping  on  text  transfers. 

The  program  we  describe  in  this 
article  is  a  dumb-terminal  emulator 
with  just  enough  intelligence  to  rec¬ 
ognize  when  the  host  is  about  to 
transfer  a  file  up  or  down.  It  re¬ 
sponds  to  the  host’s  queries  and  im¬ 
plements  the  protocol  transparently 
to  the  terminal  user.  BP.C  (Listing  One, 
page  90),  the  vanilla  version  de¬ 
scribed  and  supplied  here  in  C  source 
form,  is  not  machine  specific  and 
should  be  installable  in  most  existing 
terminal  programs,  provided  you 


have  access  to  the  source  code  or  in¬ 
formation  on  how  to  connect  new 
device  drivers.  We've  also  included 
some  machine-language  and  C  mod¬ 
ules  for  the  interface  routines  that 
will  work  on  most  MS-DOS  machines. 

Hour  it  Works 

To  transfer  a  file  using  the  B  protocol, 
first  you  invoke  it  in  the  host  system 
(usually  the  mainframe  you’re  call¬ 
ing)  by  sending  the  proper  com¬ 
mands  to  it  manually  through  your 
terminal  interface.  On  CompuServe 
this  would  mean  selecting  the  proper 
choice  from  the  menu.  Then  the  host 
system  sends  the  ASCII  ENQ,  character, 
to  which  your  terminal  program  re¬ 
sponds  with  DIE  0  (data  link  Escape 
followed  by  an  ASCII  0).  The  host  is 
acting  as  the  master  in  this  exchange 
(even  though  the  protocol  was  in¬ 
voked  by  you)  because  it  is  invoking 
the  slave  process  in  your  micro. 

Next,  the  host  usually  sends  the  se¬ 
quence  ESC  1  (Escape  followed  by  AS¬ 
CII  /).  Upon  receipt,  the  microcomput¬ 
er  terminal  software  should  transmit 
an  identification  string  to  the  request¬ 
ing  computer.  The  identification 
string  consists  of  the  pound  sign  (#), 
followed  by  a  three-letter,  alphanu¬ 
meric,  product  name  code  (in  this 
case  the  code  is  DTE,  meaning  a  gen¬ 
eral  terminal  device),  a  version  num¬ 
ber  in  decimal,  a  comma  (,),  and  a 
comma-separated  list  of  feature 
codes.  The  feature  code  list  details 
the  features  supported  by  the  partic¬ 
ular  terminal  program.  The  codes 
that  denote  a  B  protocol  driver  are  PB 
(which  refers  to  protocol  B)  and  DT 
(disk  transfer).  Additional  feature 
codes  describe  other  capabilities,  in- 
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eluding  terminal  type  and  graphics 
support. 

To  start  the  transfer,  the  host  sends 
a  DLE  followed  by  ASCII  B.  At  this 
point,  the  main  terminal  loop  should 
[  call  Transfer— File  (a  BP.C  routine)  to 
complete  the  protocol  sequence, 
j  Transfer— File  returns  a  Boolean  val¬ 
ue  indicating  the  success/failure  of 
the  transfer. 

Routines  You  Provide 

In  order  to  use  the  program  supplied 
here,  you  must  provide  some  rou¬ 
tines  for  your  specific  hardware. 
You’ll  need  four  routines  to  control 
;  your  modem  or  serial  port.  These  are 
|  used  by  BP.C  to  open,  read,  write,  and 
close  your  modem  port.  You'll  need  a 
j  couple  of  routines  to  deal  with  your 
j  local  keyboard  and  screen.  The  pro- 
|  gram  will  call  them  to  read  a  charac¬ 
ter  from  your  keyboard,  to  write  a 
character  to  your  screen,  and  to  find 
out  if  you  have  decided  to  abort  the 
program  (for  example,  by  pressing 
the  Esc  key).  You’ll  need  to  supply 
two  timer  routines:  one  that  sets  a 
|  time  out  of  a  certain  number  of  sec¬ 
onds  and  another  that  tests  whether 
the  time  is  up.  If  you  don't  have  a 
hardware  timer,  you  can  simulate 
the  effect  simply  by  decrementing  a 
count  every  time  the  time-out  rou¬ 
tine  is  called.  Finally,  you'll  need  a  set 
of  file-manipulation  routines  whose 
format  will  be  largely  dependent  on 
exactly  what  operating  system 
|  you’re  running  under  and  what  li¬ 
brary  routines  you're  using. 

Modem  Interface  Routines 

|  Open_Modem — is  required  to  initial¬ 
ize  the  modem  port  to  support  8- 
bit  data  without  auto  XON/XOFF 
recognition  before  BP.C  is  called. 
No  parity  checking  should  be 
done.  BP.C  does  not  depend  on 
baud  rate  and  stop-bit  settings. 
Note:  Depending  on  the  particular 
machine,  data  may  be  lost  when 
the  modem  port  is  reprogrammed 
for  no  auto  XON/XOFF  recognition. 
This  data  loss  usually  affects  only 
the  first  block,  which  the  slave 
software  can  request  to  be  retrans- 
mited  by  sending  a  NAK. 

Write— Modem — is  called  by  BP.C.  Its 
argument  is  an  8-bit  character  to 
be  transmitted. 

Read— Modem — is  called  by  BP.C  and 
returns  an  integer  containing  an  8- 


bit  character  or  —1.  The  latter  is  j 
used  to  indicate  that  no  character 
has  been  received  over  the  mo¬ 
dem  port. 

Close-Modem — is  required  to  shut 
down  the  modem  port  outside 
BP.C  and  to  restore  the  machine  to 
its  original  state.  Certain  changes 
made  in  Open— Modem,  such  as  re¬ 
programming  interrupt  vectors, 
must  be  undone  before  you  exit 
from  the  program. 

User  Input/Output  Routines 

Read— Keyboard  (from  KEYBOARD 
.ASM,  Listing  Two,  page  99) — re¬ 
turns  an  integer  containing  either 
ASCII-key  codes,  function-key 
codes,  or  —  1  for  no  key  pressed. 

WantsJTo— Abort  (from  DTE.C,  List¬ 
ing  Three,  page  100) — is  called  by 
BP.C  to  detect  if  the  user  has  re¬ 
quested  abort.  The  routine  returns 
a  Boolean  true  if  abort  has  been  in¬ 
dicated.  Once  the  Wants 
—To— Abort  status  has  been  read, 
the  status  is  reset.  You  may  notice 
some  delay  before  the  abort  re¬ 
quest  is  acknowledged.  The  delay 
is  because  of  the  need  to  synchron¬ 
ize  the  abort  packet  with  the  cur¬ 
rent  protocol  packet. 

Put_Char  (from  SCREEN.ASM,  Listing 
Four,  page  104) — accepts  an  inte¬ 
ger  containing  ASCII  character 
codes.  The  characters  are  dis¬ 
played  to  the  user. 

Timer  Routines 

These  are  routines  from  TIMER. ASM, 
Listing  Five,  next  month. 

Start— Timer — is  passed  an  integer  ar¬ 
gument  of  the  number  of  seconds 
to  begin  counting  down. 

Timer-Expired — returns  Boolean 
true  if  the  number  of  seconds  set 
with  Start— Timer  has  elapsed.  If 
you  don’t  have  a  real-time  clock  or 
timer,  Start— Timer  should  set  a  de¬ 
lay  counter  that  Timer— Expired 
decrements  each  time  it  is  called,  | 
so  that  the  number  of  calls  to  Ti¬ 
mer— E spired  controls  time  out.  Ti¬ 
mer-Expired  is  called  frequently 
during  time-out  detection. 

Delay  (from  DELAY.C,  Listing  Six,  next 
month) — is  called  with  an  integer 
argument  for  the  number  of  milli¬ 
seconds  to  wait  before  returning 
to  the  calling  routine.  The  only 
purpose  of  Delay  is  to  support  a 
wait  acknowledgment  request 


from  the  other  computer.  The 
wait  acknowledgment  can  be  1 
used  to  request  delay  time  needed  | 
during  intensive  processing. 

File  Input/Output  Routines 

These  are  routines  from  FILEIO.ASM,  j 
Listing  Seven,  next  month.  These  file  | 
primitives  are  used  to  create,  read,  ] 
and  write  both  text  and  binary  files. 
The  data  should  be  transferred  un¬ 
modified  (except  in  character-map)-  | 
ping  mode).  The  file-access  mode 
should  allow  access  to  each  byte  in  the  ! 
file,  often  called  "binary”  or  "raw”  j 
mode.  The  actual  arguments  of  each  | 
of  the  file  input/output  routines  will  i 
need  to  be  those  supported  by  the  par¬ 
ticular  library  you  are  using. 

Create— File — attempts  to  create  a  file 
with  the  name  supplied  and  re-  j 
turns  a  negative-result  code  (for 
errors)  or  a  file  handle. 

Open— File — opens  the  file,  returning  j 
a  negative  error  code  or  the  file 
handle. 

Read— File — reads  the  specified  num¬ 
ber  of  by  tes  from  the  open  file  into 
the  specified  buffer,  returning  a 
negative  error  code  or  the  number 
of  bytes  actually  read. 

Write— File — writes  the  specified 
number  of  bytes  from  the  open 
file  into  the  specified  buffer,  re¬ 
turning  a  negative  error  code  or 
the  number  of  bytes  actually  ' 
written. 

Close— File — closes  the  file,  returning  j 
a  negative  error  code  or  0. 

The  B  protocol  is  not  perfect,  but  j 
for  this  application,  it’s  clearly  an  im¬ 
provement  over  the  previous  micro- 
to-micro  protocols.  Currently,  only 
CompuServe  supports  the  B  protocol. 
The  master  program  will  eventually 
be  available  in  the  public  domain  as  is 
the  slave  program  presented  here. 
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The  SwyftCard: 

Jef  Raskin’s  New  User 

Interface 


SwyftCard 

Information  Appliance  Inc.,  1014  Ham¬ 
ilton  Ct.,  Menlo  Park,  CA  94025,  (415) 
328-5160;  $89.95 

he  SwyftCard  from  Informa¬ 
tion  Appliance  is  a  new  per¬ 
sonal  computer  environment 
for  the  Apple  lie  and  lie.  It  provides  a 
word  processor  from  which  you  can 
easily  perform  other  tasks,  such  as 
disk  file  access,  calculations  via  BASIC, 
printing,  and  communications  with  a 
modem.  The  environment  is  note¬ 
worthy  because  it  is  philosophically 
at  odds  with  the  popular  interface 
made  of  icons,  windows,  and  mouse 
that  is  used  on  the  Macintosh  and 
other  computer  systems.  Significant¬ 
ly,  SwyftCard 's  designer  is  Jef  Raskin, 
one  of  the  initiators  of  the  Macintosh 
project  at  Apple  Computer. 

I  tested  SwyftCard  on  an  Apple  He, 
but  as  this  issue  goes  to  press,  Infor¬ 
mation  Appliance  has  announced  a 
version  for  the  lie  also.  To  use  Swyft¬ 
Card  on  a  lie,  you  need  an  80-column 
card,  a  video  monitor  suitable  for  80- 
column  display,  and  a  disk  drive.  The 
SwyftCard  supports  a  wide  variety  of 
printers;  several  require  no  setup, 
and  many  can  be  installed  by  using 
the  Calc  command. 

SwyftCard  consists  of  a  three-chip 
board  that  plugs  into  slot  3,  a  set  of 
stick-on  labels  for  several  keys,  a  tuto¬ 
rial  disk,  and  an  excellent  manual. 
The  tutorial  will  help  you  get  started 
with  SwyftCard  by  guiding  you 
through  a  series  of  short  lessons  on 
the  use  of  its  features. 

The  word  processor  is  the  heart  of 
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the  SwyftCard  system.  It  has  been 
carefully  designed  to  achieve  several 
goals: 

•  Speed:  For  text  processing  and  flop¬ 
py-disk  access,  SwyftCard  is  signifi¬ 
cantly  faster  than  more  expensive 
systems.  All  the  text  is  in  RAM,  so  disk 
access  time  doesn’t  slow  SwyftCard 
down.  Half  the  system  is  implement¬ 
ed  in  tokenized  Forth  and  half  in  as¬ 
sembly  language,  resulting  in  fast  op¬ 
eration.  Each  SwyftCard  file  occupies 
a  single  floppy  disk  and  can  expand 
to  40,000  characters,  or  roughly  14 
pages  of  single-spaced  text.  Disk  oper¬ 
ations  take  less  than  seven  seconds  in 
all  cases. 

•  Simplicity:  There  are  only  ten  basic 
commands:  Insert,  Delete,  Print, 
Leap,  Creep,  Page,  Calc,  Print,  Send, 
and  Disk.  The  last  three  are  for  input/ 
output  and  are  not  used  as  frequently 
as  the  others.  Most  commands  are  im¬ 
plemented  with  one  or  two  key¬ 
strokes  using  a  few  dual-purpose, 
specially  labeled,  SwyftCard  func¬ 
tion  keys.  After  a  little  practice,  users 
learn  the  commands,  and  text  pro¬ 
cessing  becomes  fast  and  easy. 

•  Optional  environment:  You  can 
load  an  ordinary  Apple  disk,  and  the 


operating  system  works  normally,  as 
SwyftCard  hides  behind  the  scenes 
until  you  need  it. 

How  SwyftCard  Works 

Leaping 

SwyftCard  allows  you  to  move 
through  text  using  two  Leap  keys: 
the  open-apple  and  closed-apple 
keys  on  either  side  of  the  space  bar. 
To  make  learning  easy,  a  set  of  stick- 
on  labels  is  provided  to  indicate 
which  keys  are  used  for  special 
SwyftCard  functions.  Leaping  means 
moving  from  one  place  in  the  text  to 
another  immediately. 

Suppose  the  phrase  The  number  is 
less  than  the  numerator  appears  be¬ 
tween  the  cursor  and  the  end  of  the 
file  and  you  want  to  locate  the  cursor 
on  the  n  in  numerator.  Press  the  right 
Leap  key  as  you  type  "n  —  u  —  m  —  e" 
to  create  a  search  pattern.  After  you 
have  typed  the  “n,”  the  cursor  leaps 
to  the  next  instance  of  n  in  the  file, 
after  the  u,  to  the  next  instance  of  nu, 
and  so  on  until  it  stops  on  the  n  in  the 
word  numerator. 

If  this  isn't  the  instance  of  the  word 
you  want,  press  the  Leap  key,  and  the 
Leap  Again  key  (Tab),  to  find  the  next 
occurrence  of  the  letters.  Leap  Again 
auto-repeats;  if  you  hold  it  down  for 
more  than  half  a  second,  the  cursor 
will  move  rapidly  from  one  instance 
of  the  pattern  to  the  next.  If  the  cursor 
arrives  at  the  end  of  the  file,  it  wraps 
back  to  the  beginning.  It  will  continue 
its  forward  direction  until  the  Leap 
keys  are  released. 

If  you  wish  to  leap  to  a  point  be¬ 
tween  the  cursor  and  the  beginning 
of  the  file,  use  the  same  procedure 
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with  the  left  Leap  key,  and  the  search 
will  take  place  in  the  reverse  direc¬ 
tion. 

Lowercase  letters  in  a  leap  pattern 
match  both  uppercase  and  lowercase 
letters  in  the  text.  Uppercase  letters  in 
the  pattern  match  only  uppercase  in 
the  text.  You  can  leap  from  word  to 
i  word  (press  Leap  and  the  space  bar), 
paragraph  to  paragraph  (press  Leap 
and  Return),  or  page  to  page  (press 
Leap  and  the  Page  key  [Esc] ). 

Creeping 

Moving  the  cursor  over  just  a  few 
characters  is  called  creeping  in  the 
SwyftCard  manual.  To  creep,  press 
and  release  the  right  Leap  key,  and 
the  cursor  moves  a  character  to  the 
right.  To  creep  in  reverse,  press  the 
left  Leap  key. 

Deleting 

Deletes  can  also  be  done  to  the  left  or 
right  of  the  cursor.  While  you  are  typ¬ 
ing,  if  you  press  the  Del  key,  the  char¬ 
acter  to  the  left  is  erased  as  with  the 
backspace  key  on  a  typewriter.  After 
you  leap  or  creep  to  a  new  place  in 
the  file,  characters  to  the  right  of  the 
cursor  are  deleted.  The  appearance  of 
the  cursor  itself  indicates  which  de¬ 
lete  is  operative.  A  narrow  cursor  is 
one  character  wide  and  appears 
when  right  delete  is  in  effect;  the 
wide  cursor  is  two  characters  across 
with  the  cursor  and  the  reverse-video 
character  split. 

Highlighting 

Another  useful  SwyftCard  feature  is 
the  highlighting  of  text.  Highlighted 
text  can  be  deleted,  saved  in  a  buffer 
for  later  insertion,  printed,  or  tele¬ 
communicated.  Highlighting  takes 
place  by  pressing  and  releasing  a  Leap 
key,  moving  the  cursor,  and  then 
pressing  both  Leap  keys  simulta¬ 
neously.  Any  amount  of  text  can  be 
highlighted,  from  two  characters  to 
the  entire  document.  Pressing  Delete 
will  remove  all  highlighted  text  from 
the  screen  and  place  it  in  a  buffer.  To 
restore  the  text,  locate  the  cursor 
where  you  want  the  text  and  press 
Insert  (Control-A).  The  deleted  text  re¬ 
mains  in  the  buffer  until  you  high¬ 
light  and  delete  other  text. 

The  Disk  Command 

You  use  the  Disk  key  to  read  from  or 
write  a  file  to  the  disk.  SwyftCard's 


I  method  of  handling  disk  files  auto- 
i  matically  takes  care  of  whether  read¬ 
ing  or  writing  is  required.  Let’s  say 
you  want  to  save  some  text.  Put  a  flop¬ 
py  disk  in  the  drive,  and  press  the  Disk 
key.  SwyftCard  notes  if  the  disk  is 
S  empty  and  that  text  is  in  RAM  and  de¬ 
duces  that  a  disk  write  is  needed. 
When  text  has  been  saved,  the  cursor 
blinks  rapidly  to  indicate  that  RAM 
and  disk  contents  are  identical. 

On  the  other  hand,  if  you  are  in  the 
middle  of  writing  and  try  to  load  a 
new  file  from  a  different  floppy, 
SwyftCard  will  observe  that  some 
changes  in  RAM  have  not  been  saved 
and  refuse  to  overwrite.  A  beep 
serves  to  remind  you  that  the  disk  for 
the  old  file  should  be  inserted  in  the 
drive  to  save  changes.  If  you  really  do 
not  want  to  save  your  changes,  the 
procedure  is  to  delete  the  text.  These 
are  examples  of  a  well-planned  user 
interface,  designed  to  save  the  user 
from  accidental,  catastrophic  errors, 
which  all  computer  users  have  expe¬ 
rienced  at  some  time.  Another  exam- 
|  pie  of  this  care  is  a  SwyftCard  com- 
!  mand  that  will  make  a  disk  look 
,  blank,  in  effect  destroying  anything 
)  on  it  and  allowing  you  to  write  to  it. 

|  Because  this  command  can  affect 
your  data  and  is  thus  dangerous,  it 
does  not  use  the  Disk  key  and  is  diffi- 
j  cult  to  execute  accidentally. 

The  Calc  Command 

!  The  Calc  command  causes  a  BASIC 
statement  to  be  executed  in  the  file; 
for  example,  if  you  type  "?34  +  78" 
and  then  highlight  it  and  press  the 
Calc  key,  the  answer  112  will  appear 
j  in  place  of  the  BASIC  statement  in  your 
text.  More  complex  executions  are 
also  possible.  If  you  type 

10  FOR  I  =  1  TO  31 
20  PRINT  “JANUARY”;  I 
30  NEXT  I 
RUN 

then  highlight  this  program  and  press 
the  Calc  key,  the  following  calendar 
for  January  will  be  placed  in  your  file 
where  the  program  was: 

JANUARY  1 
JANUARY  2 
JANUARY  3 


JANUARY  30 
JANUARY  31 


Almost  all  BASIC  commands  will 
work,  but  the  size  of  the  BASIC  pro¬ 
gram  is  limited  to  900  bytes  in  the 
compacted  internal  form.  Some  uses 
of  BASIC  are  dangerous — CALL,  PEEK, 
and  POKE  can  zap  your  file  if  used  in¬ 
correctly  or  with  values  that  interfere 
with  the  SwyftCard. 

Awkward  Moments 

When  the  SwyftCard  has  used  all 
available  RAM  memory,  it  will  beep 
each  time  you  press  a  key.  To  create 
room,  execute  at  least  two  deletions. 
One  is  insufficient  because  the  delete 
buffer  continues  to  take  up  the  same 
amount  of  RAM.  At  this  point  it  is 
clearly  advisable  to  save  the  file,  insert 
a  new  disk,  delete  part  of  the  text,  and 
continue.  This  is  one  of  the  few  awk¬ 
ward  operations  of  SwyftCard.  An  im¬ 
provement  would  be  some  sort  of 
warning  when  all  but  50  or  100  bytes  | 
of  RAM  had  been  used  to  allow  for  a 
more  graceful  conclusion  of  an  edit¬ 
ing  session. 

The  SwyftCard  approach  of  allow¬ 
ing  each  disk  to  hold  one  file  is  accept- 
|  able  for  a  machine  such  as  the  Apple 
II,  but  as  memory  and  hard  disks  con¬ 
tinue  to  drop  in  price,  the  SwyftCard 
environment  will  have  to  adapt  to 
machines  with  greater  internal  and 
external  storage  capabilities.  These 
implementations  will  require  a  file 
management  system  and  some 
scheme  for  mapping  files  into  a  range 
of  RAM  memory  sizes. 

These  minor  complaints  are  far  less 
important  than  the  many  impressive 
characteristics  of  SwyftCard,  includ¬ 
ing  speed,  ease  of  use,  and  diversity. 

|  Overall,  SwyftCard  offers  a  strikingly 
innovative  user  interface  that  de¬ 
serves  the  attention  of  users  and  soft¬ 
ware  developers  interested  in  ad¬ 
vancing  the  cause  of  usable 
computers. 
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UStinQ  Seventeen  (continued  from  May) 

IMPLEMENTATION  MODULE  CodoGenorator ; 

Instructions  (OpCode,  OpLoc,  Op,  AddrModeA,  AddrModeB); 

(*  Uses  information  supplied  by  Parser,  OperationCodes,  *) 

(*  and  SyntaxAnalyzer  to  produce  the  object  code.  *) 

AddrBoundW  (AddrCnt); 

FROM  Strings  IMPORT 

Src.Loc  SrcLoc;  Dest.Loc  DestLoc; 

GetOperand  (SrcOp,  Src)  ; 

Length,  CompareStr; 

GetOperand  (DestOp,  Dest) ; 

FROM  SymbolTable  IMPORT 

FillSymTab,  Reads ym Tab; 

InstSize  2;  (*  minimum  size  of  instruction  *) 

IF  Brnch  IN  AddrModeA  THEN 

FRCM  Parser  IMPORT 

IF  Size  #  Byte  THEN 

INC  (InstSize,  2); 

TOKEN,  OPERAND,  OpLoc,  SrcLoc,  DestLoc; 

END; 

FRCM  LongNumbers  IMPORT 

ELSIF  DecBr  IN  AddrModeA  THEN 

INC  (InstSize,  2); 

LCNG,  LongAdd,  LongSub,  Lor.gi  ic,  LongDec, 

ELSE 

LongClear,  CardToLong,  LongTcJard,  LongToInt, 

IF  (Op  -  JMP)  OR  (Op  -  JSR)  THEN  (*  Allows  for  '  JMP .  S  ’  ») 

LongCompare,  AddrBoundW,  AddrBoundL; 

IF  (Size  -  Byte)  AND  (Src. Mode  -  AbsL)  THEN 

FRCM  OperationCodes  IMPORT 

Src. Mode  AbsW; 

END; 

ModeTypeA,  ModeTypeB,  ModeA,  ModeB,  Instructions; 

END; 

FRCM  ErrorX68  IMPORT 

TempC  GetlnstModeSize  (Src. Mode,  Size,  InstSize); 

ErrorType,  Error; 

TempC  GetlnstModeSize  (Dest. Mode,  Size,  InstSize); 

FRCM  SyntaxAnalyzer  IMPORT 

OpMode,  Xtype,  SizeType,  OpConfig,  Src,  Dest, 

END; 

IF  (Src. Mode  -  Imm)  AND 

Size,  Op,  AddrModeA,  AddrModeB,  InstSize, 

( (Data91 1  IN  AddrModeA)  OR  (Data03  IN  AddrModeA)  OR 

GetValue,  GetSize,  GetlnstModeSize,  GetOperand,  GetMultReg; 

(DataO 7  IN  AddrModeA)  OR  (CntR911  IN  AddrModeA))  THEN 

CONST 

(*  Quick  instruction  *) 

InstSize  2; 

END; 

JMP  -  {14,  11,  10,  9,  7,  6); 

CardToLong  (InstSize,  AddrAdv); 

JSR  -  {14,  11,  10,  9,  7}; 

END; 

RTE  -  {14,  11,  10,  9,  6,  5,  4,  1,  0); 

END  BuildSymTable; 

RTR  -  {14,  11,  10,  9,  6,  5,  4,  2,  1,  0); 

RTS  -  {14,  11,  10,  9,  6,  5,  4,  2,  0); 

TRAPV  -  {14,  11,  10,  9,  6,  5,  4,  2,  1); 

STOP  -  {14,  11,  10,  9,  6,  5,  4,  1); 

PROCEDURE  MergeModes  (VAR  SrcOp,  DestOp  :  OPERAND; 

LINK  -  {14,  11,  10,  9,  6,  4); 

VAR  ObjOp,  ObjSrc,  ObjDest  :  LONG; 

SWAP  -  {14,  11,  6); 

VAR  nO,  nS,  nD  :  CARDINAL); 

UNLK  -  {14,  11,  10,  9,  6,  4,  3); 

(*  Uses  information  from  Instructions  i  GetOperand  (among  others)  *) 

Quote  -  47C; 

(*  to  complete  calculation  of  Object  Code.  *) 

{*  Op,  AddrModeA,  AddrModeB,  Size,  and  Src  t  Dest  records  are  all  *) 

(*  Global  variables  imported  from  the  SyntaxAnalyzer  MODULE.  *) 

(* - 

CONST 

(*  Defined  in  DEFINITION  MODULE  *) 

(*  BITSETs  of  the  modes  MISSING  from  effective  address  modes  *) 

LZero,  AddrCnt  :  LONG; 

ea  -  { ) ;  (*  Effective  addressing  -  all  modes  *) 

Pass2  :  BOOLEAN; 

dea  -  (1);  (*  Data  effective  addressing  *) 

- .) 

mea  -  {1,  0);  (*  Memory  effective  addressing  *) 

AddrAdv  :  LONG; 

cea  -  {11,  4,  3,  1,  0);  (*  Control  effective  addressing  *) 

TempL  :  LONG;  (*  Temporary  variables  *) 

aea  -  {11,  10,  9);  (*  Alterable  effective  addressing  *) 

Tempi  ;  INTEGER; 

XXX  -  {15,  14,  13);  (*  extra  modes:  CCR/SR/USP  *) 

TempC  :  CARDINAL; 

(*  2  "AND"  masks  to  turn  off  switch  bits  for  shift/rotate  *) 

BrValue  :  LONG;  (*  Used  to  calculate  relative  branches  *) 

Of f910  -  {15,  14,  13,  12,  11,  8,  7,  6,  5,  4,  3,  2,  1,  0); 

RevBr  ;  BOOLEAN; 

Of f34  -  {15,  14,  13,  12,  11,  10,  9,  8,  7,  6,  5,  2,  1,  0); 

PROCEDURE  BuildSym Table  (VAR  AddrCnt  :  LONG; 

VAR 

M  :  CARDINAL; 
i  :  CARDINAL; 

Label,  OpCode  :  TOKEN;  SrcOp,  DestOp  :  OPERAND); 

Ext  :  BITSET;  {*  Bit  pattern  for  instruction  extension  word  *) 

(*  Builds  symbol  table  from  symbolic  information  of  Source  File  *) 

ExtL  :  LONG; 

VAR 

Xext  J  BITSET; 

Quick  :  BOOLEAN; 

Value  ;  LONG; 

Full  :  BOOLEAN; 

PseudoOp  :  BOOLEAN; 

PROCEDURE  OperExt  (VAR  EA  :  OpConfig)  ; 

BEGIN 

Value  : -  LZero; 

(*  Calculate  Operand  Extension  word,  and  check  range  of  Operands  *) 

VAR 

AddrAdv  LZero; 

GoodCard,  Goodlnt  :  BOOLEAN; 

InstSize  0; 

PseudoOp  FALSE; 

BEGIN 

Size  SO; 

GoodCard  LongToCard  (EA. Value,  TempC); 

IF  Length  (OpCode)  -  0  THEN 

RETURN;  (•  Nothing  added  to  symbol  table,  AddrCnt  not  changed  *) 

Goodlnt  LongToInt  (EA. Value,  Tempi); 

CASE  EA .Mode  OF 

END; 

AbsL  :  ;  (*  No  range  checking  needed  *) 

GetSize  (OpCode,  Size); 

|  AbsW  ;  IF  NOT  GoodCard  THEN 

Error  (EA.Loc,  SizeErr) ; 

IF  CompareStr  (OpCode,  "ORG")  -  0  THEN 

END; 

|  ARDisp, 

GetValue  (SrcOp,  AddrCnt); 

PCDisp  :  IF  NOT  Goodlnt  THEN 

AddrBoundW  (AddrCnt); 

Error  (EA.Loc,  SizeErr) ; 

Value  AddrCnt; 

END; 

PseudoOp  TRUE; 

|  ARDisX, 

ELSIF  CompareStr  (OpCode,  "EQU")  -  0  THEN 

PCDisX  :  IF  (Tempi  <  -128)  OR  (Tempi  >  127)  THEN 

GetValue  (SrcOp,  Value) ; 

Error  (EA.Loc,  SizeErr) ; 

PseudoOp  :*■  TRUE; 

END; 

ELSIF  CompareStr  (OpCode,  "DC")  -  0  THEN 

Xext  BITSET  (EA.Xn  *  4096); 

CASE  Size  OF 

IF  EA. X  -  Areg  THEN 

Word  :  AddrBoundW  (AddrCnt); 

Xext  Xext  +  {15}; 

I  Long  :  AddrBoundL  (AddrCnt); 

END; 

1  Byte  :  ; 

IF  EA.Xsize  -  Long  THEN 

END; 

Xext  Xext  +  {11); 

IF  SrcOp[0)  -  Quote  THEN  (*  String  Constant  •) 

END; 

CardToLong  (CARDINAL  (Xext),  TempL); 

TempC  Length  (SrcQp); 

EA.Value[3)  :-TempL[3); 

IF  TempC  >  2  THEN 

EA.Value[4]  TempL(4); 

InstSize  TempC  -  2; 

|  Imm  ;  IF  Size  -  Long  THEN 

END; 

(*  No  range  check  needed  *) 

ELSE 

ELSE 

InstSize  ORD  (Size); 

IF  Goodlnt  THEN 

END; 

IF  Size  -  Byte  THEN 

CardToLong  (InstSize,  AddrAdv); 

IF  (Tempi  <  -128)  OR  (Tempi  >  127)  THEN 

Value  :■  AddrCnt; 

Error  (EA.Loc,  SizeErr); 

PseudoOp  TRUE; 

END; 

ELSIF  CompareStr  (OpCode,  "DS")  -  0  THEN 

END; 

GetValue  (SrcC^p,  AddrAdv)  ; 

ELSE 

Value  AddrCnt; 

Error  (EA.Loc,  SizeErr); 

PseudoOp  TRUE; 

END; 

ELSIF  CompareStr  (OpCode,  "EVEN")  -  0  THEN 

END; 

AddrBoundW  (AddrCnt) ; 

ELSE 

Value  AddrCnt; 

(*  No  Action  *) 

PseudoOp  TRUE; 

END; 

ELSIF  CompareStr  (OpCode,  "END")  -  0  THEN 

END  qperExt; 

PseudoOp  TRUE; 

ELSE 

PROCEDURE  EffAdr  (VAR  EA  :  OpConfig;  Bad  :  BITSET); 

Value  AddrCnt; 

(*  adds  effective  address  field  to  Op  (BITSET  representing  opcode)  *) 

END; 

IF  Length  (Label)  #  0  THEN 

VAR 

M  :  CARDINAL; 

FillSymTab  (Label,  Value,  Full) ; 

i  :  CARDINAL; 

IF  Full  THEN 

Xext  :  BITSET; 

Error  (0,  SymFull) ; 

END; 

BEGIN 

END; 

M  ORD  (EA.Mode) ; 

IF  NOT  PseudoOp  THEN 

IF  M  IN  Bad  THEN 
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Error  (EA.Loc,  ModeErr); 

RETURN; 

ELS  IF  M  >  11  THEN 
RETURN ; 

ELS  IF  M  <  7  THEN 

Op  Op  +  BITSET  (M  *  8)  +  BITSET  (EA.Rn) ; 

ELSE  (*  7  <-  M  <-  11  *) 

Op  Op  +  (5,  4,  3}  +  BITSET  (M  -  7); 

END; 

OperExt  (EA)  ; 

END  EffAdr; 

BEGIN  (*  MergeModea  *) 

ExtL  ; ■  LZero; 

Quick  FALSE; 

(*  Check  for  5  special  cases  first  *) 

IF  (Op  -  RTE)  OR  (Op  -  RTR)  OR  (Op  -  RTS)  OR  (Op  -  TRAPV)  THEN 
IF  Sr c. Mode  #  Null  THEN 

Error  (SrcLoc,  OperErr) ; 

END; 

END; 

IF  Op  -  STOP  THEN 

IF  (Src.Mode  #  Iram)  OR  (Dest.Mode  #  Null)  THEN 
Error  (SrcLoc,  OperErr) ; 

END; 

END; 

IF  Op  -  LINK  THEN 

Op  Op  +  BITSET  (Src.Rn); 

IF  (Src.Mode  t  ARDir)  OR  (Dest.Mode  #  Imm)  THEN 
Error  (SrcLoc,  ModeErr) ; 

END; 

END; 

IF  Op  -  SWAP  THEN 

IF  EAOSf  IN  AddrModeB  THEN 

(*  Ignore,  this  is  PEA  instruction!  *) 

ELSE 

Op  Op  +  BITSET  (Src.Rn); 

IF  (Src.Mode  #  DReg)  OR  (Dest.Mode  t  Null)  THEN 
Error  (SrcLoc,  OperErr); 

END; 

END; 

END; 

IF  Op  -  UNLK  THEN 

Op  Op  +  BITSET  (Src.Rn); 

IF  (Src.Mode  #  ARDir)  OR  (Dest.Mode  «  Null)  THEN 
Error  (SrcLoc,  OperErr); 

END; 

END; 

(*  Now  do  generalized  address  modes  *) 

IF  (Ry02  IN  AddrModeA)  AND  (Rx911  IN  AddrModeA)  THEN 
Op  !-  Op  +  BITSET  (Src.Rn)  +  BITSET  (Dest.Rn  *  512); 

(*  Now  do  some  error  checking!  *) 

IF  RegMem3  IN  AddrModeA  THEN 
IF  Src.Mode  -  DReg  THEN 

IF  Dest.Mode  #  DReg  THEN 

Errpr  (DestLoc,  ModeErr) ; 

END; 

ELSIF  Src.Mode  -  ARPre  THEN 
Op  Op  +  (3); 

IF  Dest.Mode  #  ARPre  THEN 
Error  (DestLoc,  ModeErr) ; 

END; 

ELSE 

Error  (SrcLoc,  OperErr) ; 

END; 

ELSE 

IF  Src.Mode  -  ARPoat  THEN 

IF  Dest.Mode  #  ARPost  THEN 
Error  (DestLoc,  ModeErr) ; 

END; 

ELSE 

Error  (SrcLoc,  OperErr) ; 

END; 

END; 

END; 

IF  Data!)  11  IN  AddrModeA  THEN 
Quick  TRUE; 

IF  Src.Mode  -  Imm  THEN 

IF  LongToInt  (Src. Value,  Tempi) 

AND  (Tempi  >  0) 

AND  (Tempi  <-  8)  THEN 

IF  Tempi  <  8  THEN  (*  Data  of  8  is  coded  as  000  *) 

Op  Op  +  BITSET  (Tempi  *  512); 

END; 

ELSE 

Error  (SrcLoc,  SizeErr); 

END; 

ELSE 

Error  (SrcLoc,  OperErr); 

END; 

END; 

IF  CntR911  IN  AddrModeA  THEN 

(*  Only  Shift/Rotate  use  this  *) 

IF  Dest.Mode  -  DReg  THEN 

Op  (Op  •  Of f 910)  +  BITSET  (Dest.Rn); 

CASE  Size  OF 
Byte  :  ; 

|  Word  :  Op  :-Op  +  (6); 
j  Long  :  C^>  :  -  C*>  +  ( 7 } ; 

END; 

IF  Src.Mode  -  DReg  THEN 

Op  Op  +  (5)  +  BITSET  (Src.Rn  *  512); 

ELSIF  Src.Mode  -  Imm  THEN 
Quick  TRUE; 

(*  Range  Check  *) 

IF  LongToInt  (Src. Value,  Tempi) 

AND  (Tempi  >  0) 

AND  (T  imp  I  <-  8)  THEN 

IF  Tempi  <  8  THEN  (*  Data  of  8  is  coded  as  000  *) 
Op  Op  +  BITSET  (Tempi  *  512) ; 

END; 

ELSE 

Error  (SrcLoc,  SizeErr) ; 

END; 

ELSE 

Error  (SrcLoc,  C^>orErr) ; 

END; 

ELSIF  Dest.Mode  -  Null  THEN 
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Listing  Seventeen  (listing  continued) 


Op  (Op  *  Of f34)  +  {7,  f); 

EffAdr  (Src,  (meat  4-  aea)  ) ; 

ELSE 

Error  (SrcLoc,  OperErr); 

END; 

END; 

IF  Data03  IN  AddrModaA  THEN 
Quick  TRUE; 

IF  Src. Mode  -  I  nun  THEN 

IF  LongToInt  (Src. Value,  Tempi) 

AND  (Tempi  >-  0) 

AND  (Tempi  <  16)  THEN 
Op  Op  +  BITSET  (Tear.  I); 

ELSE 

Error  (SrcLoc,  SizeErr) ; 

END; 

ELSE 

Error  (SrcLoc,  OperErr); 

END; 

END; 

IF  Data07  IN  AddrModeA  THEN 
Quick  TRUE; 

IF  (Src. Mode  -  Imm)  AND  (Dest.Mode  -  DReg)  THEN 
IF  LongToInt  (Src. Value,  Tempi) 

AND  (Tempi  >-  -128) 

AND  (Tempi  <-  127)  THEN 

Op  Op  4  (BITSET  (Tempi)  *  {7,  6,  5,  4,  3,  2,  1,  0)) 

4  BITSET  (Deat.Rn  *  512); 

ELSE 

Error  (SrcLoc,  SizeErr) ; 

END; 

ELSE 

Error  (SrcLoc,  OperErr) ; 

END; 

END; 

IF  OpM68D  IN  AddrModeA  THEN 
IF  Dest.Mode  -  DReg  THEN 

Op  Op  +  BITSET  (Dest.Rn  *  512); 

IF  (Src. Mode  -  ARDir)  AND  (Size  -  Byte)  THEN 
Error  (SrcLoc,  SizeErr) ; 

END; 

ELSE  (*  Assume  Src. Mode  -  DReg  —  Error  trapped  elsewhere  •) 
Op  Op  +  BITSET  (Src.Rn  *  512); 

Op  Op  +  (8); 

END; 

CASE  Size  OF 

Byte  :  ; 

|  Word  :  Op  Op  +  (6); 

j  Long  :  Op  s-  Op  +  (7); 

END; 

END; 

IF  OpM68A  IN  AddrModeA  THEN 
IF  Dest.Mode  -  ARDir  THEN 

Op  Op  +  BITSET  (Dest.Rn  *  512); 

ELSE 

Error  (DestLoc,  ModeErr) ; 

END; 

CASE  Size  OF 

Byte  :  Error  (QpLoc,  SizeErr); 

|  Word  :  Op  Op  4  (7,  6); 

j  Long  :  Op  Op  4  (8,  7,  6); 

END; 

END; 

IF  OpM68C  IN  AddrModeA  THEN 
IF  Dest.Mode  -  DReg  THEN 

Op  Op  4  BITSET  (Dest.Rn  *  512); 

ELSE 

Error  (DestLoc,  ModeErr) ; 

END; 

CASE  Size  OF 

Byte  :  IF  Src. Mode  -  ARDir  THEN 

Error  (OpLoc,  SizeErr) ; 

END; 

|  Word  :  Op  Op  4  (6); 
j  Long  :  Op  Op  4  (7); 

END; 

END; 

IF  OpM68X  IN  AddrModeA  THEN 
IF  Src. Mode  -  DReg  THEN 

Op  Op  4  BITSET  (Src.Rn  *  512); 

ELSE 

Error  (SrcLoc,  ModeErr) ; 

END; 

CASE  Size  OF 

Byte  :  Op  s-  Op  4  (8); 

|  Word  :  Op  Op  4  (8,  6); 
j  Long  :  Op  :-Op  4  (8,  7); 

END; 

END; 

IF  OpM68S  IN  AddrModeA  THEN 
IF  Src. Mode  -  DReg  THEN 

Op  s-  Op  4  BITSET  (Src.Rn); 

ELSE 

Error  (SrcLoc,  ModeErr); 

END; 

CASE  Size  OF 

Byte  ;  Error  (OpLoc,  SizeErr) ; 

|  Word  :  Op  Op  4  (7); 
j  Long  «  Op  Op  4  {7,  6); 

END; 

END; 

IF  OpM68R  IN  AddrModeA  THEN 

IF  (Src. Mode  -  DReg)  AND  (Dest.Mode  -  ARDisp)  THEN 
CASE  Size  OF 

Byte  :  Error  (OpLoc,  SizeErr); 

|  Word  :  Op  :  —  CDp  4  (8,  7); 

j  Long  :  Op  Op  4  (8,  7,  6); 

END; 

Op  Op  4  BITSET  (Src.Rn  *  512)  4  BITSET  (Dest.Rn); 

ELS  IF  (Src. Mode  -  ARDisp)  AND  (Dest.Mode  -  DReg)  THEN 
CASE  Size  OF 

Byte  :  Error  (OpLoc,  SizeErr) ; 

|  Word  :  Op  Op  4  (8); 

j  Long  :Op  Op  4  (8,  6); 

END; 

Op  Op  4  BITSET  (Src.Rn)  4  BITSET  (Dest.Rn  *  512); 


ELSE 

Error  (SrcLoc,  ModeErr); 

END; 

END; 

IF  OpM37  IN  AddrModeA  THEN 

IF  (Src. Mode  -  DReg)  AND  (Dest.Mode  -  DReg)  THEN 

Cp  Op  4  (6)  4  BITSET  (Src.Rn  *  512)  4  BITSET  (Dest.Rn); 

ELS  IF  (Src. Mode  -  ARDir)  AND  (Dest.Mode  -  ARDir)  THEN 

Op  Op  4  (6,  3)  4  BITSET  (Src.Rn  *  512)  4  BITSET  (Dest.Rn); 
ELSIF  (Src. Mode  -  ARDir)  AND  (Dest.Mode  -  DReg)  THEN 

Op  Op  4  (7,  3)  4  BITSET  (Dest.Rn  *  512)  4  BITSET  (Src.Rn); 
ELSIF  (Src. Mode  -  DReg)  AND  (Dest.Mode  -  ARDir)  THEN 

Op  Op  4  (7,  3)  4  BITSET  (Src.Rn  *  512)  4  BITSET  (Dest.Rn); 
ELSE 

Error  (SrcLoc,  ModeErr); 

END; 

END; 

IF  Bit81 1  IN  AddrModeB  THEN 
IF  Src. Mode  -  DReg  THEN 

Op  Op  4  (8)  4  BITSET  (Src.Rn  *  512); 

ELSIF  Src. Mode  -  Imm  THEN 
Op  Op  4  {11}; 

ELSE 

Error  (SrcLoc,  ModeErr); 

END; 

END; 

IF  Size67  IN  AddrModeB  THEN 
CASE  Size  OF 

Byte  :  ; (*  No  action  —  bits  already  0's  *) 

|  Word  ;  Op  Op  4  (6); 

j  Long  ;  Op  Op  4  (7); 

END; 

END; 

IF  Size6  IN  AddrModeB  THEN 
CASE  Size  OF 

Byte  :  Error  (OpLoc,  SizeErr); 

|  Word  :  (*  No  Action  —  BIT  is  already  0  *) 

j  Long  :  Op  s-  Op  4  (6); 

END; 

END; 

IF  Sizel213A  IN  AddrModeB  THEN 
CASE  Size  OF 

Byte  :  Op  :-Op  4  (12); 

|  Word  :  Op  Op  4  (13,  12); 

|  Long  :  Op  Op  4  (13); 

END; 

END; 

IF  Sizel213  IN  AddrModeB  THEN 

Op  Op  4  BITSET  (Dest.Rn  •  512); 

CASE  Size  OF 

Byte  :  Error  (OpLoc,  SizeErr); 

|  Word  :  Op  Op  4  (13,  12); 

I  Long  :  Op  Op  4  (13); 

END; 

END; 

IF  EAO 5a  IN  AddrModeB  THEN 

IF  (Dest.Mode  -  DReg)  OR  (Dest.Mode  -  ARDir)  THEN 
EffAdr  (Src,  ea) ; 

ELSE 

Error  (DestLoc,  ModeErr) ; 

END; 

END; 

IF  EAO 5b  IN  AddrModeB  THEN 
IF  Dest.Mode  -  DReg  THEN 
EffAdr  (Src,  dea) ; 

Op  Op  4  BITSET  (Dest.Rn  *  512); 

ELSE 

Error  (DestLoc,  ModeErr) ; 

END; 

END; 

IF  EAO 5c  IN  AddrModeB  THEN 
EffAdr  (Dest,  (11,  1)); 

END; 

IF  EA05d  IN  AddrModeB  THEN 
EffAdr  (Dest,  aea) ; 

IF  (Dest.Mode  -  ARDir)  AND  (Size  -  Byte)  THEN 
Error  (OpLoc,  SizeErr) ; 

END; 

END; 

IF  EA05e  IN  AddrModeB  THEN 
IF  Dest.Mode  -  Null  THEN 

EffAdr  (Src,  (dea  4  aea) ) ; 

ELSIF  (Src. Mode  -  Imm)  OR  (Src. Mode  -  DReg)  THEN 
EffAdr  (Dest,  (dea  4  aea) ) ; 

ELSE 

Error  (SrcLoc,  ModeErr); 

END; 

END; 

IF  EA05f  IN  AddrModeB  THEN  (*  LEA  &  PEA  /  JMP  t  JSR  *) 

EffAdr  (Src,  cea) ; 

IF  Rx91 1  IN  AddrModeA  THEN 
IF  Dest.Mode  -  ARDir  THEN 

Op  Op  4  BITSET  (Dest.Rn  *  512); 

ELSE 

Error  (DestLoc,  ModeErr) ; 

END; 

ELSE 

IF  Dest.Mode  #  Null  THEN 

Error  (DestLoc,  OperErr); 

END; 

END; 

END; 

IF  EA05x  IN  AddrModeB  THEN 
IF  Dest.Mode  -  DReg  THEN 
EffAdr  (Src,  dea) ; 

ELSIF  Src. Mode  -  DReg  THEN 
EffAdr  (Dest,  mea  4  aea) ; 

ELSE 

Error  (SrcLoc,  OperErr) ; 

END; 

END; 

IF  EA05y  IN  AddrModeB  THEN 
IF  Dest.Mode  -  DReg  THEN 
EffAdr  (Src,  ea)  ; 

IF  (Src. Mode  -  ARDir)  AND  (Size  -  Byte)  THEN 


(continued  on  page  50) 
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ListinQ  Seventeen  (listing continued) 

Error  (OpLoc,  SizeErr); 

Dir  :  DirType; 

END; 

i,  j  :  CARDINAL; 

ELS  IF  Src .Mode  -  DReg  THEN 

LongString  :  ARRAY  (1..20)  OF  INTEGER; 

EffAdr  (Dest,  (mea  +  aea) ) ; 

ELSE 

BEGIN 

Error  (SrcLoc,  ModeErr) ; 

AddrAdv  LZero; 

END; 

END; 

IF  CompareStr  (OpCode,  "ORG")  -  0  THEN 

IF  EA05z  IN  AddrModeB  THEN 

GetValue  (SrcOp,  AddrCnt) ; 

AddrBoundW  (AddrCnt) ; 

IF  Src. Mode  -  MultiM  THEN 

Dir  Org; 

EffAdr  (Dest,  (mea  +  aea  +  (3))); 

ELSIF  CompareStr  (OpCode,  "EQU")  «  0  THEN 

GetMultReg  (SrcOp,  (Dest. Mode  -  ARPre) ,  SrcLoc,  Ext); 

GetValue  (SrcOp,  ObjSrc) ; 

ELS  IF  Dest. Mode  -  MultiM  THEN 

nS  8; 

EffAdr  (Src,  (mea  +  (11,  4})); 

Dir  Equ; 

GetMultReg  (DestOp,  (Src. Mode  -  ARPre),  DestLoc,  Ext); 

ELSIF  CompareStr  (OpCode,  "DC")  -  0  THEN 

C^p:-Op+(10);  (*  set  direction  *) 

CASE  Size  OF 

ELSE 

Word  :  AddrBoundW  (AddrCnt); 

Error  (SrcLoc,  OperErr) ; 

|  Long  ;  AddrBoundL  (AddrCnt); 

END; 

|  Byte  :  ; 

INC  (nO,  4);  (*  extension  is  part  of  OpCode  *) 

INC  (InstSize,  2)  ; 

END; 

IF  SrcOp (0)  -  Quote  THEN  (*  String  constant  *) 

CardToLong  (CARDINAL  (Ext),  ExtL) ; 

TempC  Length  (SrcOp); 

END; 

IF  TempC  >  2  THEN 

IF  EA611  IN  Addrl.odeB  THEN 

InstSize  TempC  -  2;  (*  Don't  count  the  Quotes  *) 

END; 

IF  Dest. Mode  -  CCR  THEN 

Op  (14,  10,  7,  6}; 

i  1;  j  20; 

EffAdr  (Src,  dea) ; 

WHILE  i  <-  InstSize  DO  (*  Change  from  ASCII  to  LONG  *) 

ELS  IF  Dest. Mode  =  SR  THEN 

CardToLong  (ORD  (SrcOp[i]),  TempL) ; 

Op  (14,  10,  9,  7,  6); 

LongStringJ j)  TempL(2J; 

EffAdr  (Src,  dea); 

LongS tring(j  -  1]  TempL [ 1] ; 

ELS  IF  Src. Mode  -  SR  THEN 

INC  (i);  DEC  (j,  2)  ; 

Op  (14,  7,  6); 

END; 

EffAdr  (Dest,  dea  +  aea); 

ELS  IF  Dest. Mode  =  USP  THEN 

i  1;  INC  (j); 

Op  (14,  11,  10,  9,  6,  5); 

WHILE  j  <-  20  DO  (*  Left  Justify  String  *) 

IF  Src. Mode  -  ARDir  THEN 

LongString [i]  LongString! j] ; 

Op  Op  +  BITSET  (Src.Rn); 

INC  (1) ;  INC  (j); 

ELSE 

END; 

Error  (SrcLoc,  ModeErr) ; 

END; 

DEC  (i); 

ELS  IF  Src. Mode  -  USP  THEN 

WHILE  i  >  16  DO  (*  Transfer  2  bytes  to  OpCode  *) 

Op  (14,  11,  10,  9,  6,  5,  3); 

ObjOp[i  -  16]  LongString (i] ; 

IF  Dest. Mode  =*  ARDir  THEN 

INC  (nO);  DEC  (i) ; 

Op  Op  +  BITSET  (Dest.Rn); 

END; 

ELSE 

Error  (DestLoc,  ModeErr); 

WHILE  i  >  8  DO  (*  Transfer  4  bytes  to  Source  Operand  *) 

END; 

ObjSrc(i  -  8]  LongString [i] ; 

ELSE 

INC  (nS);  DEC  (i)  ; 

EffAdr  (Src,  (ea  +  xxx) ) ; 

END; 

IF  (Size  -  Byte)  AND  (Src. Mode  -  ARDir)  THEN 

Error  (SrcLoc,  SizeErr) ; 

WHILE  i  >  0  DO  (*  Transfer  4  bytes  to  Destination  Operand  *) 

END; 

ObjDest [1]  LongString! i) ; 

M  ORD  (Dest .Mode); 

INC  (nD);  DEC  (i)  ; 

END; 

IF  (M  IN  (dea  +  aea))  OR  (M  >  11)  THEN 

Error  (DestLoc,  ModeErr); 

IF  SrcC^>  (InstSize  +  1]  #  Quote  THEN 

ELSIF  M  <  7  THEN 

Error  ((SrcLoc  +  InstSize  +  1),  OperErr); 

Op  Op  +  BITSET  (M  ‘  64)  +  BITSET  (Dest.Rn  •  512); 

END; 

ELSE  (*  7  <-  M  <-  11  *) 

ELSE  {*  not  a  string  constant  *) 

Op  Op  +  (8,  7,  6)  +  BITSET  (  (M  -  7)  *  512); 

GetValue  (SrcOp,  ObjSrc) ; 

END; 

InstSize  ORD  (Size) ; 

C^ierExt  (Dest)  ; 

nS  InstSize  *  2; 

END; 

END; 

CardToLong  (InstSize,  AddrAdv); 

END; 

nA  6; 

IF  (Dest .Mode  -  CCR)  AND  (Src. Mode  -  Imm)  THEN 

Dir  DC; 

ELSIF  CompareStr  (OpCode,  "DS")  -  0  THEN 

IF  (Size67  IN  AddrModeB) 

GetValue  {Srcqp,  AddrAdv) ; 

AND  (EA05e  IN  AddrModeB) 

nA  :■*  6;  nS  2;  ObjSrc  LZero; 

AND  (Exten  IN  AddrModeB)  THEN 

Dir  DS; 

IF  10  IN  Op  THEN  (*  NOT  ANDI/EORI/ORI  *) 

ELSIF  CompareStr  (OpCode,  "EVEN")  -  0  THEN 

Error  (DestLoc,  ModeErr); 

AddrBoundW  (AddrCnt); 

ELSE 

Dir  Even; 

Op  Op  *  (15,  14,  13,  12,  11,  10,  9,  8);  (*  AND  mask  *) 

ELSIF  CompareStr  (OpCode,  "END")  =  0  THEN 

Op  Op  +  (5,  4,  3,  2);  (*  OR  mask  *) 

nA  6; 

END; 

Dir  End; 

END; 

ELSE 

END; 

Dir  : “  None; 

IF  (Dest .Mode  -  SR)  AND  (Src. Mode  -  Imm)  THEN 

IF  (Size67  IN  AddrModeB) 

END; 

RETURN  (Dir) ; 

AND  (EA05e  IN  AddrModeB) 

END  ObjDir; 

AND  (Exten  IN  AddrModeB)  THEN 

IF  10  IN  Op  THEN  (*  NOT  ANDI/EORI/ORI  *) 

Error  (DestLoc,  ModeErr); 

ELSE 

PROCEDURE  AdvAddrCnt  (VAR  AddrCnt  :  LONG) ; 

Op  Op  *  (15,  14,  13,  12,  11,  10,  9,  8);  (*  AND  mask  *) 

(*  Advances  the  address  counter  based  on  the  length  of  the  instruction  *) 

Op  Op  +  (6,  5,  4,  3,  2);  (*  OR  mask  *) 

BEGIN 

END; 

LongAdd  (AddrCnt,  AddrAdv,  AddrCnt); 

END; 

END  AdvAddrCnt; 

END; 

CardToLong  (CARDINAL  (Op),  Ob jOp) ; 

INC  (InstSize,  2); 

PROCEDURE  GetOb jectCode  (Label,  OpCode  :  TOKEN; 

INC  (nO,  4); 

SrcOp,  DestOp  :  OPERAND; 

IF  nO  >  4  THEN 

VAR  AddrCnt,  ObjOp,  ObjSrc,  ObjDest  :  LONG; 

FOR  i  1  TO  4  DO  (*  move  ObjOp  —  make  room  for  extension  *) 

VAR  nA,  nO,  nS,  nD  :  CARDINAL) ; 

ObjOp[i  +  4]  ObjOpli]; 

(*  Determines  the  object  code  for  the  operation  as  well  as  the  operands  *) 

ObjOp [ i]  ExtL [i] ; 

(*  Returns  each  (up  to  3  fields),  along  with  the  length  of  each.  *) 

END; 

VAR 

nS  :»  GetlnstModeSize  (Src. Mode,  Size,  InstSize); 

Dummy  :  BOOLEAN; 

Dir  :  DirType; 

ObjSrc  Src. Value; 

nD  GetlnstModeSize  (Dest. Mode,  Size,  InstSize); 

BEGIN 

ObjDest  Dest. Value; 

AddrAdv  LZero; 

IF  Quick  THEN 

InstSize  0; 

nA  0;  nO  0;  nS  0;  nD  0; 

InstSize  :■»  2; 
nS  0;  nD  0; 

IF  Length  (OpCode)  -  0  TEEN 

END; 

(*  ensure  no  code  generated  *) 

CardToLong  (InstSize,  AddrAdv); 

RETURN; 

END  MergeModes; 

TYPE 

END; 

GetSize  (OpCode,  Size) ; 

Dir  ObjDir  (OpCode,  SrcOp,  Size, 

AddrCnt,  ObjOp,  ObjSrc,  ObjDest, 

DirType  =  (None,  Org,  Egu,  DC,  DS,  Even,  End) ; 

nA,  nO,  nS,  nD  ) ; 

PROCEDURE  ObjDir  (OpCode  :  TOKEN;  SrcOp  :  OPERAND;  Size  ;  SizeType; 

IF  (Length  (Label)  #  0)  AND  (Dir  #  Egu)  THEN 

VAR  AddrCnt,  ObjOp,  ObjSrc,  ObjDest  :  LONG; 

(*  Check  for  phase  error  *) 

VAR  nA,  nO,  nS,  nD  :  CARDINAL)  :  DirType; 

Dummy  ReadSymTab  (Label,  TempL,  Dummy); 

(*  Generates  Object  Code  for  Assembler  Directives  *) 

IF  LongCompare  (TempL,  AddrCnt)  #  0  THEN 

VAR 

Error  (0,  Phase) ; 

END; 
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Listing  Seventeen  (listing  continued) 


END; 

IF  Dir  -  Nona  THEN  (*  Instruction  *) 

AddrBoundW  (AddrCnt); 

ELSE 

RETURN; 

END; 

Instructions  (Opcode,  OpLoc,  Op,  AddrModeA,  AddrModeB) ; 

Src.Loc  SrcLoc;  Dest.Loc  DestLoc; 

GetOperand  (SrcOp,  Src) ;  (*  Src  t  Dost  are  RECORDS  *) 

GetOperand  (DestOp,  Dest) ; 

IF  DecBr  IN  AddrModeA  THEN  (*  Decrement  &  Branch  *) 

IF  Src. Mode  *  DReg  THEN 

Error  (SrcLoc,  ModeErr) ; 

END; 

BrValue  Dest .Value; 

TempL  AddrCnt; 

TempC  32767;  (*  Maximum  Branch  *) 

Longlnc  (TempL,  2);  (*  move  past  instruction  for  Rel  Adr  Calc  *) 

IF  LongCompare  (BrValue,  TempL)  <  0  THEN 
RevBr  TRUE; 

LongSub  (TempL,  BrValue,  BrValue); 

INC  (TempC);  (*  can  branch  1  farther  in  reverse  *) 

ELSE 

RevBr  FALSE; 

LongSub  (BrValue,  TempL,  BrValue); 

END; 

CardToLong  (TempC,  TempL);  (*  Maximum  Branch  distance  *) 

IF  LongCompare  (BrValue,  TempL)  >  0  THEN 
Error  (DestLoc,  BraErr) ; 

END; 

IF  RevBr  THEN  (*  Make  Negative  *) 

LongSub  (LZero,  BrValue,  BrValue) 

END; 

CardToLong  (4,  AddrAdv) ; 
nA  6;  nO  4;  nS  4; 

CardToLong  (CARDINAL  (Op  +  BITSET  (Src.Rn)),  Ob jOp) ; 

ObjSrc  BrValue; 

RETURN; 

END; 

IF  Brnch  IN  AddrModeA  THEN  (*  Branch  *) 

BrValue  Src. Value;  (*  Destination  of  Branch  *) 

TempL  AddrCnt; 

Longlnc  (TempL,  2); 

IF  Size  #  Byte  THEN  (*  Byte  Size  - >  Short  Branch  *) 

TempC  32767;  (*  Set  maximum  branch  distance  *) 

ELSE 

TempC  127; 

END; 

CASE  LongCompare  (BrValue,  TempL)  OF 
-1  :  (*  Reverse  Branch  *) 

RevBr  TRUE; 

INC  (TempC);  (*  can  branch  1  farther  in  reverse  *) 
LongSub  (TempL,  BrValue,  BrValue); 

|  +1  :  (*  Forward  Branch  *) 

RevBr  FALSE; 

LongSub  (BrValue,  TempL,  BrValue); 

|  0  :  IF  Size  -  Byte  THEN 

Error  (SrcLoc,  BraErr); 

END; 

END; 

CardToLong  (TempC,  TempL) ; 

IF  LongCompare  (BrValue,  TempL)  >  0  THEN 
Error  (SrcLoc,  BraErr) ; 

END; 

IF  RevBr  THEN 

LongSub  (LZero,  BrValue,  BrValue);  (*  Make  negative  *) 

END; 

IF  Size  f  Byte  THEN 
InstSize  4; 

nS  4; 

ObjSrc  BrValue; 

ELSE 

InstSize  2; 

Dummy  LongToInt  (BrValue,  Tempi); 

Op  Op  +  (BITSET  (Tempi)  •  (7,  6,  5,  4,  3,  2,  1,  0)); 

END; 

nA  6;  nO  4; 

CardToLong  (InstSize,  AddrAdv); 

CardToLong  (CARDINAL  (Op),  Ob jOp) ; 

RETURN; 

END; 

nA  6; 

IF  (Op  -  JMP)  OR  (Op  -  JSR)  THEN  (•  Allows  for  'JMP.S*  *) 

IF  (Size  -  Byte)  AND  (Src. Mode  -  AbsL)  THEN 
Src. Mode  AbsH; 

END; 

END; 

MergeModes  (SrcOp,  DestOp,  Objpp,  ObjSrc,  ObjDest,  nO,  nS,  nD)  ; 

END  GetOb jectCode; 


BEGIN  (*  MODULE  Initialization  *) 

LongClear  (LZero);  (*  Used  as  a  constant  *) 
AddrCnt  LZero; 

Pass 2  FALSE; 

END  CodeGenerator . 


End  Listing  Seventeen 


Listing  Eighteen 


IMPLEMENTATION  MODULE  SyntaxAnalyzer; 

(*  Analyzes  the  operands  to  provide  information  for  CodeGenerator  *) 

FRCW  Conversions  IMPORT 
StrToCard; 


FRCM  Strings  IMPORT 
Length; 


FRCM  LongNumbers  IMPORT 

LONG,  LongAdd,  LongSub,  CardToLong,  StringToLong; 

FRCM  SymbolTable  IMPORT 
SortSymTab,  ReadSymTab; 

FRCM  ErrorX68  IMPORT 
ErrorType,  Error; 

FRCM  Parser  IMPORT 
OPERAND,  SrcLoc; 

FRCM  CodeGenerator  IMPORT 

LZero,  AddrCnt,  Pass2;  (•  BOOLEAN  Switch  *) 


CONST 

Zero  ■ 
Seven 
Quote 


30H; 

■  37H; 

■  47C; 


(*  The  Ordinal  value  of  the  Character  ’O’  *) 
(*  The  Ordinal  value  of  the  Character  '7*  *) 


(‘ - 

TYPE 

OpMode  “  (DReg, 
ARDir, 
ARInd, 
ARPost, 
ARPre, 
ARDisp, 
ARDisX, 
AbsH, 
AbsL, 
PCDisp, 
PCDisX, 
I  mm, 
MultiM, 
SR, 

CCR, 
USP, 
Null) ; 


*  Data  Register  *) 

*  Address  Register  Direct  *) 

*  Address  Register  Indirect  *) 

*  Address  Register  with  Post- Increment  *) 

*  Address  Register  with  Pre-Decrement  *) 

*  Address  Register  with  Displacement  *) 

*  Address  Register  with  Disp.  &  Index  *) 

*  Absolute  Word  (16-bit  Address)  *) 

*  Absolute  Word  (32-bit  Address)  *) 

*  Program  Counter  Relative,  with  Displacement  *) 

*  Program  Counter  Relative,  with  Disp.  &  Index  *) 

*  Immediate  *) 

*  Multiple  Register  Move  *) 

*  Status  Register  *) 

*  Condition  Code  Register  *) 

*  User's  Stack  Pointer  *) 

*  Error  Condition,  or  Operand  missing  *) 


Xtype  -  (XO,  Dreg,  Areg) ; 

SizeType  -  (SO,  Byte,  Word,  S3,  Long) ; 


OpConfig  -  RECORD 

Mode  :  OpMode; 
Value  :  LONG; 

Loc  :  CARDINAL; 

Rn  :  CARDINAL; 

Xn  :  CARDINAL; 
Xsize  ;  SizeType; 
X  :  Xtype; 


(*  OPERAND  CONFIGURATION  *) 


*  Location  of  C^erand  on  line  ») 

*  Register  number  *) 

*  Index  Reg.  nbr.  *) 

*  size  of  Index  *) 

*  Is  index  Data  or  Address  reg?  *) 


Size  :  SizeType;  (* 

AbsSize  :  SizeType;  (* 

InstSize  :  CARDINAL;  (* 

AddrModeA  :  ModeA;  (* 

AddrModeB  :  ModeB;  (* 

Op  :  BITSET;  (* 

Src,  Dest  :  OpConfig; 


PROCEDURE  CalcValue  (Operand 
(*  Calculates  left  and  right 

Full  :  BOOLEAN; 

Neg  :  BOOLEAN; 

Dup  :  BOOLEAN; 

Num  :  CARDINAL; 

NumSyms  :  CARDINAL; 

BEGIN 

IF  Operand (0 ]  -  THEN 
Neg  TRUE; 

Operand (0]  '0*; 

ELSE 

Neg  FALSE; 

END; 

IF  StrToCard  (Operand,  Num)  THEN 
(*  It  is  a  number  *) 

CardToLong  (Num,  Value) ; 

IF  Neg  THEN 

LongSub  (LZero,  Value,  Value); 

END; 

ELS IF  StringToLong  (Operand,  Value)  THEN 
(*  It  is  a  HEX  number  *) 

ELSIF  (Operand (0]  -  Quote)  AND  (Operand(2]  -  Quote)  THEN 
CardToLong  (ORD  (Operand! 1) ) ,  Value); 

ELSIF  (Length  (Operand)  -  1)  AND  (Operand(0]  -  '*')  THEN 
Value  AddrCnt; 

ELSE 

(*  It  is  a  label,  but  may  be  undefined!  *) 

IF  NOT  Pass2  THEN 

SortSymTab  (NumSyms) ; 

END; 

IF  NOT  ReadSymTab  (Operand,  Value,  Dup)  THEN 
Error  (SrcLoc,  Undef ) ; 

END; 

IF  Dup  THEN 

Error  (SrcLoc,  SymDup) ; 

END; 

END; 

END  CalcValue; 


size  for  C^pCode  *) 

size  of  operand  (Absolute  only)  *) 

Size  of  instruction,  including  operands  *) 
Addressing  modes  for  this  Instruction  *) 
ditto  •) 

Raw  bit  pattern  for  Opcode  *) 

- .) 


;  OPERAND;  VAR  Value  :  LONG); 
values  for  GetValue  *) 


PROCEDURE  GetValue  (Operand  :  OPERAND;  VAR  Value  ;  LONG) ; 

(*  determines  value  of  operand  (in  Decimal,  HEX,  or  via  Symbol  Table)  *) 

VAR 

TempOp  :  OPERAND; 

TempVal  :  LONG; 
c,  op  :  CHAR; 
i,  j  ;  CARDINAL; 

InQuotes  :  BOOLEAN; 
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UStinQ  Eighteen  (listing  continued) 

BEGIN 

ELSE 

i  0; 

n  2; 

Value  LZero; 

END; 

InQuotes  FALSE; 

ELSE 

op  :  -  '  + ' ; 

n  0; 

REPEAT 

END; 

j  0; 

LOOP 

INC  (InstSize,  n) ; 

c  Operand (1] ; 

RETURN  (n  *  2) ; 

TempOp ( j ]  :=  c; 

END  GetlnstModeSize; 

IF  c  -  Quote  THEN 

InQuotes  NOT  InQuotes; 

END; 

INC  (1);  INC  (j); 

PROCEDURE  GetOporand  (Oper  :  OPERAND;  VAR  Op  :  OpConfig); 

IF  c  -  0C  THEN 

(*  Finds  mode  and  value  for  source  or  destination  operand  *) 

EXIT; 

END; 

VAR 

IF  (c  -  '+')  AND  (NOT  InQuotes)  THEN 

ch  :  CHAR; 

EXIT; 

C  :  CARDINAL;  (*  holds  the  ordinal  value  of  a  charcter  *) 

END; 

i,  j  :  CARDINAL; 

IF  (c  -  AND  (i  >  1)  AND  (NOT  InQuotes)  THEN 

Len  :  CARDINAL;  (*  Calculated  Length  of  Oper  *) 

EXIT; 

TempOp  :  OPERAND; 

END; 

MultFlag  :  BOOLEAN; 

END; 

TempOp [ j  -  1]  0C;  (*  In  case  c  is  +/-  *) 

BEGIN 

CalcValue  (TempOp,  TempVal) ; 

Op. Mode  Null;  Op.X  X0; 

IF  op  -  THEN 

Len  : -  Length  (Oper)  ; 

LongSub  (Value,  TempVal,  Value); 

ELSE 

IF  Len  -  0  THEN 

LongAdd  (Value,  TempVal,  Value); 

RETURN; 

END; 

END; 

op  c; 

UNTIL  op  -  0C; 

GetAbsSize  (Oper,  AbsSize); 

END  GetValue; 

PROCEDURE  GetSize  (VAR  Symbol  :  ARRAY  OF  CHAR;  VAR  Size  :  SizeType); 

IF  Oper ( 0]  -  ’#'  THEN  (•  Immediate  *) 

IF  Pass 2  THEN 
i  0; 

REPEAT 

(*  determines  size  of  op code /ope rand :  Byte,  Word,  Long  *) 

INC  (i) ; 

VAR 

Oper ( i  -  1]  Oper[i); 

UNTIL  Oper(i]  -  0C; 

i  ;  CARDINAL; 

GetValue  (Oper,  .Value); 

c  :  CHAR; 

END; 

BEGIN 

Op. Mode  Imm; 

RETURN; 

i  0; 

END; 

REPEAT 

c  Symbol [i] ; 

IF  Len  -  2  THEN  (*  possible  Addr  or  Data  Register  *) 

INC  (i); 

C  ORD  (Oper ( 1 ] ) ; 

UNTIL  (c  -  0C)  OR  (c  -  '.'); 

IF  (Oper ( 0 ]  -  ’S')  AND  (Opor[l]  -  'R')  THEN 

IF  c  -  0C  THEN 

(*  Status  Register  *) 

Op. Mode  SR; 

Size  Word;  {*  Default  to  size  Word  =  16  bits  *) 

RETURN; 

ELSE 

ELSIF  (Oper[0]  -  ’S')  AND  (Oper(l]  -  'P')  THEN 

c  Symbol [i];  (*  Record  size  extension  *) 

(*  Stack  Pointer  *) 

Symbol [i  -  1]  :*■  GC;  (*  Chop  size  extension  off  *) 

Op. Mode  ARDir; 

IF  (c  »  'B')  OR  (c  =  'S')  THEN  (*  Byte  or  Short  Branch/ Jump  *) 

Op.Rn  7; 

Size  :«  Byte; 

RETURN; 

ELS  IF  c  -  'L'  THEN 

ELSIF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 

Size  Long; 

(*  Looks  Like  an  Addr  or  Data  Reg  *) 

ELSE 

IF  Oper[0]  -  'A'  THEN  (*  Address  Register  *) 

Size  :*■  Word;  (*  Default  size  *) 

Op. Mode  ARDir; 

END; 

Op.Rn  C  -  Zero; 

END; 

RETURN; 

END  GetSize; 

ELSIF  Oper (0 ]  -  'D'  THEN  (*  Data  Register  ») 

PROCEDURE  GetAbsSize  (VAR  Symbol  :  ARRAY  OF  CHAR;  VAR  AbsSize  :  SizeType); 

Op. Mode  : -  DReg; 

Op.Rn  : -  C  -  Zero; 

RETURN; 

ELSE 

(‘  determines  size  of  operand:  Word  or  Long  *) 

(*  may  be  a  label  —  ignore  for  now  *) 

VAR 

END; 

ELSE 

i  ;  CARDINAL; 

(•  may  be  a  label  —  ignore  for  now  *) 

c  :  CHAR; 

END; 

Parent  :  INTEGER; 

END; 

BEGIN 

IF  Len  -  3  THEN 

ParCnt  0; 

IF  (Oper ( 0 J  -  'C')  AND  (Opor|l]  -  'C')  AND  (Oper[2)  -  'R')  THEN 

i  0; 

(*  Condition  Code  Register  *) 

REPEAT 

Op. Mode  CCR; 

c  Symbol [i] ; 

RETURN; 

IF  c  ■  ' ( '  THEN 

ELSIF  (Oper [0 )  -  'U')  AND  (Opor(l)  -  'S')  AND  (Oper[2)  -  'P')  THEN 

INC  (Parent)  ; 

(*  User’s  Stack  Pointer  *) 

END; 

Op. Mode  USP; 

IF  C  «  ')'  THEN 

RETURN; 

DEC  (Parent)  ; 

ELSE 

END; 

(*  may  be  a  label  —  ignore  for  now  *) 

INC  (1)  ; 

END; 

UNTIL  (c  -  0C)  OR  ( (c  -  *.')  AND  (ParCnt  -  0)); 

END; 

IF  c  -  0C  THEN 

IF  (Len  -  4)  AND  (Oper(0)  -  '(')  AND  (Oper (3]  -  ’)')  THEN 

AbsSize  Long; 

IF  (Oper [ 1 )  -  'S')  AND  (Oper [ 2]  -  'P')  THEN 

ELSE 

Op. Mode  ARInd; 

c  :=  Symbol [i];  (*  Record  size  extension  *) 

Op.Rn  7; 

Symbol[i  -  1]  0C;  {*  Chop  size  extension  off  *) 

RETURN; 

IF  (c  -  'W')  OR  (c  -  ’S')  THEN 

ELSIF  Oper [ I]  -  'A'  THEN 

AbsSize  Word; 

C  ORD  (Oper |2]) ; 

ELSE 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 

AbsSize  Long; 

Op. Mode  ARInd; 

END; 

Op.Rn  C  -  Zero; 

END; 

RETURN; 

END  GetAbsSize; 

ELSE 

PROCEDURE  GetlnstModeSize  (Mode  :  OpModo;  Size  :  SizeType; 

Error  (Op.Loc,  SizeErr); 

RETURN; 

END; 

ELSE 

Error  (Op.Loc,  AddrErr) ; 

RETURN; 

VAR  InstSizo  :  CARDINAL)  :  CARDINAL; 

END; 

(*  Determines  the  size  for  the  various  instruction  modes.  *) 

END; 

VAR 

IF  (Len  -  5)  AND  (Oper(0]  -  '(') 

n  :  CARDINAL; 

AND  (Oper (3 )  -  ')')  AND  (Oper[4]  -  '+’)  THEN 

BEGIN 

(*  Address  Indirect  with  Post  Inc  *) 

IF  (Oper | 1]  -  'S’)  AND  (Oper(2]  -  'P')  THEN 

CASE  Mode  OF 

(•  Svstem  Stack  Pointer  *) 

ARDisp, 

Op. Mode  ARPost; 

ARDisX, 

Op.Rn  ; -  7 ; 

PCDisp, 

RETURN 

PCDisX, 

ELSIF  Oper [ 1)  -  'A'  THEN 

AbsW  :  n  2; 

C  ORD  (Oper [2]) ; 

1  AbsL  :  n  4; 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 

|  MultiM  ;  IF  Pass 2  THEN 

Op. Mode  ARPost; 

n  0;  (*  accounted  for  by  code  generator  *) 

Op.Rn  : —  C  -  Zero; 

ELSE 

RETURN; 

n  2; 

ELSE 

END; 

Error  (Op.Loc,  SizeErr); 

|  Imm  ;  IF  Size  -  Long  THEN 

RETURN; 

n  4; 

™0;  (continued  on  page  56) 
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ELSE 

Error  (Op.Loc,  AddrErr); 

RETURN; 

END; 

END; 

IF  (Len  -  5)  AND  (Oper[0]  -  '-•) 

AND  (Oper[l]  -  *  (')  AND  (Oper [4]  -  ')•)  THEN 
IF  (Oper[2]  -  ’S')  AND  (Oper[3]  -  ’P*)  THEN 
(*  System  Stack  Pointer  *) 

Op. Mode  ARPre; 

C^p.Rn  7; 

RETURN; 

ELSIF  Oper (2]  -  ’A'  THEN 
C  ORD  (Oper (3]) ; 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
Op. Mode  ARPre; 

Op.Rn  C  -  Zero; 

RETURN; 

ELSE 

Error  (Op.Loc,  SizeErr); 

RETURN; 

END; 

ELSE 

Error  (Op.Loc,  AddrErr); 

RETURN; 

END; 

END; 

(*  Try  to  split  off  displacement  (if  present)  *) 
i  0; 

ch  Operji]; 

WHILE  (ch  #  *(•)  AND  (ch  #  0C)  DO  (*  move  to  TernpOp  •) 

TempOp  [ i]  ch; 

INC  (i)  ; 
ch  Oper [ i] ; 

END; 

TempOp [i]  0C;  (*  Displacement  (it  it  exists)  now  in  TempOp 

IF  ch  -  '(*  THEN  (*  looks  like  a  displacement  mode  *) 

IF  Pass2  THEN 

GetValue  (TempOp,  Op. Value);  (*  Value  of  Disp.  *) 

END; 
j  0; 

REPEAT  (*  put  rest  of  operand  (eg.  (An,Xi)  in  TempOp  *) 
ch  qper  (i] ; 

TempOp [j]  ch; 

INC  (i);  INC  (j); 

UNTIL  ch  -  0C; 

IF  Length  (TempC^j)  >  4  THEN  (*  Index  may  be  present  *) 
i  t"  4;  {*  Index  starts  at  4  •) 

j  0; 

REPEAT  (*  put  Xi  in  Oper  •) 

ch  TempOp ( i] ; 

Oper [ j]  ch; 

INC  (i);  INC  (j); 

UNTIL  ch  -  0C; 

IF  Oper [ J  -  2]  -  •) '  THEN 
Oper [ j  -  2]  0C; 

ELSE 

Error  (Op.Loc,  AddrErr); 

RETURN; 

END; 

GetSize  (Oper,  Op.Xsize); 

IF  Op.Xsize  -  Byte  THEN 

Error  (Qp.Loc,  SizeErr) ; 

RETURN; 

END; 

C  ORD  (Oper (1J) ; 

IF  (Oper (0 ]  -  ’S')  AND  (Oper[l]  -  ’P’)  THEN 
(*  Stack  Pointer  *) 

Op.X  : “  Areg; 

Op. Xn  7; 

ELSIF  Oper [0 ]  -  ’A'  THEN 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
Qp.X  :■>  Areg; 

Op.Xn  :■»  C  —  Zero; 

ELSE 

Error  (Op.Loc,  SizeErr); 

RETURN; 

END; 

ELSIF  Oper [0]  -  'D'  THEN 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
Op.X  Dreg; 

Op.Xn  C  -  Zero; 

ELSE 

Error  (Op.Loc,  SizeErr); 

RETURN; 

END; 

ELSE 

Error  (Qp.Loc,  AddrErr); 

RETURN- 

END; 

IF  (TempOp [1]  -  ’P')  AND  (TempOp [2]  -  ’C*)  THEN 
Op. Mode  : -PCDisX; 

RETURN; 

ELSIF  (TempOp ( 1 ]  -  'S')  AND  (TempOp(2]  -  ’P’)  THEN 
(*  Stack  Pointer  *) 

Op . Rn  : -  7; 

Op. Mode  : -  ARDisX; 

RETURN; 

ELSIF  TempOp (1]  -  ’A’  THEN 
C  ORD  (TempOp [2]); 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
Op.Rn  C  -  Zero; 

Op. Mode  ARDisX; 

RETURN; 

ELSE 

Error  (Op.Loc,  SizeErr); 

RETURN; 

END; 

ELSE 

Error  (Qp.Loc,  AddrErr); 

RETURN; 

END; 

ELSE  (*  No  Index  *) 

IF  (TempOpfl]  -  'P'J  AND  (TempOp|2]  -  'C’)  THEN 
Op. Mode  PCDisp; 

RETURN; 

ELSIF  (TempOp ( 1)  -  ’S’)  AND  (TempOp[2J  -  ’P1)  THEN 
(*  Stack  Pointer  *) 

Op. Mode  ARDisp; 

Op.Rn  7; 

RETURN; 

ELSIF  TempOp [1]  -  'A'  THEN 


C  ORD  (TempOp ( 2) ); 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
Op.Rn  C  -  Zero; 

Op  .Mode  : -  ARDisp; 

RETURN; 

ELSE 

Error  (Op.Loc,  SizeErr); 

RETURN; 

END; 

ELSE 

Error  (Op.Loc,  AddrErr); 

RETURN; 

END; 

END; 

END; 

(*  Check  to  see  if  this  could  be  a  register  list  for  MOVEM ;  *) 
i  0; 

MultFlag  FALSE; 

LOOP 

ch  Oper(i) ;  INC  (i) ; 

IF  ch  -  0C  THEN 

MultFlag  FALSE; 

EXIT; 

END; 

IF  (ch  -  ’A1)  OR  (ch  -  ’D')  THEN 

ch  Oper ( 1 ) ;  INC  (i) ;  C  ORD  (ch); 

IF  ch  -  0C  THEN 

MultFlag  FALSE; 

EXIT; 

END; 

IF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
ch  Oper [ i] ;  INC  (i) ; 

IF  ch  -  0C  THEN 
EXIT 
END; 

IF  (ch  -  •/*)  OR  (ch  -  ’-')  THEN 
MultFlag  TRUE; 

END; 

ELSE 

MultFlag  FALSE; 

EXIT; 

END; 

ELSE 

MultFlag  FALSE; 

EXIT; 

END; 

END; 

IF  MultFlag  THEN 

Op. Mode  MultiM; 

RETURN; 

END; 

(*  Must  be  absolute  mode!  *) 

IF  Pass2  THEN 

GetValue  (Oper,  Op. Value) ; 

END; 

IF  AbsSize  -  Word  THEN 
Op. Mode  :■  AbsW; 

ELSE 

Op. Mode  : “  AbsL; 

END; 

END  GetOperand; 


PROCEDURE  GetMultReg  (Oper  :  OPERAND;  PreDec  :  BOOLEAN; 

Loc  :  CARDINAL;  VAR  MultExt  :  BITSET) ; 

(*  Builds  a  BITSET  marking  each  register  used  in  a  MOVEM  instruction  *) 


TYPE 

MReg  -  (DO,  Dl,  D2,  D3,  D4,  D5,  D6,  D7, 
A0,  Al,  A2,  A3,  A4 ,  A5,  A6,  A7); 


i,  j  :  CARDINAL; 
ch  :  CHAR; 

C  :  CARDINAL;  (*  ORD  value  of  ch  *) 

Tl,  T2  ;  MReg;  (*  Temporary  variables  for  registers  *) 

RegStack  :  ARRAY  [0..15]  OF  MReg;  (•  Holds  specified  registers  *) 

SP  :  CARDINAL;  (•  Pointer  for  Register  Stack  *) 

RegType  :  (D,  A,  Nil) ; 

Range  :  BOOLEAN; 

BEGIN 

SP  0; 

Range  : •  FALSE; 

RegType  Nil; 
i  0; 

ch  Oper (i] ; 

WHILE  ch  «  0C  DO 
IF  SP  >  15  THEN 

Error  (Loc,  SizeErr) ; 

RETURN; 

END; 

C  ORD  (ch) ; 

IF  ch  -  ’A’  THEN 

IF  RegType  -  Nil  THEN 
RegType  : -  A; 

ELSE 

Error  (Loc,  OperErr) ; 

RETURN; 

END; 

ELSIF  ch  -  'D '  THEN 

IF  RegType  -  Nil  THEN 
RegType  : -  D; 

ELSE 

Error  (Loc,  OperErr) ; 

RETURN; 

END; 

ELSIF  (C  >-  Zero)  AND  (C  <-  Seven)  THEN 
IF  RegType  «  Nil  THEN 

T2  VAL  (MReg,  (ORD  (RegType)  *  8)  +  (C  -  Zero) ) ; 

IF  Range  THEN 

Range  FALSE; 

Tl  RegStack [SP  -  1];  {*  retreive  1st  Reg  in  range  *) 

FOR  j  (ORD  (Tl)  +  1)  TO  ORD  (T2)  DO 
RegStack [SP]  VAL  (MReg,  j) ; 

INC  (SP); 

END; 

ELSE 

RegStack [SP]  T2; 

INC  (SP)  ; 

END; 

ELSE 

Error  (Loc,  OperErr) ; 
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END; 

ELS  IF  ch  -  THEN 

IF  (Range  -  FALSE)  AND  (RegType  #  Nil)  AND  (i  >  0)  THEN 
RegType  Nil; 

Range  TRUE; 

ELSE 

Error  (Loc,  OperErr); 

RETURN; 

END; 

ELS  IF  ch  -  '/'  THEN 

IF  (Range  -  FALSE)  AND  (RegType  #  Nil)  AND  (i  >  0)  THEN 
RegType  Nil; 

ELSE 

Error  (Loc,  OperErr); 

RETURN; 

END; 

ELSE 

Error  (Loc,  OperErr) ; 

RETURN; 

END; 

INC  (i); 
ch  Oper (i] ; 

END; 

MultExt 

FOR  j  0  TO  SP  -  1  DO 
C  ORD  (RegStack [ j] ) ; 

IF  PreDec  THEN 
C  15  -  C; 

END; 

INCL  (MultExt,  C) ; 

END; 

END  GetMultReg; 

END  SyntaxAnalyzer . 


End  Listing  Eighteen 


Listing  Nineteen 


IMPLEMENTATION  MODULE  Listing; 

(*  Creates  a  program  listing,  including  Addresses,  Code  &  Source.  *) 

FRCM  Files  IMPORT 
FILE,  Write; 

FRCM  LongNumbers  IMPORT 
LONG,  LongPut; 

FRCM  Parser  IMPORT 
TOKEN,  Line; 

FRCM  SymbolTable  IMPORT 
ListSymTab; 

FRCM  Conversions  IMPORT 
CardToStr; 

IMPORT  ASCII; 


CONST 

LnMAX  -  55; 


VAR 

LnCnt  :  CARDINAL;  (*  counts  number  of  lines  per  page  *) 

PgCnt  :  CARDINAL;  (*  count  of  page  numbers  *) 


PROCEDURE  WriteStrF  (f  :  FILE;  Str  :  ARRAY  OF  CHAR) ; 
(*  Writes  a  string  to  the  file  *) 

VAR 

i  t  CARDINAL; 

BEGIN 

i  s-  0; 

WHILE  Str (i]  «  0C  DO 
Write  (f,  S tr  [ i ] )  ; 

INC  (1); 

END; 

END  WriteStrF; 


PROCEDURE  StartListing  (f  :  FILE) ; 

(*  Sign  on  messages  for  listing  file  —  initialize  *) 

BEGIN 

Write  (f,  ASCII.ff);  (*  Start  on  a  clean  page  *) 

WriteStrF  (f,  "  68000  Cross  Assembler"); 

Write  (f,  ASCII.cr); 

Write  (f,  ASCI  I. If); 

WriteStrF  (f,  "  Copyright  (c)  1985  by  Brian  R.  Anderson"); 

Write  (f,  ASCII.cr); 

Write  (f,  ASCI I. If); 

Write  (f,  ASCII.cr); 

Write  (f,  ASCI  I. If); 


LnCnt  1; 
PgCnt  1; 

END  StartListing; 


PROCEDURE  WriteListLine  (f  :  FILE; 

AddrCnt ,  ObjOp,  ObjSrc,  ObJDest  :  LONG; 

nA,  nO,  nS,  nD  :  CARDINAL) ; 

(*  Writes  one  line  to  the  Listing  file.  Including  Object  Code  *) 

CONST 

ObjMAX  -  30; 


i  :  CARDINAL; 

BEGIN 

IF  nA  -  0  THEN  (*  nA  is  always  either  0  or  6.  Address  field  -  8  *) 
FOR  i  1  TO  8  DO 
Write  (f,  •  ’); 

END; 

ELSE 

LongPut  (f,  AddrCnt,  6); 

Write  (f,  '  '); 

Write  (f,  •  •); 

END; 

LongPut  (f,  Ob jOp,  nO) ; 

LongPut  (f,  ObjSrc,  nS); 

LongPut  (f ,  Ob jDest,  nD) ; 
i  8  +  nO  +  nS  +  nD; 

WHILE  i  <  ObjMAX  DO 
Write  (f,  •  '); 

INC  (i); 

END; 


WriteStrF  (f,  Line); 
Write  (f,  ASCII.cr); 
Write  (f,  ASCI  I. If); 

CheckPage  (f ) ; 

END  WriteListLine; 


PROCEDURE  WriteSymTab  (f  :  FILE;  NumSym  :  CARDINAL); 

(*  Lists  symbol  table  in  alphabetical  order  *) 

VAR 

uabel  :  TOKEN; 

Value  :  LONG; 
i  :  CARDINAL; 

BEGIN 

LnCnt  1; 

INC  (PgCnt); 

WriteStrF  (f,  "  *  *  *  Symbolic  Reference  Table  *  *  *"); 

FOR  1  1  TO  3  DO 

Write  (f,  ASCII.cr); 

Write  (f,  ASCII. If )  ; 

END; 

FOR  i  1  TO  NumSym  DO 

ListSymTab  (i.  Label,  Value); 

WriteStrF  (f,  Label); 

WriteStrF  (f,  "  :  "); 

LongPut  (f.  Value,  8) ; 

Write  (f,  ASCII.cr); 

Write  (f,  ASCII . If)  ; 

CheckPage  (f)  ; 

END; 

Write  (f,  ASCII.ff); 

END  WriteSymTab; 


PROCEDURE  CheckPage  (f  :  FILE) ; 

(*  Checks  if  end  of  page  reached  yet  —  if  so,  advances  to  next  page.  *) 
VAR 

i  :  CARDINAL; 

PgCntStr  :  ARRAY  [0..6]  OF  CHAR; 

BEGIN 

INC  (LnCnt); 

IF  LnCnt  >-  LnMAX  THEN 
LnCnt  1; 

INC  (PgCnt) ; 

Write  (f,  ASCII.ff);  (*  Form  Feed  for  new  page  *) 

IF  CardToStr  (PgCnt,  PgCntStr)  THEN  (*  Print  New  Page  Number  *) 
FOR  1  j-  1  TO  60  DO 
Write  (f,  •  •); 

END; 

WriteStrF  (f ,  "Page  ") ; 

WriteStrF  (f,  PgCntStr); 

END; 

FOR  i  1  TO  3  DO 

Write  (f,  ASCII.cr); 

Write  (f,  ASCI I. If ); 

END; 

END; 

END  CheckPage; 


End  Listing  Nineteen 


Listing  Twenty 


IMPLEMENTATION  MODULE  Srecord; 

(*  Creates  Motorola  S-records  of  program:  *) 
(*  SO  -  header  record,  *) 
(*  S2  -  code/data  records  (24  bit  address),  *) 
(*  S8  -  termination  record  (24  bit  address).  *) 


FRCM  Files  IMPORT 
FILE,  Write; 

FRCM  Strings  IMPORT 
Length; 
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FRCM  LongNumbers  IMPORT 

PROCEDURE  GetXdata; 

LONG,  LongAdd,  LongSub,  Longlnc,  LongDec,  LongClear, 

(•  Transfer  Xdata  into  new  Sdata  line  —  N.B.:  Xdata  stored  in  reverse  *) 

LongCompare,  CardToLong,  LongPut; 

VAR 

IMPORT  ASCII; 

i  :  CARDINAL; 

T  :  LONG; 

CONST 

BEGIN 

CountMAX  -  16; 

i  1; 

SrecMAX  -  CountMAX  *  2; 

XrocMAX  -  SrecMAX; 

T  LZero; 

(*  No  need  for  either  of  the  tests  (CountMAX  or  Boundary)  *) 

(•  used  in  AppendSdata.  GetXdata  is  only  ever  called  *) 

VAR 

(*  after  DumpSdata  and  is  therefore  only  putting  (up  to  20)  *) 

StartAddr  :  LONG;  (*  address  that  record  starts  on  *) 

(*  HEX  digits  in  an  empty  buffer  (which  could  hold  32) .  *) 

TempAddr  :  LONG;  (*  running  address  of  where  we  are  now  *) 

WHILE  i  <  Xindex  DO 

Checksum  :  LONG; 

Sdata [Sindex]  Xdata [ i] ; 

Count  ;  CARDINAL;  (*  count  of  HSX-pairs  in  S-record  *) 

Sdata [Sindex  -  1]  Xdata[i  +1]; 

Sdata  :  ARRAY  [1.. SrecMAX]  OF  INTEGER;  (*  S-record  data,  HEX  digits  *) 

T [2]  Sdata [Sindex] ;  T[l]  Sdata [Sindex  -  1]; 

Sindex  :  CARDINAL;  (*  index  for  Sdata  array  *) 

LongAdd  (T,  Checksum,  Checksum) ; 

Xdata  :  ARRAY  [l..XrecMAX]  OF  INTEGER;  (*  Overflow  for  Sdata  *) 

INC  (i,  2); 

Xindex  :  CARDINAL;  (*  index  for  Xdata  array  *) 

DEC  (Sindex,  2) ; 

Boundary  :  BOOLEAN;  (*  marks  Address  MOD  16  boundary  of  S-record  *) 

INC  (Count) ; 

LZero  :  LCWG;  (*  used  as  a  constant  «  0  *) 

Longlnc  (TempAddr,  1) ; 

END; 

Xindex  0; 

PROCEDURE  Complement;  (*  Checksum  *) 

END  GetXdata; 

BEGIN 

LongSub  (LZero,  Checksum,  Checksum);  (*  2's  Complement  *) 

LongDec  (Checksum,  1);  (*  Make  it  l's  Complement  *) 

END  Complement; 

PROCEDURE  StartSrec  (f  :  FILE;  SourceFN  :  ARRAY  OF  CHAR); 

(*  Writes  SO  record  (HEADER)  and  initializes  *) 

VAR 

PROCEDURE  AppendSdata  (Data  :  LONG;  n  :  CARDINAL)  :  BOOLEAN; 

(*  Transfers  data  to  Sdata,  and  updates  Count  £  Checksum.  *) 

(*  If  no  room:  Data  goes  to  Xdata  &  FALSE  returned.  •) 

T  :  LONG;  (•  temporary  •) 

i  :  CARDINAL; 

BEGIN 

VAR 

Write  (f,  ’S’); 

T  :  LONG;  (*  temporary  —  used  only  as  a  2  digit  HEX  number  *) 

Write  (f,  ’O’); 

BEGIN 

Checksum  LZero; 

T  LZero; 

Count  Length  (SourceFN)  +3;  (*  extra  for  Address  £  Checksum  *) 

CardToLong  (Count,  T) ; 

WHILE  (n  1  0)  AND  (Count  #  CountMAX)  AND  (NOT  Boundary)  DO 

LongPut  (f,  T,  2); 

Sdata [Sindex]  Data(n]; 

Sdata [Sindex  -  1]  Data[n  -  1]; 

LongAdd  (T,  Checksum,  Checksum); 

LongPut  (f,  LZero,  4);  (*  Address  is  4  digit,  all  zero,  for  SO  *) 

T [2 ]  Data(n];  T [ 1)  Data[n  -  1]; 

LongAdd  (T,  Checksum,  Checksum) ; 

i  0; 

WHILE  SourceFN [i]  #  0C  DO 

DEC  (n,  2); 

CardToLong  (ORD  (SourceFN [ i ]) ,  T) ; 

DEC  (Sindex,  2); 

LongAdd  (T,  Checksum,  Checksum) ; 

INC  (Count) ; 

LongPut  (f,  T,  2) ; 

INC  (i); 

Longlnc  (TempAddr,  1) ; 

IF  TempAddr [1]  -  0  THEN  (*  i.e.,  TempAddr  MOO  16-0  •) 

END; 

Boundary  TRUE; 

Complement;  (*  Checksum  •) 

END; 

LongPut  (f.  Checksum,  2) ; 

END; 

Write  (f,  ASCII.cr); 

IF  (Count  -  CountMAX)  OR  (Boundary)  THEN 

Write  (f,  ASCI  I. If); 

WHILE  n  >  0  DO  (*  Add  Data  to  Xdata  (in  reverse)  *) 

INC  (Xindex) ; 

Sindex  SrecMAX; 

Xdata [ Xindex]  Data[n]; 

Xindex  0; 

DEC  (n); 

Count  0; 

END; 

Boundary  FALSE; 

Checksum  LZero; 

RETURN  FALSE;  (*  Sdata  is  full  *) 

StartAddr  LZero; 

ELSE 

TempAddr  LZero; 

RETURN  TRUE; 

END  StartSrec; 

END; 

END  AppendSdata; 

PROCEDURE  WriteSrecLine  (f  :  FILE; 

AddrCnt,  ObjOp,  ObjSrc,  ObjDest  :  LONG; 

PROCEDURE  DumpSdata  (f  :  FILE); 

nA,  nO,  nS,  nD  :  CARDINAL) ; 

(*  Writes  am  S2  record  to  the  file  •) 

(*  Collects  Object  Code  —  Writes  an  S2  record  to  file  if  line  is  full  *) 

VAR 

VAR 

T  ;  LONG;  (*  temporary  —  used  to  output  Count  £  Checksum  *) 

i,  j  :  CARDINAL; 

dummy  :  BOOLEAN; 

BEGIN 

BEGIN 

IF  nA  -  0  THEN 

IF  Count  -  0  THEN 

RETURN;  (*  Nothing  to  add  to  S-record  *) 

RETURN;  (*  nothing  to  dump  *) 

END; 

END; 

IF  Xindex  #  0  THEN 

Write  (f,  ’S'); 

GetXdata;  (*  transfers  Xdata  into  Sdata  *) 

Write  (f,  ’2’); 

END; 

CardToLong  (Count  +  4,  T) ;  (*  extra  for  Address  &  Checksum  *) 

IF  LongCompare  (AddrCnt,  TempAddr)  #  0  THEN 

LongPut  (f,  T,  2); 

DumpSdata  (f)  ; 

LongAdd  (T,  Checksum,  Checksum);  (»  Add  Count  to  Checksum  *) 

END; 

LongPut  (f,  StartAddr,  6); 

IF  Count  -  0  THEN 

(*  Add  Address  to  Checksum  *) 

StartAddr  AddrCnt; 

T  LZero; 

TempAddr  AddrCnt; 

T ( 1 ]  StartAddr [ 1] ;  T[2]  StartAddr [ 2] ; 

END; 

LongAdd  (T,  Checksum,  Checksum); 

T [ 1 ]  StartAddr [3] ;  T [ 2 ]  StartAddr [4] ; 

dummy  AppendSdata  (ObjOp,  nO) ; 

LongAdd  (T,  Checksum,  Checksum); 

dummy  AppendSdata  (ObjSrc,  nS) ; 

T [ 1]  StartAddr [ 5] ;  T [ 2 ]  StartAddr [ 6] ; 

IF  NOT  AppendSdata  (ObjDest,  nD)  THEN 

LongAdd  (T,  Checksum,  Checksum); 

DumpSdata  (f)  ; 

END; 

IF  Count  <  CountMAX  THEN  (*  adjust  short  record  —  shuffle  down  *) 

j  1; 

FOR  i  Sindex  +  1  TO  SrecMAX  DO 

END  WriteSrecLine; 

Sdata [j]  Sdata [i]; 

INC  (j); 

PROCEDURE  Ends re c  (f  :  FILE) ; 

END; 

END; 

LongPut  (f,  Sdata,  Count  *  2);  (*  S-record  Code/Data  •) 

(*  Finishes  off  any  left-over  (Partial)  S2  line,  *) 

(*  and  then  writes  S8  record  (TRAILER)  *) 

BEGIN 

IF  Xindex  f  0  THEN 

Complement;  (*  Checksum  *) 

GetXdata; 

LongPut  (f,  Checksum,  2) ; 

END; 

Write  (f,  ASCII.cr); 

Write  (f,  ASCII. If); 

DumpSdata  (f); 

Write  (f,  ’S');  (*  Fixed  format  for  S8  record  *) 

Longlnc  (StartAddr,  Count) ; 

Write  (f,  ’8’); 

Sindex  SrecMAX; 

Write  (f,  ’O’); 

Count  0; 

Write  (f,  ’4’); 

Boundary  FALSE; 

Write  (f,  ’O’); 

Checksum  LZero; 

END  DumpSdata; 

“JitH  !f'  J  (continued  on  page  62) 
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68K  ASSEMBLER 


Listing  Twenty  (listing  continued) 


Write  (f,  ’O'); 

Write  (f,  ’O’); 

Write  (f,  'O’); 

Write  (f,  'F'); 

Write  (f,  'C') ; 

Write  (f,  ASCII.cr); 
Write  (f,  ASCII.lf); 
Write  (f,  ASCII.cr); 
Write  (f,  ASCII.lf); 
END  EndSrec; 

BEGIN  (*  Initialization  *) 
LongClear  (LZero); 

END  Srecord. 


End  Listing  Twenty 


|  EndErr  :  WriteString  ("Missing  END  Pseudo-Op."); 
ELSE 

WriteString  ("Unknown  Error."); 

END; 

WriteLn; 

IF  FirstTime  THEN 

WriteString  ("Hit  any  key  to  continue....  "); 
Terminal. Read  (c)  ; 

WriteLn; 

FirstTime  FALSE; 

ELSE 

Terminal. Read  (c)  ; 

END; 

INC  (ErrorCount)  ; 

IF  ErrorCount  >500  THEN 

WriteString  ("Too  many  errors!");  WriteLn; 
WriteString  ("Program  Terminated.");  WriteLn;. 
HALT; 

END; 

END  Error; 


Listing  Twenty-One 


IMPLEMENTATION  MODULE  ErrorX68; 

(*  Displays  error  messages  for  X68000  cross  assembler  *) 

FROM  Terminal  IMPORT 
WriteString,  WriteLn; 


IMPORT  Terminal; 


FROM  Files  IMPORT 
FILE; 


(*  for  Read/Write  *) 


IMPORT  Files; 


(*  for  Write  *) 


FRCM  Strings  IMPORT 
Length; 


FRCM  Parser  IMPORT 
Line,  LineCount; 


TYPE 

ErrorType  -  (Dummy,  TooLong,  NoCode,  SymDup,  Undef,  SymFull,  Phase, 
ModeErr,  OperErr,  BraErr,  AddrErr,  SizeErr,  EndErr); 

VAR 

ErrorCount  :  CARDINAL; 


FirstTime  :  BOOLEAN; 


PROCEDURE  FileWriteString  (f  :  FILE;  VAR  Str  :  ARRAY  OF  CHAR) ; 


BEGIN 

i  0; 

WHILE  Str [i]  #  0C  DO 

Files. Write  (f,  Str(i]) 
INC  (i); 

END; 

END  FileWriteString; 


PROCEDURE  Error  (Pos  :  CARDINAL;  ErrorNbr  :  ErrorType) ; 

(*  Displays  Error  #ErrorNbr,  then  waits  for  any  key  to  continue  *) 


PROCEDURE  WriteErrorCount  (f  :  FILE) ; 

Error  count  output  to  Console  &  Listing  file  *) 


CntStr  :  ARRAY  [0..6]  OF  CHAR; 

MsgO  :  ARRAY  [0..25]  OF  CHAR; 

Msgl  :  ARRAY  [0..10]  OF  CHAR; 

Msg2  :  ARRAY  [0..20]  OF  CHAR; 
dummy  ;  BOOLEAN; 

BEGIN 

MsgO  " - >  END  OF  ASSEMBLY"; 

Msgl  :*»  " - >  "; 

Msg2  "  ASSEMBLY  ERROR  (S)."; 

dummy  CardToStr  (ErrorCount,  CntStr); 

(*  Messages  to  console  *) 

WriteLn; 

WriteLn; 

WriteString  (MsgO) ;  WriteLn; 
WriteString  (Msgl) ; 

WriteString  (CntStr) ; 

WriteString  (Msg2) ; 

WriteLn; 

(*  Messages  to  listing  file  *) 

Files. Write  (f,  ASCII.cr); 

Files. Write  (f,  ASCII. If); 

Files. Write  (f,  ASCII.cr); 

Files. Write  (f,  ASCII.lf); 

FileWriteString  (f,  MsgO); 

Files. Write  (f,  ASCII.cr); 

Files. Write  (f,  ASCII.lf); 

FileWriteString  (f,  Msgl); 
FileWriteString  (f,  CntStr); 
FileWriteString  (f,  Msg2); 

Files. Write  (f,  ASCII.cr); 

Files. Write  (f,  ASCII.lf); 

Files. Write  (f,  ASCII.ff);  (*  feed  up 
END  WriteErrorCount; 


( *  feed  up  next  page  * ) 


BEGIN  (•  MODULE  Initialization  ») 
FirstTime  TRUE; 

ErrorCount  0; 

END  ErrorX68 . 


i  :  CARDINAL; 
c  :  CHAR; 

CntStr  :  ARRAY  (0..6]  OF  CHAR; 
dummy  :  BOOLEAN; 

BEGIN 

WriteLn; 

dummy  CardToStr  (LineCount,  CntStr) ; 
WriteString  (CntStr) ; 

WriteString  ("  "); 

WriteString  (Line) ;  WriteLn; 

(■*  Make  up  for  LineCnt  so  A  in  right  spot  *) 
FOR  i  1  TO  Length  (CntStr)  DO 
Terminal. Write  ('  '); 

END; 

WriteString  ("  "); 

IF  Pos  >  0  THEN 

FOR  i  1  TO  Pos  DO 

Terminal. Write  (’  '); 

END; 

Terminal. Write  (,A');  WriteLn; 

END; 


End  Listings 


CASE  ErrorNbr  OF 

TooLong  :  WriteString 
|  NoCode  ;  WriteString 
j  SymDup  :  WriteString 
I  Undef  :  WriteString 
|  SymFull  :  WriteString 
WriteLn; 
WriteString 
HALT; 

|  Phase  :  WriteString 
j  ModeErr  :  WriteString 
I  OperErr  :  WriteString 
j  BraErr  :  WriteString 
|  AddrErr  :  WriteString 
I  SizeErr  :  WriteString 


("Identifier  too  long  —  Truncated!"); 

("No  such  op-code."); 

("Duplicate  Symbol."); 

("Undefined  Symbol."); 

("Symbol  Table  Full  —  Maximum  -  500!"); 

("Program  Terminated.");  WriteLn; 

("Pass  1/Pass  2  Address  Count  Mis-Match . " ) ; 
("This  addressing  mode  not  allowed  here."); 
("Error  in  operand  format."); 

("Error  in  relative  branch."); 

("Address  mode  error."); 

("Operand  size  error."); 
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DDJ  ON  LINE 


Listing  One  (Text  begins  on  page  16.) 


PERMG  for  the  68000.  Inversely  permute  a  256-bit  bit 
vector,  BLOCK,  by  table  BITPERM.  On  call: 

aO  ->  BLOCK,  a  32-byte  area 

al  ->  BITPERM,  a  table  of  byte  values  in  0. .255 

On  return,  aO  ->  permuted  BLOCK 
All  registers  saved 

Register  usage: 

a2  ->  WORK,  a  32-byte  temporary  work  area 
a3  ->  BLOCK 

dO  =  outer  loop  counter 
dl  -  inner  loop  counter 
d3  -  longword  from  BLOCK 
d4  -  byte  from  BITPERM 
d5  -  temporary 

d6  -  #7,  immediate  masking  value 


move . 1  (a2)+,  (a3)+  move  WORK  to  BLOCK 

dbf  d6,movloop  use  #7  already  in  d6 

movem.l  (a7 ) +, d0-d6/a0-a3 
rts  all  done 


(al,d2)  ,d4 

d4,d5 

*3,d4 

d6,d5 

d6,d5 

d5,  (a2,d4) 

permg2 


get  byte  BITPERM [COUNT] 
save  for  reuse 
index  to  byte  of  WORK 
compute  bit  *  in  that  byte 
reverse  bit  order 
set  the  bit  in  WORK 
re-enter  main  loop 


Version  of  3/22/86.  Executes  in  4 


.globl  permg 
.globl  work 


on  8  MHz  system. 


End  Listing  One 


movem.l 

d0-d6/a0-a3. 

-<a7) 

moveq 

*7,  dO 

clear  work  area 

lea 

work, a2 

clr.l 

(a2)  + 

dbf 

d0,clrloop 

lea 

work, a2 

init  registers 

move . 1 

aO,  a3 

save  block  addr  for 

later 

moveq 

#7,d0 

outer  loop  control 

moveq 

*0,d2 

count  of  bits 

move 

d2,d4 

need  word  clear 

move 

d2,d5 

need  word  clear 

moveq 

*7,d6 

masking  value 

moveq 

#31, dl 

inner  loop  control 

move . 1 

(a0)+,d3 

get  longword  from  BLOCK 

btst 

dl,d3 

check  for  bit  on 

brie 

setbit 

if  on,  set  BITPERM [d2 ]  bit  in  WOP 

addq 

#1,  d2 

. . .else,  bump  count 

dbf 

dl,bitloop 

and  do  for  all  bits 

in  this  word 

dbf 

dO,  permgl 

do  for  all  words  of 

BLOCK 

Listing  Two 


PERMF  for  the  68000.  Permute  a  256-bit  bit  vector,  BLOCK 
by  table  BITPERM.  On  call: 

aO  ->  BLOCK,  a  32-byte  area 

al  ->  BITPERM,  a  table  of  byte  values  in  0..255 

On  return,  aO  ->  permuted  BLOCK. 

All  registers  saved. 

Register  usage: 

a2  ->  WORK,  a  32-byte  temporary  work  area 

dO  -  byte  from  BITPERM,  shifted  to  bit  index 

dl  -  index  to  byte  of  BLOCK 

d2  -  #3,  immediate  shift  value 

d3  -  identifies  bit  in  WORK  to  change 

d4  -  loop  counter  for  BITPERM  values 

d5  -  identifies  bit  in  WORK  to  change 

d6  -  *7,  immediate  masking  value 

d7  -  temporary 

Version  of  3/22/86.  Execution  time  at  8  MHz  -  6  ms. 

.globl  perraf 
.globl  work 


movem.l  dO-d7/aO-a2, - (a7) 


*7,  dO 
work, a2 

(a2)  + 

d0,clrloop 

work,a2 

♦  0,  d3 

*255, d4 

#7,d6 

#3,d2 

dO 

(al)  +,  dO 
dO,  dl 
d2,  dl 
d6,d0 
d6,  dO 
dO,  (aO, dl ) 
permf2 

*1,  d3 

d4,permloop 


clear  work  area 


init  counter  to  bits  in  WORK 
init  BITPERM  loop  counter 
masking  value 
shift  value 


get  byte  from  BITPERM 
we  will  need  it  twice 
compute  byte  index  in  BLOCK 
save  lower  3  bits  for  bit  index 
reverse  bit  order  for  btst 
is  bit  on  in  BLOCK? 
if  so,  we  must  set  bit  in  WORK 

else,  next  bit  of  WORK 
and  next  byte  of  BITPERM 


move . 1  (a2)+,  (a0)+  move  WORK  to  BLOCK 

dbf  d6,movloop  use  #7  already  in  d6 

movem.l  (a7) +,d0-d7/a0-a2 
rts  all  done 


d3,d5  if  BLOCK  bit  is  on... 

d2,d5  find  permuted  bit  in  WORK.. 

d3,d7  save  d3  for  counter 

d6,d7  save  lower  3  bits 

d6,d7  reverse  bit  order  for  bset 

d7,  (a2,d5)  set  desired  bit  in  WORK 

permfl  re-enter  main  loop 


bset  d7, (a2,d5) 


End  Listings 
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_ C  CHEST 

Listing  One  (Text  begins  on  page  22.) 

1  /* 

2  *  SORT.C 

3  * 

4  *  Copyright  (c)  1986  Allen  I.  Holub 

5  *  All  rights  reserved. 

6  */ 

7 

8  • include  <stdlo.h> 

9  # include  <ct;ype.h> 

10  # include  <getargs.h> 

11 

12  extern  char  *malloc(); 

13 

15  *  General  purpose  idefines. 

16  */ 

17 


18 

idefine 

MAXBUF 

(132  +  1) 

/* 

Maximum  input  line  length  +1 

*/ 

19 

idefine 

MAXLINEC 

1024 

/* 

Maximum  number  of  lines  in 

*/ 

20 

/* 

an  input  file  before  merge 

*/ 

21 

/* 

files  start  to  be  created 

*/ 

22 

idefine 

MAXTMP 

18 

/* 

The  maximum  number  of  temp¬ 

*/ 

23 

/* 

orary  files  that  will  be 

*/ 

24 

/* 

created.  Note  that  fp's  are 

*/ 

25 

/* 

needed  for  stdout,  and 

*/ 

26 

27 

28 

/* 

stderr  during  output 

*/ 

idefine 

isnum(cl) 

(  isdigit (cl) 

||  (cl)  ==  ) 

29 

30  /* - 

31  *  Variables  for  getargs.  The  immediately  following  variables  will 

32  *  be  modified  by  getargs ()  according  to  what  flags  it  finds  on  the 

33  *  command  line. 

34  V 

35 


36 

static 

int 

Noblanks 

= 

0 

/* 

Blanks  don't  count 

*/ 

37 

static 

int 

Numeric 

= 

0 

/* 

Sort  numbers  by  val 

*/ 

38 

static 

int 

Primary 

= 

0 

/* 

Primary  sort  key 

V 

39 

static 

int 

Secondary 

0 

/* 

Secondary  sort  key 

*/ 

40 

static 

int 

Dictorder 

= 

0 

/* 

Use  dictionary  order 

V 

41 

static 

int 

Foldupper 

- 

0 

/* 

Fold  upper  case 

V 

42 

static 

int 

Reverse 

0 

/* 

Sort  in  reverse  order 

*/ 

43 

static 

int 

Delim 

0 

/* 

Field  separator 

*/ 

44 

static 

char 

*Mdir 

= 

■III 

/* 

Put  temp  files  here 

*/ 

45 

static 

int 

Nodups 

= 

0 

/* 

Don't  print  duplicate 

V 

46 

/* 

lines. 

V 

47 

ARG 

Argt 

ab[]  = 

48  { 


49 

50 

51 

/*  arg 

type 

variable 

error  message  string  */ 

i 

■b' 

BOOLEAN, 

&Noblanks, 

"ignore  leading  whitespace  (Blanks)" 

), 

52 

i 

'd' 

BOOLEAN, 

iDictorder, 

"sort  in  Dictionary  order" 

i. 

53 

i 

'  f ' 

BOOLEAN, 

fiFoldupper, 

"Fold  upper  into  lower  case" 

i, 

54 

t 

'n' 

,  BOOLEAN, 

^Numeric, 

"sort  Numbers  by  numeric  value" 

i. 

55 

i 

•p' 

,  INTEGER, 

iPrimary, 

"use  field  <num>  as  Primary  key" 

i, 

56 

i 

'r ' 

,  BOOLEAN, 

&Reverse, 

"do  a  reverse  sort" 

i, 

57 

i 

's' 

,  INTEGER, 

& Secondary, 

"use  field  <num>  as  Secondary  key" 

i. 

58 

i 

't ' 

,  CHARACTER, 

&Delim, 

"use  <C>  to  separate  fields" 

i. 

59 

i 

.T. 

,  STRING, 

(int*)  &Mdir 

"prepend  <str>  to  Temp  file  names" 

i. 

60 

i 

•u' 

,  BOOLEAN, 

&Nodups, 

"delete  duplicate  lines  in  output" 

61  }; 

62 

63  Idefine  NUMARGS  (sizeof  (Argtab)  /  sizeof(ARG)) 

64 


65 

66 

Global  • 

variables.  The  Lines 

array  is  used  for  the  initial 

67 

* 

sorting 

68 

V 

69 

70 

static 

int 

Options; 

/* 

Set  by  main  if  any  options  set 

*/ 

71 

static 

char 

•Lines  [MAXLINEC  ]  ; 

/* 

Holds  arrays  of  input  lines 

*/ 

72 

static 

int 

Linec; 

/* 

#  of  items  in  Lines 

*/ 

73 

static 

char 

**Argv; 

/* 

Copies  of  argv  and  argc 

*/ 

74 

static 

int 

Argc; 

75 

77  *  The  heap  used  in  the  merge  process: 

78  V 

79 

80  typedef  struct 

81  { 

82  char  string [MAXBUF ) ;  /*  One  line  from  the  merge  file  */ 

83  FILE  *file;  /*  Pointer  to  input  file  */ 

84  } 

85  HEAP; 

86 

87  HEAP  *  Heap  [  MAXTMP  );  /*  The  heap  itself  V 

88 

90 

91  fifndef  DEBUG 

92  idefine  pheap(s,n) 

93  ielse 

94 

95  pheap(  str,  n  ) 

96  char  *str; 


C  CHEST 


Listing  One  (Listing  continued,  text  begins  on  page  22.) 


97  { 


98  int  i; 

99 

100  printf  ("+■ - \n") ; 

101  printf (M|  %s,  heap  is:\n",  str) ; 

102  for(i  =  0;  i  <  n  ;  i++  ) 

103  { 

104  printf (" | %02d:  %s",  i,  *  (Heap [ i } — >st ring)  ? 

105  Heap [i]->st ring  :  M(null)\n"  ); 

106  ) 

107  printf  (“+ - \n") ; 


108  } 

109 

110  #endif 


111 

113 

114  int  dedupe {argc,  argv) 

115  int  argc; 

116  char  **argv; 

117  { 

118  /*  Compress  an  argv-like  array  of  pointers  to  strings  so  that 

119  *  adjacent  duplicate  lines  are  eliminated.  Return  the 

120  *  argument  count  after  the  conpression. 

121  V 

122 

123  register  int  i  ; 

124  int  nargc  ; 

125  char  **dp  ; 

126 

127  nargc  «  1; 

128 

129  dp  »  fiargv [1] ; 

130 

131  for  (  i*=l  ;  i  <  argc  ;  i++  ) 

132  { 

133  if  (  strcmp(argv[i-l] ,  argvfi])  !-  0  ) 

134  { 

135  *dpf+  -  argv[i); 

136  nargc++; 

137  } 

138  } 

139 

140  return (  nargc  ); 

141  } 

142 


144 


145  static  char 

146  int 

147  char 


*skip_field  (n,  str) 
n; 

*str; 


148  { 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161  } 

162 

163  /*- 

164  * 

165  * 

166  * 

167  * 

168  * 

169  * 

170  */ 

171 


/*  Skip  over  n  fields.  The  delimiter  is  in  the  global 

*  variable  Delim.  Return  a  pointer  to  either  the  character 

*  to  the  right  of  the  delimiter,  or  to  the  '\0'. 

*/ 

while (  n  >  0  &&  *str  ) 

{ 

if (  *str++  «■  Delim) 


return (str) ; 


Comparison  functions  needed  for  sorting. 

ssort ()  will  call  either  argvcmp  or  qcmp,  passing  them  pointers 
to  linev  entries.  qcmp()  calls  two  workhorse  functions,  qcmpl  () 
and  qcmp2().  The  workhorse  functions  will  also  be  called  by  the 
reheap ()  subroutine  used  to  manipulate  merge  files. 


172  static 

173  char 

174  { 

175 

176  ) 

177 

178  /* - 

179 


int  argvcmp (  sip, 

**slp,  **s2p; 


return  (  strcmp(  *slp, 


s2p  ) 


*s2p  ) 


); 


180  static  int 

181  char 

182  char 


qcmp(  strip,  str2p  ) 
**strlp; 

**str2p; 


/ 


183  l 

184 

185 

186 

187 

188 

189 

190  ) 

191 


/*  Takes  care  of  all  the  sorting  of  fields,  calling  qanpl 

*  to  do  the  actual  comparisons.  Assuming  here  that 

*  Secondary  won't  be  set  unless  Primary  is  set  too. 

V 

return (  qcmpl (  *strlp,  *str2p  )  ); 
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193 

194  static 

int 

qcmpl (  strl,  str2  ) 

195  char 

196  { 

*strl,  *str2; 

197 

/* 

Workhorse  comparison  function.  Takes  care  of  sorting 

198 

* 

fields.  If  a  primary  sort  field  is  specified  then 

199 

* 

qcnpl  ()  skips  to  that  field  and  calls  qcmp2  to  do  the 

200 

* 

actual  comparison.  If  the  primary  fields  are  equal,  then 

201 

* 

the  secondary  fields  are  compared  in  the  same  way. 

202 

V 

203 

204 

int 

rval; 

205 

206 

if 

[Primary  ) 

207 

return  qanp2  (  strl,  str2  ); 

208 

else 

209 

i 

210 

rval  =  qanp2  (  skip  field  (Primary  -  1,  strl), 

211 

skip  field  (Primary  -  1,  str2)  ); 

212 

213 

if(  !rval  &&  Secondary  ) 

214 

t 

215 

/*  The  two  primary  keys  are  equal,  search  the  */ 

216 

/*  secondary  keys  if  one  is  specified  */ 

217 

218 

rval  =  qcmp2  (  skip  field  (Secondary  -  1,  strl). 

219 

skip  field (Secondary  -  1,  str2)  ); 

220 

i 

221 

222 

return  rval; 

223 

i 

224  } 

225 

227 

228  static 

int 

qanp2  (  strl,  str2  ) 

229  char 

*strl; 

230  char 

231  { 

*str2; 

232 

/* 

Workhorse  comparison  function.  Deals  with  all  command  line 

233 

* 

options  except  fields.  Returns 

234 

* 

235 

* 

0  if  strl  =  str2 

236 

• 

positive  if  strl  >  str2 

237 

* 

negative  if  strl  <  str2 

238 

* 

239 

* 

This  is  a  general  purpose  (and  therefore  relatively  slow) 

240 

* 

routine.  Use  strcmpO  if  you  need  a  fast  compare. 

241 

* 

Comparison  stops  on  reaching  end  of  string  or  on  encountering 

242 

* 

a  Delim  character  (if  one  exists) .  So  make  sure  Delim  is 

243 

* 

set  to  ’\0'  if  you're  not  sorting  by  fields. 

244 

V 

245 

246 

register  unsigned  int  cl,  c2; 

247 

248 

if 

Noblanks  ) 

249 

i 

250 

/* 

251 

*  Skip  past  leading  whitespace  in  both  strings 

252 

V 

253 

254 

while  (  isspace (*strl)  ) 

255 

strl++; 

256 

257 

while  (  isspace (*str2)  ) 

258 

str2++; 

259 

i 

260 

261 

do 

262 

i 

263 

if (  Numeric  &&  isnum(*strl)  &&  isnum(*str2)  ) 

264 

i 

265 

/*  Add  Oxff  to  the  two  numeric  values  so  that 

266 

*  cl  and  c2  can't  be  confused  with  a  Delim 

267 

*  character  later  on. 

268 

*/ 

269 

270 

cl  =  stoi (  istrl  )  +  Oxff  ; 

271 

c2  -  stoi (  &str2  )  +  Oxff  ; 

272 

273 

if (  cl  ==  c2  ) 

274 

continue; 

275 

else 

276 

break; 

277 

) 

278 

279 

cl  *  *strl++; 

280 

c2  =  *str2++; 

281 

282 

if  (Dictorder) 

283 

t 

284 

/*  Skip  past  any  non-alphanumeric  or  blank 

285 

*  characters. 

286 

*/ 

287 

288 

while (  cl  &&  !isalnum(cl)  ) 

289 

cl  -  *strl++  ; 

290 

291 

while (  c2  &&  !isalnum(c2)  ) 

292 

c2  »  *str2++  ; 

293 

i 
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294 

295 

296 

if (Foldupper) 

297 

f 

298 

/*  Map  cl  and  c2  to  upper  case  */ 

299 

300 

cl  -  toupper (cl  ) ; 

301 

c2  =  toupper (  c2  ) ; 

302 

i 

303 

304 

/*  Keep  processing  while  the  characters  are  the  same 

305 

*  unless  we've  reached  end  of  string  or  a  delimiter. 

306 

V 

307 

) 

308 

while ( 

(cl-=c2)  &&  cl  &&  cl  ! ”  Delim  ); 

309 

310 

if(  Delim  )  /*  If  we're  sorting  on  a  field  */ 

311 

i 

/*  and  we've  found  a  delimiter  */ 

312 

if (cl  =*  Delim)  /*  then  map  the  delimiter  to  a  */ 

313 

cl  =  0;  /*  zero  for  purposes  of  * / 

314 

/*  comparison.  */ 

315 

if  (c2  «=  Delim) 

316 

c2  -  0; 

317 

i 

318 

319 

return ( 

Reverse  ?  (c2  -  cl)  :  (cl  -  c2)  ) ; 

320  } 

321 

322  /* - 

— 

- */ 

323 

324  FILE 

*  next  file  () 

325  { 

326 

/* 

Return  a  FILE  pointer  for  the  next  input  file  or  NULL 

327 

* 

if  no  more  input  files  exist  (ie.  all  of  the  files 

328 

* 

on  the  command  line  have  been  processed)  or  a  file 

329 

* 

can't  be  opened.  In  this  last  case  print  an  error  message. 

330 

* 

If  Argc  ==  1  the  first  time  we're  called,  then  standard 

331 

* 

input  is  returned  (the  first  time  only  ,  NULL  is  returned 

332 

* 

on  subsequent  calls) . 

333 

*/ 

334 

335 

FILE 

*fp; 

336 

static 

int  first  time  -  1  ; 

337 

338 

if  (  first  time  ) 

339 

i 

340 

first  time  =  0; 

341 

if (  Argc  ==  1  ) 

342 

return  stdin; 

343 

) 

344 

345 

if  (  Argc —  >  1  ) 

346 

t 

347 

if(  !  (fp  -  fopen (*++Argv,  "r"))  ) 

348 

fprintf (stderr,  "sort:  can't  open  %s  for  read\n". 

349 

*Argv  ) ; 

350 

return  fp; 

351 

i 

352 

353 

return 

NULL; 

354  } 

355 

357 

358  gtext  () 

359  { 

360 

/* 

Get  text  from  the  appropriate  input  source  and  put 

361 

* 

the  lines  into  Linev,  updating  Linec.  Return  non-zero 

362 

* 

if  more  input  remains.  Note  that  non-zero  will 

363 

* 

be  returned  if  there  are  exactly  MAXLINEC  lines  in 

364 

* 

the  input,  even  though  there  isn't  any  more  actual 

365 

* 

input  available.  If  malloc  can't  get  space  for  the  line. 

366 

* 

we'll  remember  the  line  in  buf  and  return  1. 

367 

*/ 

368 

369 

register  int  c; 

370 

static 

FILE  *fp  =  0; 

371 

static 

char  buf [  MAXBUF  ]  -  (0);  /*  Input  buffer  */ 

372 

int 

maxcount; 

373 

char 

**lv; 

374 

375 

if(  !fp  )  /*  This  is  only  true  the  first  */ 

376 

fp  -  nextfile  () ;  /*  time  we're  called.  */ 

377 

378 

lv  -  Lines  ; 

379 

Linec  -  0  ; 

380 

381 

for  (  maxcount  -  MAXLINEC;  — maxcount  >=*  0  ;) 

382 

< 

383 

if(  ! *buf  ) 

384 

while  (  fgets  (buf,  MAX  BUF,  fp)  —  NULL  ) 

385 

if(  !  (fp  =  nextfile () )  ) 

386 

return (  0  );  /*  No  more  input 

387 
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388 

389 

390 

391 

392 

393 

394 

395 

396 

397 

398 

399 
4CC 

401 

402 

403 

404 

405 

406 

407 

408 

409 

410 

411 

412 

413 

414 

415 

416 

417 

418 

419 

420 

421 

422 

423 

424 

425 

426 

427 

428 

429 

430 

431 

432 

433 

434 

435 

436 

437 

438 

439 

440 

441 

442 

443 

444 

445 

446 

447 

448 

449 

450 

451 

452 

453 

454 

455 

456 

457 

458 

459 

460 

461 

462 

463 

464 

465 

466 

467 

468 

469 

470 

471 

472 

473 

474 

475 

476 

477 

478 

479 

480 

481 


if(  *lv  -  malloc (strlen (buf)  +  l)  ) 

( 

strcpy(  *lv++,  buf  ); 

•buf  -  ' \0 ' ; 

Line C++; 

} 

else 

return  1; 

) 

return (  maxcount  <  0  );  /*  Return  1  if  there's  more  input  to  get  V 


/* - V 

char  *fname(  num  ) 

l 

/*  Return  a  merge  file  name  for  the  indicated  merge  pass. 

*/ 

static  char  name[  16  ); 

if (  num  >  MAXTMP  ) 

{ 

fprintf (stderr, "sort;  input  file  too  large\n"  ); 
exit  (1) ; 

} 

sprintf (name,  "%smerge.%d",  Mdir,  num  ); 
return (  name  ); 


/* - - - */ 

outtext (  passnum,  more  to  go  ) 

{ 

/*  Print  out  all  the  strings  in  the  Lines  array  and  free  all 

•  the  memory  that  they  use.  Output  is  sent  to  standard 

•  output  if  this  is  pass  1  and  there's  no  more  input 

•  to  process,  otherwise  output  is  sent  to  a  merge  file. 

V 

register  char  **lv; 
register  FILE  *fp; 

i f (  passnum  —  1  &&  !more_to_go  ) 

fp  -  stdout; 

else  if(  ! (fp  -  fopen(  f name (passnum) ,  "w"  ))  ) 

{ 

fprintf (stderr, "Can't  open  merge  file  %s  for  write\n", 

fname (passnum) ) ; 

exit  (1) ; 

> 

for(  lv  -  Lines  ;  — Linec  >«  0;  ) 

{ 

fputs(  *lv,  fp  ); 
free  (  *lv++  ) ; 

) 

f close (  fp  ); 


/* - */ 


open_mergefiles (  nfiles  ) 

{ 

/•  Open  all  the  merge  files  and  create  the  heap,  "nfiles" 

•  merge-files  exist  and  the  heap  will  have  that  many 

*  elements  in  it.  The  heap  is  unsorted  on  exit. 

V 

HEAP  *  *hp; 

int  i; 

for(  hp  -  Heap,  i  -  nfiles;  i  >  0;  hp++,  — i  ) 

( 

if(  !  (*hp  -  (HEAP  *)  malloc (sizeof (HEAP)))  ) 

{ 

fprintf  (  stderr,  "sort:  out  of  memory!"  ); 
exit (  1  ) ; 

} 

if  (  !(  (*hp)->file  -  fopen(  fname (i),  "r")  )) 

{ 

fprintf (stderr, "sort :  can't  open  %s  for  read", 

fname  (i)  ); 

exit (  1  ); 

} 

if(  !  fgets  (  (*hp)  ->string,  MAX  BUF,  (*hp)->file  )  ) 

{ 
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482 

fprintf  (stderr,  "sort :  merge  file  %s  is  enpty**. 

483 

fname(i)  ); 

484 

exit (  1  ); 

485 

i 

486 

487  } 

488 

490 

491  monp (  hppl,  hpp2  ) 

492  HEAP 

**hppl,  **hpp2; 

493  { 

494 

/* 

Comparison  routine  for  sorting  the  heap.  Is  passed 

495 

* 

two  pointers  to  HEAP  pointers  and  compares  the 

496 

* 

string  fields  of  these  using  the  same  workhorse 

497 

* 

functions  used  in  the  initial  sorting  phase. 

498 

*/ 

499 

500 

return 

Options  ?  qcmpl  ( (*hppl) ->string,  (*hpp2) ->string) 

501 

:  strcmp  ( (*hppl)->string,  (*hpp2)  ->string) 

502 

; 

503  ) 

504 

506 

507  reheap ( 

nfiles 

i 

508  { 

509 

/* 

Reheap  the  Heap,  assume  that  the  first  element  (**Heap) 

510 

* 

is  the  newly  added  one. 

511 

*/ 

512 

513 

register  int  parent,  child; 

514 

HEAP 

*tmp; 

515 

516 

for(  parent  -  0,  child  -  1;  child  <  nfiles;  ) 

517 

i 

518 

/*  Find  the  smaller  child.  Then  if  the  parent  is  less 

519 

*  than  the  smaller  child,  we're  done.  Otherwise 

520 

*  swap  the  parent  and  child,  and  continue  the 

521 

*  reheaping  process  with  a  new  parent. 

522 

V 

523 

524 

if(  child+l  <  nfiles  )  /*  if  chlld+1  is  in  the  heap  */ 

525 

if (  mcmp(& Heap [child],  iHeap [child+l ) )  >  0) 

526 

child++; 

527 

528 

if  (  manp(  fiHeap [parent ) ,  &Heap[child) )  <-  0) 

529 

break; 

530 

531 

tmp  -  Heap [pa rent ] ;  /*  Exchange  */ 

532 

Heap [pa rent)  -  Heap [chi Id  ); 

533 

Heap [chi Id  )  -  tmp; 

534 

535 

parent  -  child; 

536 

child  -  parent  «  1;  /*  child  -  parent  *  2  */ 

537 

i 

538  ) 

539 

541 

542  merge ( 

nfiles  ) 

543  lnt 

nfiles; 

/*  Number  of  merge  files  V 

544  { 

545 

open  mergefiles (  nfiles  ); 

546 

ssort  ( 

Heap,  nfiles,  sizeof (Heap[0) ) ,  mcmp  ); 

547 

548 

while ( 

nfiles  >  0  ) 

549 

i 

550 

pheap(  "Merge:  top  of  while  loop",  nfiles  ); 

551 

552 

fputs(  (*Heap)->string,  stdout  ); 

553 

554 

if (  ! fgets ( ("Heap) ->strlng,  MAXBUF,  ("Heap) ->f lie)  ) 

555 

( 

556 

/*  This  input  stream  is  exhausted.  Reduce  the 

557 

*  heap  size  to  conpensate.  Note  that  Heap+1 

558 

*  is  the  same  as  &Heap[l); 

559 

V 

560 

561 

fclose(  (*Heap)  ->file  ); 

562 

if(  — nfiles  ) 

563 

memcpy(Heap,  Heap+1,  nfiles  *  sizeof (HEAP) ) ; 

564 

i 

565 

566 

reheap (  nfiles  ); 

567 

i 

568  ) 

569 

571 

572  adjust 

args  () 

573  { 

574 

/* 

Adjust  various  default  arguments  to  fix  mistakes  made 

575 

* 

on  the  command  line.  In  particular  Delim  is  always  0 

576 

* 

unless  either  Primary  or  Secondary  was  set. 

577 

* 

If  a  secondary  field  is  specified  without  a  Primary,  then 

578 

* 

1  is  assumed  for  the  primary.  If  no  Delim  is  specified 

then  tab  (\t)  is  assumed.  "Options"  is  true  if  any  of 
the  options  that  affect  the  sort  order  were  specified 
on  the  command  line. 


if (  ! (Primary  | |  Secondary)  ) 
Delim  -  0; 

else 

1 

if  (  '.Delim  ) 

Delim  -  *\t ' ; 

if{  IPrimary  ) 

Primary  =  1; 


Options  =  Noblanks  | |  Numeric  | |  Dictorder  | |  Foldupper 

1 1  Reverse  | |  Delim; 


main  (argc,  argv) 
int  argc; 


int  numpasses  -  0;  /*  Number  of  merge  files  used 

int  more_input;  /*  True  if  input  isn't  exhausted 

Argc  -  getargs (  argc,  argv,  Argtab,  NUMARGS  ) ; 

Argv  -  argv; 
ad  just_args  () ; 


more_input  -  gtext  ()  ; 

if (  Linec  ) 

{ 

ssort  (Lines,  Linec,  sizeof  (*Lines) , 

Options  ?  qanp  :  argvanp)  ; 

if (  Nodups  ) 

Linec  =■  dedupe  (Linec,  Lines); 
outtext (  ++numpasses,  more_input  ) ; 


)  while  (  more_input  ); 


if(  numpasses  >  1  ) 


f close (  stdin  );  /*  Free  up  c 

fclose(  stdaux  );  /*  criptors 

fclose(  stdprn  );  /*  so  that  t 

/*  merge  fi] 

merge (  numpasses  )  ; 

for(;  numpasses  >  0  ;  — numpasses  ) 
unlink (  fname (nunpasses)  ) ; 


/*  merge  files  were  created 

/*  Free  up  default  file  des- 
/*  criptors  for  unused  streams 
/*  so  that  they  can  be  used  for 
/*  merge  files. 


Listing  1  —  stoi.c 


Listing  Two 


End  Listing  One 


# include  <ctype.h> 

int  stoi(instr) 

register  char  **instr; 

( 

/*  Convert  string  to  integer  updating  *instr  to  point 

*  past  the  number.  Return  the  integer  value  represented 

*  by  the  string. 


10 

11 

register  int 

12 

register  char 

13 

int 

14 

15 

str  -  *instr; 

16 

17 

if(  *str  — 

18 

{ 

19 

sign  = 

20 

str++; 

21 

} 

22 

23 

while (  *0'  <« 

24 

num  - 

25 

26 

*instr  *  str; 

27 

return (  num  *  : 

28  ) 

(num  *  10)  +  (*str++ 


End  Listings 
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/* 

*  short  demo  program  to  illustrate  Hamming  forward  error  correction 

*  code  detects  and  corrects  all  one  bit  errors  and  detects  two 

*  bit  errors  in  a  total  transmitted  block  of  16  bits. 

*  eleven  bits  are  message  bits,  the  rest  are  error  checks 

* 

*  implementation  is  oriented  toward  exposition,  not  speed  or 

*  efficiency  —  this  is  not  industrial  strength  code! 

* 

*  bit  fields  not  implemented  in  C/80 

★ 

*  Joe  Marasco,  March  1986 
*/ 

# include  "fprintf.h" 


#define 

EOF 

-1 

#define 

BO 

1 

#define 

B1 

2 

fdefine 

B2 

4 

#define 

B3 

8 

#define 

B4 

16 

fdefine 

B5 

32 

Idefine 

B6 

64 

#define 

B7 

128 

#define 

B8 

256 

fdefine 

B9 

512 

#define 

BIO 

1024 

idefine 

Bll 

2048 

#define 

B12 

4096 

#define 

B13 

8192 

#define 

B14 

16384 

#define 

B15 

32768 

#define 

Cl 

(B1  +  B3  + 

B5  + 

B7 

+  B9  +  Bll  +  B13  +  B15) 

#define 

C2 

(B2  +  B3  + 

B6  + 

B7 

+  BIO  +  Bll  +  B14  +  B15) 

#define 

C3 

(B4  +  B5  + 

B6  + 

B7 

+  B12  +  B13  +  B14  +  B15) 

#define 

C4 

(B8  +  B9  + 

BIO  +  Bll  +  B12  +  B13  +  B14  +  B15) 

main() 

{ 

int 

input [11]  ; 

/*  input  message  bits 

register  unsigned  int 

xmit  ; 

/*  transmitted  message 

int 

recvd[16]  j 

/*  received  message  bits*/ 

register  unsigned 

int 

rec  ; 

/*  received  message*/ 

int 

syndrome  ; 

/*  computed  syndrome 

int 

recpar  ; 

/*  parity  of  rec'd  msg 

int 

i  ,  ch  ; 

for  (;;)  { 

printf  ("input  11  message  bits,  AC  to  quit\n")  ; 
print  f  ("1  234567890  l\n")  ; 


i  =  0  ; 

while  (  ((ch  =  getchar()) 
switch  (ch)  { 
case  'O'  : 

case  ' 1 '  : 

} 


!=  EOF)  &&  i<ll  ) 

input [i++]  =  0  ; 
break  ; 

input [i++]  =  1  ; 
break  ; 


/* 

*  anything  but  a  0  or  1  is  ignored 

*  check  that  we  have  11  good  bits 
*/ 

if  (  i  <  11  )  ( 

printf ("not  enough  valid  bits,  try  again\n")  ; 
continue  ; 


/* 


} 


*  build  the  message 
*/ 


xmit 

= 

; 

xmit 

|  = 

input [0] 

« 

3  ; 

xmit 

|  = 

input  [1] 

« 

5  ; 

xmit 

|  = 

input [2] 

« 

6  ; 

xmit 

|  = 

input [3] 

« 

7  ; 

xmit 

|  = 

input [4] 

« 

9  ; 

xmit 

|  = 

input [5] 

« 

10  ; 

xmit 

|  = 

input [6] 

« 

11 

xmit 

|  = 

input [7] 

« 

12  ; 

xmit 

|  = 

input [8] 

« 

13  ; 

xmit 

|  = 

input [9] 

« 

14  ; 

xmit 

1  = 

input  [10' 

«  15 

/* 


*  and  the  check  bits  —  even  parity 


*/ 


xmit  |=  (parity (  Cl  &  xmit  )  «  1)  | 
(parity (  C2  &  xmit  )  «  2)  | 
(parity (  C3  &  xmit  )  «  4)  | 
(parity!  C4  &  xmit  )  «  8)  ; 
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*  and  last  but  not  least,  make  total  parity  even 
*/ 


display  it 


xmit  |=  parity (  xmit  )  ; 


print f ("the  block  sent  is 
print f ("0  12345678901234  5\n") 
for  (i=0  ;  i<16  ;  ++i) 

printf ("%d  ",  ((xmit»i)  &  01)  )  ; 
printf  ("\n")  ; 

printf("now  input  the  received  block\n")  ; 
printf ("0  12345678901234  5\n") 


%x  \n",  xmit  ) 


get  the  received  message 


readagain: 


i  =  0  ; 

while  (  ((ch  =  get char ()) 
switch (ch)  { 
case  'O'  : 

case  *1'  : 

} 


anything  but  a  0  or  1  is  ignored 
check  that  we  have  16  good  bits 


EOF)  &&  i<16  ) 

recvd[i t+]  =  0  ; 
break  ; 

recvd[i++]  *  1  ; 
break  ; 


if  (  i  <  16  )  { 

printf ("not  enough  valid  bits,  try  again\n") 
goto  readagain  ; 

) 

for  (i=0  ,  rec=0  ;  i<16  ;  ++i  ) 

rec  |=  (recvd[i)  «  i) 


/* 


printf  ("the  block  received  is 


%x  \n",  rec  ) 


*  compute  the  syndrome 


syndrome  =*  parity  (  Cl  &  rec  )  | 

(  parity (  C2  &  rec  )  «  1  )  | 

(  parity  (  C3  &  rec  )  «  2  )  j 

(  parity (  C4  &  rec  )  «  3  )  ; 


and  the  parity  bit,  which  should  be  zero 


*  decision  time 
V 


recpar  «  parity (  rec  )  ; 


if  (  syndrome  ==  0  )  { 

printf  ("good  message !\n")  ; 
if  (recpar)  { 

printf ("with  reversed  parity  bit\n")  ; 
rec  =  rec  A  01  ; 

printf ("the  recovered  block  is  %x\n" 

rec  )  ; 

printf ("0  12345678901234  5\n")  ; 
for  (i-0  ;  i<16  ;  +4i) 

printf  ("%d  ",  ( (reO>i)  &  01)  )  ; 
printf  ("\n")  ; 

} 

printf (" - \n")  ; 


} 

else  ( 


if  (! recpar)  { 

printf  ("two  bit  errors,  can't  fix\n")  ; 
printf  (" - \n") 


} 

else  { 


printf ("bad  bit  in  position  %d\ri", 
syndrome  )  ; 
rec  =  rec  A  (  01  «  syndrome  )  ; 
printf ("the  recovered  block  is  %x\n" 

rec  )  ; 

printf ("0  12345678901234  5\n")  ; 
for  (i=0  ;  i<16  ;  ++i) 

printf  ("%d  ",  ( (reo>i)  &  01)  )  ; 
printf  ("\n - \n") 


parity (  message  ) 
unsigned  int  message  ; 

( 

/* 

*  return  1  if  odd  parity,  0  if  even 
*/ 

int  j  ,  k  ; 

for  (  j=0  ,  k=0  ;  j<16  ;  ++j  )  k  +=  (  (message  »  j)  &  01  ) 
return (  k  &  01  )  ; 


End  Listing 
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B  PROTOCOL 


Listing  One 


(Listing  continued;  text  begins  on  page  38.) 


# define  R_SenH_NAK  5 
# define  R_Send_ACK  6 

static  int 
Ch, 

Checksum, 

Seq_Num, 

RjSize, 

XOFF_Flag, 

Seen_ETX, 

Seen_ENQ; 

static  char 

S_Buffer [Packet_Size] , 
R_Buffer [Packet_Sizej ; 


/*  Size  of  receiver  buffer  */ 


/*  Sender  buffer  */ 

/*  Receiver  buffer  */ 


stat ic  Put_Msg (Text ) 
char  *Text; 

( 

while  (*Text  !=  0) 

Put_Char  (*Text++)  ; 

Put_Char  ('VOIS')  ; 
Put_Char (’ \012 ' ) ; 

) 


static  Send_Byte (Ch) 
int  Ch; 

( 

int  TCh; 

/*  Listen  for  XOFF  from  the  network  */ 

Start  Timer  (Max  Xoff  Time); 
do 

{ 

while  ((TCh  -  Read_Modem  () )  >=  0) 
if  (TCh  —  XON) 

XOFF_Flag  -  False; 
else  if  (TCh  —  XOFF) 

( 

XOFF_Flag  -  True; 
Start_Timer  ( Max_Xo  f  f _T  ime ) ; 
} 

} 

while  (XOFF_Flag  &&  !Timer_Expired  () )  ; 

while  (! Write  Modem  (Ch) ) ; 

} 


static  Send_Masked_Byte (Ch) 
int  Ch; 

{ 

/*  Mask  any  protocol  or  flow  characters  */ 

if  (Ch  —  NUL  ||  Ch  “  ETX  ||  Ch  ~  ENQ  | |  Ch  =  DLE  | |  Ch  ==  NAK  | |  Ch  ~  XON  | |  Ch 
( 

Send_3yte (DLE) ; 

Send_Byte  (Ch  +  '  @ ' ) ; 

) 

else 

Send  Byte (Ch) ; 

} 


static  Send_ACK() 

{ 

Send_Byte (DLE) ; 

Send_Byte (Seq  Num  +  • 0 ' ) ; 

I 


static  Read_Byte() 

( 

if  ((Ch  -  Read_Modem ( ) )  <  0) 

( 

Start_Timer  (Max_Time) ; 
do 

( 

if  (Timer_Expired() ) 
return  Failure; 

) 

while  ( (Ch  *  Read_Modem() )  <  0); 

) 

return  Success; 

} 


static  Read_Masked_Byte  () 

{ 
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B  PROTOCOL 


Listing  One 

(Listing  continued,  text  begins  on  page  38.) 


Seen_ETX  =  False; 

Seen_ENQ  =  False; 

if  (Read_Byte  ()  =  Failure) 
return  Failure; 

if  (Ch  =  DLE) 

{ 

if  (Read_Byte  ()  ==  Failure) 
return  Failure; 

Ch  &=  Oxl F; 

} 

else  if  (Ch  ==  ETX) 

Seen_ETX  =  True; 
else  if  (Ch  ==  ENQ) 

Seen_ENQ  »  True; 

return  Success; 

1 


static  Do_Checksum  (Ch) 
int  Ch; 

{ 

Checksum  «=  1; 

if  (Checksum  >  255) 

Checksum  =  (Checksum  &  OxFF)  +  1; 

Checksum  +=  Ch  &  OxFF; 

if  (Checksum  >  255) 

Checksum  =  (Checksum  &  OxFF)  +1; 

) 

static  int  Read_Packet (Action) 

/** 

*  Function: 

*  Receive  a  packet  from  the  host. 

*  Inputs: 

*  Action  —  the  starting  action 

*  Outputs: 

*  R_Buffer  —  contains  the  packet  just  received 

*  R_Size  —  length  of  the  packet 

*  Returns: 

*  success/failure 
**/ 

int  Action; 

{ 

int 

Errors, 

Next_Seq; 

Errors  =  0; 

while  (Errors  <  Max_Errors) 
switch  (Action) 

1 

case  R  Get_DLE: 

if  (Read_Byte  ()  ==  Failure) 

Action  =  R  Send_NAK; 
else  if  (Ch  ="DLE) 

Action  «=  R_Get_B; 
else  if  (Ch  =  ENQ) 

Action  =  R_Send_ACK; 

break; 

case  R  Get_B: 

If  (Read_Byte  ()  ==  Failure) 

Action  =  R_Send_NAK; 
else  if  (Ch  =  ‘  B  * ) 

Action  =  R_Get_Seq; 

else 

Action  =  R_Get_DLE; 
break; 

case  R  Get_Seq: 

Ff  (Read_Byte  ()  ==  Failure) 

Action  =  R_Send_NAK; 

else 

{ 

Checksum  =  0; 

Next_Seq  =  Ch  -  'O’; 
Do_Checksum(Ch)  ; 

R_Size  =  0; 

Action  -  R_Get_Data; 

} 
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break; 

case  R  Get_Data: 

I~f  (Read_Masked_Byte()  ==  Failure) 

Action  -  R_Send_NAK; 
else  if  (Seen_ETX) 

Action  -  R_Get_Checksun; 
else  if  (Seen_ENQ) 

Action  -  R_Send_ACK; 
else  if  (R_Size  ==  Packet_Size) 

Action  =  R_Send_NAK; 

else 

{ 

R_Buffer [R_Size++]  =  Ch; 

Do  Checksum (Ch) ; 

} 

break; 

case  R_Get_Checksum: 

Do_Checksum  (ETX) ; 

if  (Read_Masked_Byte()  ==  Failure) 

Action  -  R_Send_NAK; 
else  if  (Checksum  !  =  Ch) 

Action  =  R_Send_NAK; 
else  if  (Next_Seq  ==  Seq_Num) 

Action  -  R_Send_ACK;  /*  Ignore  duplicate  packet  */ 
else  if  (Next_Seq  !  =  (Seq_Num  +1)  %  10) 

Action  =  R_Send_NAK; 

else 

{ 

Seq_Num  -  Next_Seq; 


return  Success; 

} 

break; 

case  R_Send_NAK: 

Put_Char  ('-'); 
Errors ++; 

Send_Byte  (NAK)  ; 
Action  =  R_Get_DLE; 
break; 

case  R_Send_ACK: 

Send_ACK ( ) ; 

Action  -  R_Get_DLE; 
break; 

) 

return  Failure; 

) 


static  int  Send_Packet (Size) 

/*« 

*  Function: 

*  Send  the  specified  packet  to  the  host. 

*  Inputs: 

*  Size  —  length  of  the  packet 

*  S_Buffer  —  the  packet  to  send 

* 

*  Outputs: 

* 

*  Returns: 

*  success/ failure 
**/ 

int  Size; 

( 

int 

Action, 

Next_Seq, 

RCV_Num, 

I, 

Errors; 

Next_Seq  =  (Seq_Num  +  1)  %  10; 

Errors  “0; 

Action  -  S_Send_Packet; 

while  (Errors  <  Max_Errors) 
switch  (Action) 

{ 

case  S_Send_Packet : 

Checksum  =0; 

Send_Byte (DLE) ; 

Send_Byte ( ’ B ' ) ; 

Send  Byte  (Next_Seq  +  '  0 ' ) ; 
Do_cHecksum (Next_Seq  +  1 0 ' ) ; 

for  (1=0;  I  <  Size;  I++) 

( 

Send_Masked_Byte(S_Buffer (I) ) ; 
Do_Checksum (S_Buf fer ( I ] ) ; 

) 

Send_Byte (ETX) ; 

Do_C heck sum (ETX) ; 

Send  Masked  Byte (Checksum) ; 


(continued  on  next  page) 
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Listing  One  (Listing  continued,  text  begins  on  page  38.) 


Action  =*  S_Get_DLE; 
break; 

case  S_Get_DLE: 

if  (Read_Byte()  ==  Failure) 

Action  =  S_Timed_Out; 
else  if  (Ch  =  DLE) 

Action  =  S_Get_Num; 
else  if  (Ch  —  ENQ) 

Action  =  S_Send_ACK; 
else  if  (Ch  —  NAK) 

( 

Errors ++; 

Action  =  S_Send_Packet; 

} 

break; 

case  S  Get_Num: 

£~f  (Read_Byte()  ==  Failure) 

Action  -  S_Timed_Out; 
else  if  (Ch  >=  '0*  &&  Ch  <=  '9') 

{ 

if  (Ch  “  Seq_Num  +  '0') 

Action  =  S_Get_DLE; /*  Ignore  duplicate  ACK  */ 
else  if  (Ch  ==  Next_Seq  +  '0') 

{ 

/*  Correct  sequence  number  *  •' 

Seq_Num  =  Next_Seq; 
return  Success; 

} 

else  if  (Errors  ==  0) 

Action  *  S_Send_Packet; 

else 

Action  »  S_Get_DLE; 

) 

else  if  (Ch  =  WACK) 

{ 

Delay (5000);  /*  Sleep  for  5  seconds  */ 

Action  =  S_Get_DLE; 

) 

else  if  (Ch  =  *B') 

Action  -  S_Get_Seq; 

else 

Action  -  S_Get_DLE; 
break; 

case  S  Get_Seq: 

/** 

*  Start  of  a  "B"  protocol  packet.  The  only  packet  that  makes 

*  any  sense  here  is  a  failure  packet. 

**/ 

if  (Read_Byte()  ==  Failure) 

Action  =  S_Send_NAK; 

else 

{ 

Checksum  =  0; 

RCV_Num  =  Ch  -  'O'; 

Do_Checksum(Ch) ; 

I  -  0; 

Action  =  S_Get_Data; 

) 

break; 

case  S  Get_Data: 

Ff  (Read_Masked_Byte  ()  ==  Failure) 

Action  =  S_Send_NAK; 
else  if  (Seen_ETX) 

Action  ■  S_Get_Checksum; 
else  if  (Seen_ENQ) 

Action  =  S_Send_ACK; 
else  if  (I  “  Packet_Size) 

Action  =  S_Send_NAK; 

else 

{ 

R_Buffer [I++]  =  Ch; 

Do_Checksum(Ch)  ; 

} 

break; 

case  S_Get_Checksum: 

Do_C  heck  sum  (ETX)  ; 

if  (Read_Masked_Byte  ()  ==  Failure) 

Action  -  S_Send_NAK; 
else  if  (Checksum  !*»  Ch) 

Action  =  S_Send_NAK; 

else  if  (RCV_Num  !-  (Next_Seq  +1)  %  10) 

Action  =  S_Send_NAK; 

else 

{ 
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/** 

*  Assume  the  packet  is  failure  packet.  It  makes  no 

*  difference  since  any  other  type  of  packet  would  be 

*  invalid  anyway.  Return  failure  to  caller. 

**/ 

Errors  =  Max_Errors; 

) 

break; 

case  S_Timed_Out : 

Errors++; 

Action  =  S_Get_DLE; 
break; 

case  S_Send_NAK: 

Put_Char 
Errors ++; 

Send_Byte (NAK) ; 

Action  *  S_Get_DLE; 
break; 

case  S_Send_ACK: 

Send_ACK()  ; 

Action  =  S_Get_DLE; 
break; 

) 

return  Failure; 

I 

static  Send_Fai lure (Code) 

/** 

*  Function: 

*  Send  a  failure  packet  to  the  host. 

*  Inputs: 

*  Code  —  failure  code 

* 

*  Outputs: 

* 

*  Returns: 

**/ 

char  Code; 

{ 

S_Buffer[0]  =  'F'; 

S__Buffer[l]  =  Code; 

Send_Packet (2) ; 

) 

static  int  Receive_File (Name) 

/•* 

*  Function: 

*  Download  the  specified  file  from  the  host. 

* 

*  Inputs: 

*  Name  —  ptr  to  the  file  name  string 

*  Outputs: 

*  Returns: 

*  success/failure 
**/ 

char  *Name; 

{ 

int  Data_File;  /*  file  descriptor  */ 

if  ((Data_File  «  Create_File (Name,  0))  ==  -1) 

l 

Put_Msg ("Cannot  create  file"); 

Send_Failure ( * E * )  ; 
return  Failure; 

} 

Send_ACK  ()  ; 
for  (;;) 

if  (Read_Packet (R_Get_DLE)  ==  Success) 
switch  (R_Buffer (0) ) 

1 

case  'N':  /*  Data  packet  */ 

if  (Write_File  (Data  File,  SR  Buffer [1),  R  Size  -  1)  !-  R  Size  -  1) 
( 

/"  Disk  write  error  V 

Put_Msg ("Disk  write  error"); 

Send_Failure('E')  ; 

Close_File  (Data_File)  ; 
return  Failure; 

) 

if  (Wants_To_Abort  () ) 

( 

/*  The  user  wants  to  kill  the  transfer  */ 

Send_Failure ( 'A' ) ; 

Close_File (Data_File) ; 
return  Failure; 

) 

(continued  on  ne,xt  page) 
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Listing  One  (Listing  continued,  text  begins  on  page  38.) 


Send_ACK  ()  ; 
Put_Char  ( '  +  ') ; 
break ; 


if  (R_Buffer [1] 


/*  Transfer  packet  */ 

]  =  'C')  /*  Close  file 


Send_ACK ( )  ; 

Close_File (Data_File) ; 
return  Success; 

} 


*  Unexpected  "T"  packet.  Something  is  rotten  on  the 

*  other  end.  Send  a  failure  packet  to  kill  the 

*  transfer  cleanly. 

**/ 

Put_Msg ("Unexpected  packet  type"); 

Send_Failure ( *  E ' ) ; 

Close_File (Data_File) ; 
return  Failure; 


case  '  F * :  /*  FaiJ 

Send_ACK  ()  ; 

Close_File (Data_File) ; 
return  Failure; 


/*  Failure  packet 


Close_File (Data_File) ; 
return  Failure; 

) 


static  int  Send_File (Name) 

/** 

*  Function: 

*  Send  the  specified  file  to  the  host. 

*  Inputs: 

*  Name  —  ptr  to  the  file  name  string 

*  Outputs: 

* 

*  Returns: 

*  success/failure 
**/ 

char  *Name; 


Data_File, 

N; 


/*  file  descriptor  */ 


if  ( (Data_File  -  Open_File  (Name,  0))  — 

( 

Put _Msg ("Cannot  access  that  file"); 
Send_Failure ( *E') ; 
return  Failure; 


S_Buffer [0]  -  'N'; 

N  -  Read_File (Data_File,  &S_Buffer [1] ,  Packet_Size  -  1); 

if  (N  >  0) 

{ 

if  (Send_Packet  (N  +  1)  ==  Failure) 

{ 

Close_File (Data_File) ; 
return  Failure; 

) 

if  (Want s_To_Abort  ( ) ) 

{ 

Send_Failure( 'A' ) ; 

Close_File (Data_File) ; 
return  Failure; 

) 

Put_Char  ('  +  ')  ; 

} 


while  (N  >  0); 

if  (N  ==  0) 

1 

Close_File (Data_File) ; 
S_Buffer(0]  =  'T1; 
S_Buf fer [1]  »  *C'; 
return  Send_Paeket  (2) ; 
) 


/*  end  of  file  */ 
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Put_Msg("Disk  read  error"); 
Send_Failure ( ' E ' ) ; 
return  Failure; 


int  Transfer  File() 


*  Function: 

*  Transfer  a  file  from/ to  the  micro  to/from  the  host. 


Returns: 

success/failure 


int  I,  N; 
char  Name  [64] ; 

XOFF_Flag  -  False; 
Seq_Num  -  0; 


if  (Read_Packet (R_Get_Seq)  —  Success) 

{ 

if  (R_Buffer [0]  --  'T') 

{ 

/*  Check  the  direction  */ 


/*  holds  the  file  name  */ 


/*  transfer  packet  */ 


if  (R_Buffer [1]  !«  'D*  &&  R_Buffer[l]  !=  *U') 

{ 

Send_Failure('N') ;  /*  not  implemented  */ 
return  Failure; 

) 

/*  Check  the  file  type  */ 


if  (R  Buffer (2) 


*A*  &&  R_Buf fer [2]  !=  1 B* ) 


Send_Failure('N') ; 
return  Failure; 


/*  Collect  the  file  name  */ 

N  -  R_Si ze  -  3  >  63  ?  63  :  R_Size  -  3; 

for  (I  -  0;  I  <  N;  I++) 

Name[I]  -  R_Buffer[I  +  3]; 

Name  [I]  «  0; 

/*  Do  the  transfer  */ 

if  (R_Buffer[l]  =  *U') 

return  Send_File (Name) ; 

else 

return  Receive_File  (Name) ; 

) 


Send_Fa ilure  ( '  E ' ) ; 
return  Failure; 


/*  wrong  type  of  packet  */ 


return  Failure; 


Listing  Two 


End  Listing  One 


title  Keyboard  Driver 

include  \lc\dos.mac 
pseg 

public  Read_Keyboard 

Read_Keyboard  proc 
;++ 

;  Function: 

;  Read  a  "raw"  character  from  the  keyboard. 

;  Inputs:  none 
;  Outputs:  none 


-1  if  no  character  is  available;  otherwise  a  16-bit  code. 

If  the  high  byte  is  zero,  then  the  low  byte  is  an  ASCII  character, 
else  the  low  byte  is  an  "extended"  character  (scan  code) . 
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Listing  Two  (Listing  continued,  text  begins  on  page  38.) 


int 

jz 

mov 

int 

onp 

je 

mov 

ret 

Read_Keyboard_l : 
mov 
ret 


16H 

Read_Keyboard_l 
AH,  0 
16H 
AL,  0 

Read_Keyboard_2 
AH,  0 


AX,  -1 


Read_Keyboard_2 : 

mov  AL,  AH 

mov  AH, 01H 

ret 

Read_Keyboard  endp 

endps 

end 


;  Scan  the  keyboard 
;  No  character  available 
;  Yes 

;  Read  keyboard 
;  Extended  character 
;  Yes 

;  No,  normal  character 


;  Denote  "no  character  available" 


Extended  character 

;  Set  the  "function  key"  flags 


End  Listing  Two 


Listing  Three 


/* 

*  This  program  emulates  a  dump  terminal  with  file  transfer  support  using 

*  CompuServe’s  B-Protocol.  This  program  is  just  a  sample  of  how  to  interface 

*  the  BP  module  (BP.C)  with  the  rest  of  the  terminal  emulator. 

V 


•define  IBM  PC  1 


extern  int  Transfer_File  () ; 

extern  int  Read_Keyboard  () ; 

extern  Open_Modem  () ; 
extern  int  Read  Modem (); 


/*  Transfer  a  file  using  the  "B"  protocol  */ 

/*  Get  a  "raw"  character  from  the  keyboard  */ 

/*  Initialize  the  comm  port  */ 

/*  Read  a  character  from  the  comm  port  */ 


(continued  on  page  102) 
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_ B  PROTOCOL 

Listing  Three  (Listing  continued,  text  begins  on  page  38.) 


extern  int  Write_Modem() ; 
extern  Close_Modem  ()  ; 


♦  define 

True 

1 

♦define 

False  0 

♦define 

Baud_ 

300 

1 

♦define 

Baud_ 

"450 

2 

♦define 

Baud 

1200 

3 

♦define 

Baud 

'1800 

4 

♦define 

Baud 

'2400 

5 

♦define 

Baud_ 

'4800 

6 

♦define 

Baud 

'9600 

7 

♦ifdef  IBM  PC 

♦define 

Ex1t_ 

Key 

0x01 2D 

♦else 

♦define 

Exit_ 

Key 

OxOOlD 

♦endif 

♦define 

ls_Function  Key(C) 

♦define 

ENQ 

0x05 

♦define 

DLE 

0x10 

♦define 

ESC 

OxlB 

/*  Send  a  character  to  the  comm  port  */ 
/*  Release  the  comm  port  */ 


/*  Baud  rate  codes  used  by  Qpen_Modem  */ 


/*  for  IBM  style  keyboards  */ 
/*  Alt-X  */ 

/*  control-]  */ 

((C)  >  127) 


/* 

*  We  only  support  the  B-protocol  file  transfer.  No  other  VIDTEX  features. 
V 

static  char  VIDTEX_Response [ ]  =  "#DTE, PB,DT\015"; 


static  int 

01d_Break_State, 

I, 

Ch,  /*  16-bit  "raw"  character  */ 

Want_7_Bit,  /*  true  if  we  want  to  ignore  the  parity  bit  */ 

ESC_Seq_State;  /*  Escape  sequence  state  variable  */ 


int  Wa  nt  s_To_Abo  rt ( ) 

( 

return  Read_Keyboard  ()  =■=  ESC; 

} 

main() 

l 

char  *cp; 

Want_7_Bit  =  True; 

ESC_Seq_State  -  0; 

♦ifdef  MSDOS 

01d_Break_State  =  Get_Break(); 

Set_Break  (0) ; 

#endif 

Cpen_Modem(0,  Baud_1200,  False); 
puts("[  Terminal  Mode  ]"); 

Ch  =  Read_Keyboard ( ) ; 

while  (Ch  !-  Exit_Key) 

( 

if  (Ch  >  0) 

( 

if  (Is_Function_Key  (Ch) ) 

{ 

/*  Here  to  process  any  local  function  keys.  */ 

} 

else 

Write_Modem(Ch  &  0x7F) ; 

) 

if  ({Ch  =  Read_Modem())  >=  0) 

( 

if  (Want_7_Bit)  Ch  &=  0x7F; 

switch  (ESC_Seq_State) 

( 


case  0: 

switch  (Ch) 

( 

case  ESC: 

E  SC_S  eq_S  t  a  t  e  =  1; 
break; 

case  ENQ: 

/*  Enquiry  —  send  ACK  for  packet  0  */ 

Write_Modem (DLE)  ; 

Write_Modem ( ' 0 ' ) ; 
break ; 

case  DLE: 

ESC_Seq_State  =•  2; 
break ; 
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default: 

Put_Char  (Ch)  ; 

} 

break; 
case  1: 

/*  ESC  —  process  any  escape  sequences  here  */ 

switch  (Ch) 

{ 

case  'I': 

/* 

*  Reply  to  the  VIDTEX  "ESC  I"  identify  sequence 
V 

cp  *  VIDTEX_Response; 

while  (*cp  !=  0)  Write_MDdem (*cp++) ; 

ESC_Seq_State  =0; 
break ; 

default: 

Put_Char  (ESC)  ; 

Put_Char  (Ch)  ; 

ESC_Seq_State  =  0; 

} 

break; 

case  2: 

/*  DLE  V 

if  (Ch  ■=  'B') 

{ 

/*  Start  of  "B"  protocol  packet.  Go  into  protocol 
*  mode  and  transfer  the  file  as  requested. 

*/ 

if  (!  Trans  fer_File  () )  puts  ("Transfer  failed!"); 

) 

else 

{ 

Put_Char  (DLE)  ; 

Put_Char  (Ch)  ; 

) 

ESC_Seq_State  *■  0; 

) 

} 

(continued  on  next  page) 


103 

429 


16-BIT 

Listing  One 

(Text  begins  on  page  1 12.) 

mov 

dx, seg  fname 

open  a  file  for  I/O 

mov 

ds,dx 

DS:DX  -  ASCIIZ  filespec 

mov 

dx, offset  fname 

function  3DH  -  open. 

mov 

ax, 3d02h 

use  mode  2  (read/write) 

int 

21h 

jc 

error 

jump  if  open  failed 

mov 

my_file. 

ax 

save  handle  for  file 

further  file 
processing  here 

now  use  DUP  and  CLOSE 
to  update  the  directory... 

mov 

bx,my  file 

get  handle  for  file 

mov 

ah,  45h 

function  45H  -  DUP  handle. 

int 

21h 

jc 

error 

jump  if  DUP  failed 

mov 

bx,  ax 

now  close  the  DUP'd  handle 

mov 

ah, 3eh 

function  3 EH  -  close  file 

int 

21h 

transfer  to  MS-DOS 

jc 

error 

junp  if  close  failed 
otherwise  directory  is 
updated,  continue  processing 

2rror: 

my_file  dw 

0 

handle  from  previous  "open" 

fname  db 

'MY  FILE 

DAT' 

/0 

ASCIIZ  filespec 

End  Listing  One 

Listing  Two 

page  60,  120 

title  Redirected  I/O  example 

REDIRECT. ASM 

-  An  illustration  of 

I/O  redirection  under 

MS-DOS 

.x  or  3.X 

Copyright  (C) 

1985  by  Jerry  Jankura 

Created:  6 

November 

1985 

Modified:  9 

November 

1985 

Abstract:  This  routine  demonstrates  redirection  of  I/O 

from  the  console  to  a 

line  printer.  The  method  may  be 

used  to  redirect  I/O 

:rom 

any 

device  to  any  other  device. 

Requires  Microsoft  MS 

-DOS 

2.X 

or  3.X,  or  DRI  Concurrent 

DOS  version  4 

.1. 

STD  IN 

ECU 

0 

;  Standard  input  handle 

STD  OUT 

EQU 

1 

;  Standard  output  handle 

STD  ERR 

ECU 

2 

;  Standare  error  handle 

STD  AUX 

EQU 

3 

;  Standard  Auxiliary  handle 

STD_LST 

EQU 

4 

;  Standard  printer  handle 

C_WRITESTR 

EQU 

9 

;  Write  string  to  STD_OUT 

F  DUP 

EQU 

45H 

;  Duplicate  handle 

F  CDUP 

EQU 

46H 

;  Force  duplicate  handle 

F  CLOSE 

EQU 

3EH 

;  Close  file  handle 

F_WRITE 

EQU 

40H 

;  Write  to  file  or  dev 

P_TERM 

EQU 

4CH 

;  Terminate  a  program 

MS_DOS 

EQU 

21H 

;  MS-DOS  service  request 

CR 

EQU 

ODH 

;  Carriage  return 

LF 

EQU 

OAH 

;  Line  feed 

datasg 

segment 

para 

'data' 

msgl 

db 

CR, 

LF, 

‘Redirected  I/O  example....' 

db 

CR, 

LF 

db 

CR, 

LF, 

'This  example  was  written  using  the' 

db 

CR, 

LF, 

'File  I/O  system  services,  with  the' 

db 

CR, 

LF, 

'file  handle  being  set  to  STD  CUT.' 

db 

CR, 

LF, 

'STD  OUT  normally  defaults  to  the' 

db 

CR, 

LF, 

'video  screen,  so  you  are  reading' 

db 

CR, 

LF, 

'this  message  on  the  screen.' 

db 

CR, 

LF 

msg2 

db 

CR, 

LF, 

'However,  we  may  direct  STD  OUT  to' 

db 

CR, 

LF, 

'another  device,  such  as  the  printer.' 

'This  message  is  still  written  to* 

db 

CR, 

IF, 

db 

CR, 

LF, 

'STD-CUT,  but  is  appears  at  the  printer.' 
'Again,  the  operating  system  provides' 

db 

CR, 

LF, 

db 

CR, 

LF, 

'the  facility  to  allow  one  file  to  mimic' 

db 

CR, 

LF, 

'and  track  another.  The  Command  processor* 

db 

CR, 

LF, 

'normally  implements  this  redirection' 

db 

CR, 

LF, 

'of  standard  devices. ' 

db 

CR, 

LF 

msg3 

db 

CR, 

LF, 

'This  message  is  written  on  the' 

db 

CR, 

LF, 

'Video  screen,  demonstrating  that' 

db 

CR, 

LF, 

'a  message  may  be  redirected  to  the' 

db 

CR, 

LF, 

'normal  STD  CUT  device  in  the  same' 

db 

CR, 

LF, 

'manner  that  was  used  to  redirect' 

db 

CR, 

LF, 

'it  to  the  printer.' 

db 

CR, 

LF 

msg4 

dup_handle 

orig_handle 

datasg 

stack sg 

inystack 

stacksg 

code 

assume 

assure 

assure 

assure 


db 

CR, 

LF, 

db 

CR, 

LF, 

db 

CR, 

LF, 

db 

CR, 

LF 

db 

CR, 

IF, 

db 

CR, 

LF, 

db 

CR, 

LF, 

db 

0 

dw 

? 

dw 

0 

'Note  also  that  the  initialized  data  is' 
'stored  in  the  data  segnent,  rather* 
'than  in  the  code  seyrent.' 

'Also,  the  messages  are  written  using* 
'block  I/O,  so  a  minimum  number  of  DOS' 
'system  services  are  requested.' 


ends 

segment  para  stack  'stack' 
db  512  dup  (?) 

ends 

segment  para  'code* 

cs:  code 
ds:  datasg 
ss:  stacksg 
es:  nothing 


test_redirect  proc 


far 


;  Initialize  stack  pointer  and  data  segment  register 
;  to  the  correct  values.  The  stack  pointer  is  set 
;  to  the  top  of  the  stack  segment.  The  data  segment 
;  is  set  to  the  segment  of  the  first  variable.  Note 
;  that  at  this  point  in  time,  the  DS  register  does 
;  not  point  to  the  PSP. 

mov  sp,  513  ;  set  up  user  stack 

mov  ax,  seg  msgl 

mov  ds,  ax 

;  First,  write  a  sign-on  message  to  the  screen.  We 
;  will  attempt  to  write  this  message  to  the  standard 
;  output  device. 


ah: 

bx: 

cx: 

DS:dx 


I NT  21 H  function  id. 
file  handle 

•  of  bytes  to  transfer 
points  to  message 


mov 

mov 

mov 

mov 

int 


ah,  F  WRITE 
dx,  oYfset  msgl 
bx,  STD_OUT 
cx,  msg2-msgl 
MS  DOS 


Now,  we  wish  to  redirect  the  output  to  the 
printer.  Before  we  force  the  redirection, 
we  must  make  a  copy  of  the  standard  output 
file  handle  and  store  it  in  the  field 
orlg_handle. 

mov  bx,  STD_OUT 

mov  ah,  F_DUP 

int  MS_DOS 

mov  word  ptr  orig_handle,  ax 

mov  bx,  STD_LST 

mov  ah,  F_DUP 

int  MS_DOS 

mov  word  ptr  dup_handle,  ax 

Then,  the  STD  LST  handle  is  set  to  track 
the  STD  OUT  fTle. 


mov 

mov 

mov 

int 


bx,  ax 
cx,  STD_OUT 
ah,  F_CDUP 
MS  DOS 


;  Let's  write  a  message  out  and  try  it. 

;  Note  that  we  are  still  writing  information  to 
;  the  STD  OUT  device. 


mov 

mov 

mov 

mov 

int 


ah,  F_WRITE 
bx,  STD  OUT 
cx,  msgl-msg2 
dx,  offset  msg2 
MS  DOS 


Now,  let's  clean  up  and  return  everything 
back  to  its  original  condition. 


mov 

mov 

int 

mov 

mov 

mov 

int 

mov 

mov 

mov 

mov 

int 

mov 

int 

test_redirect  endp 
code  ends 

end 


bx,  word  ptr  dup_handle 

ah,  F_CLOSE 

MS_DOS 

bx,  word  ptr  orlg_handle 
cx,  STD_OUT 
ah,  F_CDUP 
MS_DOS 

ah,  F_WRITE 
bx,  STD  OUT 
cx,  msgT-msg3 
dx,  offset  msg3 
MS_DOS 

ah,  P_TERM 
MS  DOS 


test  redirect 


End  Listings 
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STRUCTURED  PROGRAMMING 

UStinC]  On©  (Text  begins  on  page  11 6.) 

Listing  Two 

CONST  MAX  SWITCH  -  3; 

TYPE  Complex  -  RECORD 

MAX  ELEMENTS  -  100; 

Is  Polar  :  BOOLEAN; 

MAX  BIN  -  30; 

CASE  BOOLEAN  OF 

MAX  BIN  PLUS  ONE  -  31; 

(  Polar  coordinates  } 

TRUE  :  (Modulus,  Angle  :  REAL) ; 

TYPE  Histogram  Rec  - 

(  Rectangular  coordinates  } 

FALSE  :  (Xcoord,  YCoord  :  REAL) ; 

RECORD 

END; 

Num  Elements  :  1..MAX  ELEMENTS; 

Switch  :  1 . .MAX  SWITCH; 

Num  Bins  :  1..MAX  BIN  PLUS  ONE; 

PROCEDURE  Add (A,  B  :  Complex;  (  input  ] 

Count  :  ARRAY  [1..MAX  BIN]  OF  INTEGER;  {  For  output  only  } 

VAR  C  :  Complex  (  ouput  } ) ; 

CASE  INTEGER  OF 

(  Procedure  to  add  two  complex  numbers  taking  into  account  ) 

1  :  (Real  Array  :  ARRAY  [1..MAX  ELEMENTS]  OF  REAL; 

{  their  dual  presentation.  ) 

Real  Bins  :  ARRAY  (1..MAX  BIN  PLUS  ONE]  OF  REAL); 

(  local  rectangular  coordinates  ] 

2  :  (String  Array  :  ARRAY  [1..MAX  ELEMENTS]  OF  STRING[80]; 

VAR  XI,  X2,  X3,  Yl,  Y2,  Y3  :  REAL; 

First  Char,  Last  Char  :  INTEGER; 

String  Bins  :  ARRAY  [1..MAX  BIN  PLUS  ONE]  OF  STRING [20]); 

PROCEDURE  Get  Coordinates (P  :  Complex;  {  input  } 

( - More  types  here - ) 

X,  Y  :  REAL  [  output  } ) ; 

{  3  :  (Intg  Array  :  ARRAY  [1..MAX  ELEMENTS]  OF  INTEGER;  ] 

(  Local  procedure  to  obtain  rectangular  coordinates  ] 

(  Intg  Bins  :  ARRAY  [1..MAX  BIN  PLUS  ONE]  OF  INTEGER);  ] 

BEGIN 

(  4  :  (Char  Array  :  ARRAY  [1..MAX  ELEMENTS]  OF  CHAR;  ] 

WITH  P  DO  BEGIN 

{  Char  Bins  :  ARRAY  [1..MAX  BIN  PLUS  ONE]  OF  CHAR);  } 

IF  P.Is  Polar 

THEN  BEGIN 

END; 

X  :«  Modulus  *  COS (Angle); 

Y  Modulus  *  SIN (Angle) 

END 

ELSE  BEGIN 

PROCEDURE  Count  Histogram (VAR  Histogram  :  Histogram  Rec); 

X  Xcoord; 

(  Pseudo-over loaded  histogram  counting  procedure  ) 

Y  Ycoord 

END;  {  IF  ] 

VAR  I,  J  : INTEGER; 

END;  {  WITH  ) 

Found  :  BOOLEAN; 

END;  (  Get  Coordinates  } 

PROCEDURE  Real  Histogram; 

BEGIN 

{  Local  procedure  to  count  histogram  frequency  for  an  array  of  reals  ] 

(  Get  rectangular  coordinates  of  A  and  B  } 

Get  Coordinates (A,  XI,  Yl); 

BEGIN 

Get  Coordinates (B,  X2,  Y2) ; 

WITH  Histogram  DO  BEGIN 

FOR  I  ;■  1  TO  Num  Elements  DO  BEGIN  {  main  loop  ) 

(  Add  rectangular  components  ] 

{  Is  element  within  bln  ranges  ?  ) 

IF  (Real  Array [I]  >-  Real  Bins[l])  AND 

X3  XI  +  X2;  Y3  Yl  +  Y2; 

(Real  Array  [I]  <  Real  Bins  [Nun  Bins]) 

WITH  C  DO  BEGIN 

THEN  BEGIN  (  Locate  corresponding  bin  ) 

IF  Is  Polar 

J  1;  Found  FALSE; 

THEN  BEGIN 

WHILE  (J  <  Num  Bins)  AND  (NOT  Found)  DO 

Modulus  SQRT (X3*X3  +  Y3*Y3) ; 

IF  (Real  Array[I]  >-  Real  Bins[J])  AND 

Angle  ArcTan (Y3/X3) 

(Real  Array [I]  <  Real  Bins[J+l]) 

END 

THEN  Found  TRUE 

ELSE  BEGIN 

ELSE  J  J  +  1; 

Xcoord  X3; 

(  END  WHILE  } 

Ycoord  Y3 

Count [J]  Count [J]  +  1; 

END;  (  IF  } 

END;  {  IF  } 

END;  [  WITH  } 

END;  (  FOR  I  ] 

END;  {  Add  ) 

END;  (  WITH  } 

End  Listing  Two 

END;  {  Real_Histogram  ) 

PROCEDURE  String_Histogram; 

(  Procedure  to  count  histogram  frequency  for  an  array  of  strings  } 

Listing  Three 

VAR  strr  :  STRING [20]; 

Copy  String  ;  STRING [80]; 

{ - Constants  and  Data  Types  Needed - ) 

BEGIN 

CONST  MAX  HEIGHT  **  100; 

WITH  Histogram  DO  BEGIN 

TYPE 

FOR  I  1  TO  Num  Elements  DO  BEGIN  [  main  loop  } 

Copy_String  String  Array[I]; 

Strr  {  initialize  Strr  ) 

Complex  **  RECORD  Reel,  Imaginary  :  REAL;  END; 

(  Extract  portion  of  string  for  comparison  ] 

FOR  J  First  Char  TO  Last  Char  DO 

Stack  Rec  - 

Strr  Strr  +  Copy_String[ JJ ; 

RECORD 

Switch  :  INTEGER; 

(  Is  element  within  bin  ranges  ?  ) 

CASE  INTEGER  OF 

IF  (Strr  >-  String  Bins[l])  AND 

0  :  (Integer_type  :  INTEGER) ; 

(Strr  <  String  Bins [Num  Bins]) 

1  :  (Real  type  :  REAL) ; 

THEN  BEGIN 

2  :  (String  type  :  STRING[80]); 

J  :=  1;  Found  FALSE; 

3  :  (Complex_type  :  Complex) ; 

WHILE  (J  <  Num  Bins)  AND  (NOT  Found)  DO 

IF  (Strr  >-  String  Bins[J])  AND 

Stack  -  RECORD 

(Strr  <  String  Bins[J+l]) 

THEN  Found  :=  TRUE 

Height  :  INTEGER; 

ELSE  J  J  +  1; 

Stack  Member  :  ARRAY  [1..MAX  HEIGHT]  OF  Stack  Rec; 

{  END  WHILE  ) 

Count [J]  Count [J]  +1; 

END; 

END;  {  IF  } 

PROCEDURE  Push  (VAR  Stk  :  Stack;  [  in/out  ] 

END;  {  FOR  I  ) 

Element  :  Stack  Rec;  {  output  ) 

END;  |  WITH  } 

VAR  OK  :  BOOLEAN  {  output  }); 

END;  {  String  Histogram  ) 

{  Procedure  to  push  'Element'  in  stack  ) 

BEGIN 

BEGIN 

WITH  Stk  DO  BEGIN 

{  Initialize  keys  } 

FOR  I  :=  1  TO  MAX_BIN  DO 

Histogram. Count [I]  0; 

IF  Height  <  MAX  HEIGHT 

THEN  BEGIN 

OK  TRUE; 

CASE  Histogram. Switch  OF 

1  :  Real  Histogram;  {  Do  histogram  count  for  reals  ) 

Height  Height  +1; 

Stack_Member [Height]  Element 

2  :  String  Histogram;  {  Do  histogram  count  for  strings  ) 

END;  {  CASE  ) 

END;  {  Push  } 

END;  {  Count_Histogram  } 

PROCEDURE  Pop (VAR  Stk  :  Stack;  {  in/out  ) 

VAR  Element  :  Stack  Rec;  {  output  ) 

VAR  OK  :  BOOLEAN  {  output  }); 

(  Procedure  to  pop  'Element'  in  stack  } 

BEGIN 

WITH  Stk  DO  BEGIN 

OK  FALSE; 

End  Listing  One 

IF  Height  >  0 
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THEN  BEGIN 

OK  TRUE; 

Element  St ack_Member [Height ) ; 

Height  Height  -  1 
END;  (  IF  } 

END;  {  WITH  } 

END;  [  Push  } 


PROCEDURE  Select  ive_Pop  (VAR  Stic  :  Stack;  (  in/out  } 

VAR  Element  :  Stack  Rec;  {  in/out  } 

VAR  OK  :  BOOLEAN  T  output  }); 

{  Procedure  to  search  for  first  stack  element  that  matches  ) 

{  the  Switch  field  in  'Element'.  } 

VAR  I,  J  :  INTEGER; 

BEGIN 

WITH  Stk  DO  BEGIN 
OK  FALSE; 

I  Height; 

{  Attenpt  to  locate  element  of  desired  type  ) 

WHILE  (I  >  0)  AND  (NOT  OK)  DO 

IF  Element .Switch  -  Stack_Member (I] .Switch 
THEN  OK  TRUE 
ELSE  I  I  -  1; 

IF  OK  THEN  BEGIN  {  Found  one!  ) 

Element  Stack  Member [ I); 

(  Rearrange  stacJc  ) 

FOR  J  I  TO  Height- 1  DO 

Stack_Member (JJ  Stack_Member [ J+l ] ; 

Height  Height  -  1; 

END;  (  IF  | 

END;  (  WITH  ) 

END;  1  select ive_Pop  i  End  Listing  Three 


Listing  Four  A 


DEFINITION  MODULE  HPStackMod; 

EXPORT  QUALIFIED 

HPStack,  (*  Opaque  type  *) 

Enter,  Cist,  Add,  Sub,  Mul,  Div,  RclLast,  GetX;  (*  Procedures  *) 

TYPE  HPStack; 

PROCEDURE  Enter (VAR  Stack  :  HPStack;  (*  in/out  *) 

X  :  REAL  (*  input  *)); 

(*  Procedure  to  enter  a  number  in  the  stack  *) 

PROCEDURE  Cist  (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  clear  stack  and  LASTX  register  *) 

PROCEDURE  Add (VAR  Stack  :  HPStack  (•  in/out  *)); 

(*  Procedure  to  add  Y  and  X  registers  *) 

PROCEDURE  Sub (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  subtract  Y  and  X  registers  *) 

End  Listing  Four  A 

Listing  Four  B 


PROCEDURE  Mul (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  multiply  Y  and  X  registers  *) 

PROCEDURE  Div (VAR  Stack  :  HPStack;  (*  in/out  *) 

VAR  OK  :  BOOLEAN  (*  output  *) ) ; 

(*  Procedure  to  divide  Y  and  X  registers  *) 

PROCEDURE  RclLast  (VAR  Stack  :  HPStack  (*  in/out  *)); 
(*  Procedure  to  recall  LASTX  register  *) 

PROCEDURE  GetX  (Stack  :  HPStack  (*  input  •))  :  REAL; 
(*  Function  to  get  X  register  *) 

END  HPStackMod. 


Listing  Four  B. 

IMPLEMENTATION  MODULE  HPStackMod; 

(*  Module  implementing  scalar-based  RPN  stack  calculator  •) 

TYPE  HPStackRec  -  RECORD 

XReg,  YReg,  ZReg,  TReg,  LASTX  :  REAL; 

END; 

(*  Exported  opaque  type  *) 

HPStack  -  POINTER  TO  HPStackRec; 

PROCEDURE  StackDown; 

(* -  Internal  module  usage  - *) 

(*  Procedure  to  roll  down  Y,  Z  and  T  registers  *) 

BEGIN 

YReg  ZReg;  (*  Copy  Z  into  Y  *) 

ZReg  TReg  {*  Copy  T  into  Z  *) 

END  StackDown; 

PROCEDURE  Enter (VAR  Stack  :  HPStack;  (•  in/out  *) 

X  :  REAL  (*  input  *)); 

(*  Procedure  to  enter  a  number  in  the  stack  and  push  it  *) 

BEGIN 

WITH  Stack''  DO 

TReg  ZReg;  ZReg  YReg; 

YReg  XReg;  XReg:-  X 

END; 

END  Enter; 
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_ STRUCTURED  PROGRAMMING 

Listing  Four  B  (Listing  continued,  text  begins  on  page  116.) 


PROCEDURE  Cist (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  clear  stack  and  IASTX  register  *) 

BEGIN 

WITH  Stack*  DO 

XReg  0.0;  YReg  0.0;  ZReg  0.0; 

TReg  0.0;  IASTX  0.0; 

END; 

END  Cist; 

PROCEDURE  Add (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  add  Y  and  X  registers  *) 

BEGIN 

WITH  Stack*  DO 

IASTX  XReg;  (*  Save  X  reg.  in  IASTX  *) 

XReg  YReg  +  XReg; 

Stack Down 

END; 

END  Add; 

PROCEDURE  Sub (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  subtract  Y  and  X  registers  *) 

BEGIN 

WITH  Stack*  DO 

IASTX  XReg;  (*  Save  X  reg.  in  IASTX  *) 

XReg  YReg  -  XReg; 

Stack Down 

END; 

END  Sub; 

PROCEDURE  Mul(VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  multiply  Y  and  X  registers  *) 

BEGIN 

WITH  Stack*  DO 

IASTX  XReg;  (*  Save  X  reg.  in  IASTX  *) 

XReg  YReg  *  XReg; 

Stack Down 

END; 

END  Mul; 

PROCEDURE  Div (VAR  Stack  :  HPStack;  (*  in/out  *) 

VAR  OK  :  BOOLEAN  (*  output  *) ) ; 

(*  Procedure  to  divide  Y  and  X  registers  *) 

End  Listing  Four  B 


Listing  Four  C 


BEGIN 

OK  TRUE; 

WITH  Stack*  DO 

IF  StackReg(l)  <>  0.0  (*  Division  by  non-zero  ?  *) 
THEN 

IASTX  XReg;  (*  Save  X  reg.  in  IASTX  *) 

XReg  YReg  /  XReg; 

Stack Down 
ELSE  (*  Trouble  *) 

OK  FALSE 

END; 

END; 

END  Div; 

PROCEDURE  RclLast  (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  recall  LASTX  register  *) 

BEGIN 

WITH  Stack*  DO 

TReg  ZReg;  ZReg  YReg; 

YReg  XReg;  XReg  IASTX 

END; 

END  RclLast; 

PROCEDURE  GetX (Stack  :  HPStack  (*  input  *))  :  REAL; 

(*  Function  to  get  X  register  *) 

BEGIN 

RETURN  Stack*. XReg; 

END  GetX; 

END  HPStackMod. 

Listing  Four  C. 


IMPLEMENTATION  MODULE  HPStackMod; 

(*  Module  Implementing  array-based  RPN  stack  calculator  *) 


TYPE  HPStackRec  -  RECORD 

StackReg  :  ARRAY  (0..4)  OF  REAL; 

(*  Stack Reg(0)  is  LASTX,  StackReg [1)  is  X  Reg  *) 
(*  StackReg(2]  is  Y  Reg,  StackReg [3]  is  Z  Reg  *) 
(*  StackReg [4]  is  T  Reg  *) 

END; 

(*  Exported  opaque  type  *) 

HPStack  -  POINTER  TO  HPStackRec; 

PROCEDURE  StackDown; 

(* -  Internal  module  usage  - *) 

(*  Procedure  to  roll  down  Y,  Z  and  T  registers  *) 

BEGIN 

StackReg [2]  StackReg [3];  {*  Copy  Z  into  Y  *) 

StackReg(3]  StackReg[4]  (*  Copy  T  into  Z  *) 

END  StackDown; 


PROCEDURE  Enter (VAR  Stack  :  HPStack;  (*  in/out  *) 

X  :  REAL  (*  input  *)); 

(*  Procedure  to  enter  a  number  in  the  stack  *) 

VAR  I  :  CARDINAL; 

BEGIN 

WITH  Stack*  DO 

FOR  I  ;■  3  TO  1  BY  -1  DO 

StackReg [1+1]  StackReg [I] 

END; 

StackReg (1J  X 

END; 

END  Enter; 

PROCEDURE  Cist  (VAR  Stack  :  HPStack  (*  in/out  *)) ; 

(*  Procedure  to  clear  stack  and  LASTX  register  *) 

VAR  I  ;  CARDINAL; 

BEGIN 

WITH  Stack*  DO 

FOR  I  0  TO  4  DO 

StackReg (I)  0.0 

END; 

END; 

END  Cist; 

PROCEDURE  Add (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  add  Y  and  X  registers  *) 

BEGIN 

WITH  Stack*  DO 

StackReg(O)  StackReg[l);  (*  Save  X  reg.  in  LASTX  *) 
StackReg (1]  StackReg[2]  +  StackReg(l); 

StackDown 

END; 

END  Add; 

PROCEDURE  Sub (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  subtract  Y  and  X  registers  *) 

BEGIN 

WITH  Stack*  DO 

StackReg [0]  StackReg(l);  (•  Save  X  reg.  in  LASTX  *) 
StackReg [lj  StackReg(21  -  StackReg(l); 

StackDown 

END; 

END  Sub; 

PROCEDURE  Mul (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  multiply  Y  and  X  registers  *) 

BEGIN 

WITH  Stack*  DO 

StackReg [0]  StackReg(lJ;  (*  Save  X  reg.  in  LASTX  *) 
StackReg(l)  StackReg(2)  *  StackReg[l); 

StackDown 

END; 

END  Mul; 

PROCEDURE  Div (VAR  Stack  :  HPStack;  (•  in/out  *) 

VAR  OK  :  BOOLEAN  (*  output  *) ) ; 

(*  Procedure  to  divide  Y  and  X  registers  *) 

BEGIN 

OK  TRUE; 

WITH  Stack*  DO 

IF  StackReg (1)  <>  0.0  (*  Division  by  non-zero  ?  *) 

THEN 

StackReg (0]  StackReg (1);  (*  Save  X  reg.  in  LASTX  *) 
StackRegdJ  StackReg[2]  /  StackReg[l]; 

StackDown 
ELSE  (*  Trouble  *) 

OK  FALSE 

END; 

END; 

END  Div; 

PROCEDURE  RclLast (VAR  Stack  :  HPStack  (*  in/out  *)); 

(*  Procedure  to  recall  LASTX  register  *) 

VAR  I  :  CARDINAL; 

BEGIN 

WITH  Stack*  DO 

FOR  I  4  TO  1  BY  -1  DO 

StackReg [I]  StackReg [1-1] 

END; 

END; 

END  RclLast; 

PROCEDURE  GetX (Stack  :  HPStack  (*  input  *))  :  REAL; 

(*  Function  to  get  X  register  *) 

BEGIN 

RETURN  Stack* . StackReg [ 1 ] ; 

END  GetX; 

END  HPStackMod. 


End  Listings 
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The DVP and FORCDUP 
Functions 

S-DOS  functions  45H  ( DUP )  and 
46H  ( FORCDUP )  have  always 
been  considered  a  little  mysterious, 
except  perhaps  by  those  program¬ 
mers  who  were  nurtured  under 
Unix.  Both  functions  were  added  to 
MS-DOS  in  Version  2.0  at  the  same  time 
as  were  the  "extended  file  manage¬ 
ment”  functions,  and  their  documen¬ 
tation  is  a  bit  spare.  The  description 
in  the  PC-DOS  Technical  Reference 
Manual  for  function  45H  simply  says 
that  it  "returns  a  new  file  handle  that 
refers  to  the  same  file  at  the  same  po¬ 
sition,”  and  the  explanation  for  func¬ 
tion  46H  is  that  it  “forces  the  handle 
in  CX  to  refer  to  the  same  file  at  the 
same  position  as  the  handle  in  BX.  ”  In 
actuality,  both  of  these  functions  are 
much  more  useful  than  the  docu¬ 
mentation  suggests. 

The  DUP  function  (45H)  is  particu¬ 
larly  convenient  in  applications  that 
perform  extensive  file  manipulation. 
Normally,  the  directory  entry  for  a 
file  is  updated  to  reflect  only  the  time 
and  date  last  modified  and  the  new 
length  (if  the  file  has  been  extended) 
when  the  file  is  closed.  If  your  appli¬ 
cation  extends  a  file  and  then  crashes 
before  closing  the  file,  the  new  infor¬ 
mation  at  the  end  of  the  file  is  left 
floating  in  the  form  of  lost  clusters. 
Therefore,  in  programs  that  run  for 
long  periods,  it  would  seem  most 
wise  to  close  and  reopen  a  file  when¬ 
ever  its  length  has  been  changed. 

Unfortunately,  the  overhead  of  an 
open  operation  in  MS-DOS  is  consider- 
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able,  especially  if  the  desired  file  is  at 
the  end  of  a  fairly  long  path  and  is  not 
in  the  current  directory.  You  can 
avoid  the  open  function  altogether 
and  still  get  your  desired  updating  of 
the  directory  by  DUPing  the  handle 
for  the  open  file  and  closing  the  du¬ 
plicate.  The  close  function  turns  out 


to  be  relatively  fast  in  MS-DOS.  See  List¬ 
ing  One,  page  106,  for  an  example  of 
this  technique. 

The  DUPed  handle  does  subtract 
one  from  the  maximum  of  20  simul¬ 
taneously  active  handles  allowed  for 
your  process  while  it  is  open,  but  it 
doesn’t  count  against  the  total  num¬ 
ber  of  open  handles  allowed  for  the 
system  as  a  whole  (the  system  total  is 
set  with  th e  files  =  command  in  the 
config.sys  file  and  defaults  to  eight). 

The  FORCDUP  function  ( 46H )  can  be 
used  to  redirect  the  input/output  for 
any  handle,  previously  opened  to 
any  logical  device  or  file,  to  any  other 
open  device  or  file.  The  ramifications 
of  this  seem  endless,  but  I  suspect 
FORCDUP’s  most  common  use  is  with 
the  EXEC  function  to  affect  the  behav¬ 
ior  of  the  standard  devices  for  child 
processes.  Because  the  open  handles 
of  the  parent  program  are  inherited 
by  the  child,  any  desired  redirection 
of  the  child's  input  or  output  can  sim¬ 
ply  be  put  into  effect  at  the  parent’s 
level  before  EXEC  is  called. 

Jerry  Jankura  has  been  kind 
enough  to  donate  a  program  that  il¬ 
lustrates  the  use  of  FORCDUP  to  per¬ 
form  I/O  redirection.  It  accompanies 
this  month's  column  as  Listing  Two, 
page  106. 

DOS  Two-Point-What? 

Last  October,  Microsoft  released  a  re¬ 
vision  of  MS-DOS  that  hardly  anyone 
has  heard  of — Version  2.25. 

The  main  reason  for  MS-DOS  2.25’s 
existence  seems  to  be  its  enhanced 
character  set  support  and  interim 
character  support,  designed  for  the 
Far  East  OEMs  that  must  support  lan¬ 
guages  such  as  kanji  and  Korean.  The 


ASSIGN  and  LABEL  commands  were 
added  from  MS-DOS,  Version  3.  In  ad¬ 
dition,  MS-DOS  2's  DEBUG,  SORT,  and 
EDL1N  commands  were  replaced  by 
MS-DOS  3.x’s  versions  of  the  same. 
Many  bugs  reported  in  previous  ver¬ 
sions  of  MS-DOS  (2.11  and  earlier)  were 
fixed. 

Don’t  look  for  this  version  at  your 
corner  software  store  any  time  soon, 
though.  Most  U.S.  OEMs  appear  to  be 
ignoring  it,  even  though  it  has  less 
bugs,  remains  memory  economical, 
and  adds  some  of  the  desirable  fea¬ 
tures  of  MS-DOS  3.x. 

Windows  Development  Kit 

Since  its  release  late  last  year,  Micro¬ 
soft  Windows  has  had  surprisingly 
good  market  acceptance  and  in  fact 
has  been  on  the  Softsel  best-seller  list 
for  the  last  month  as  I  write  this.  Al¬ 
though  Windows  is  rather  slow  on 
the  original  8088-based  PC  and  is 
nearly  unbearable  without  a  hard 
disk,  Windows  on  a  PC/AT  with  an 
EGA  is  responsive  and  a  pleasure  to 
use.  Prices  for  80286-based  PCs  and 
fixed  disks  are  decreasing  rapidly,  so 
it  appears  that  if  Windows  was  be¬ 
fore  its  time  hardwarewise,  it  was 
only  just  a  little — though  any  signifi¬ 
cant  penetration  into  the  older  PC 
user  base  will  probably  require  the 
widespread  availability  of  cheap  tur¬ 
bo  expansion  boards  and  expanded 
memory  boards. 

Because  of  the  dismal  fates  of  Vi¬ 
sion  and  the  PC  version  of  GEM  (seen 
any  of  those  full-page  color  ads  for 
GEM  lately?),  I  was  uncertain  wheth¬ 
er  it  was  worth  the  time  to  pay  any 
attention  to  Windows,  how  it  works, 
and  the  machinations  needed  to 
write  well-behaved  Windows  appli¬ 
cations.  The  preliminary  Windows 
development  kit  I  received  a  year  or 
so  ago  was  intimidating  to  say  the 
least,  written  as  it  was  in  the  now- 
famous,  infinitely  self-referencing 
style  of  Inside  Macintosh.  To  try  and 
get  some  feeling  for  the  future  of 
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Windows,  I  attended  Microsoft’s 
Windows  Developer  Seminar  in  Feb¬ 
ruary  in  Seattle.  I  came  away  from 
this  seminar  with  a  changed  outlook 
on  Windows  and  what  it  portends 
for  the  future. 

First,  there  is  some  confusion  in  the 
world  of  programmers  about  exactly 
what  Windows  is.  Windows  is  not  a 
desktop  metaphor  user  interface  like 
the  one  on  the  Mac.  Icons  are  used  in 
Windows  only  to  symbolize  tasks 
that  are  currently  active  in  memory 
but  do  not  have  an  open  window  or 
occasionally  to  select  a  resource  (such 
as  changing  from  one  default  disk 
drive  to  another).  Icons  are  not  used 
in  Windows  to  represent  and  manip¬ 
ulate  objects  (files  or  programs)  on  a 
disk — you  can't  erase  a  file  by  drop¬ 
ping  an  icon  in  a  wastebasket  or  copy 
a  file  by  dragging  an  icon  from  one 
place  to  another,  for  example. 

Windows  is  a  multitasking  execu¬ 
tive,  running  on  top  of  (and  closely  in¬ 
tertwined  with)  MS-DOS,  that  offers  so¬ 
phisticated  memory  management, 
dynamic  loading  and  linking  of  code 
segments,  intertask  communication,  a 
standardized  virtual  keyboard  and 
pointing-device  interface,  and  device¬ 
independent  graphics  services.  Al¬ 
though  Windows  does  have  pull¬ 
down  menus,  tiled  windows,  scroll 
bars,  and  dialog  boxes,  these  are  in  a 
way  tangential  to  the  intent  and  func¬ 
tion  of  Windows.  A  pointing  device 
can  be  used  to  advantage  in  Windows, 
but  unlike  the  Mac,  you  can  also  get 
along  quite  nicely  without  one.  The 
fact  that  well-behaved  Windows  ap¬ 
plications  will  have  a  rather  uniform 
user  interface  that  dramatically  short¬ 
ens  the  learning  curve  for  new  users 
(as  do  Mac  applications)  can  be  viewed 
as  just  a  nifty  fringe  benefit. 

You  are  probably  saying  to  your¬ 
self,  “That  all  sounds  great,  but  why 
should  I  as  a  programmer  who  uses 
MS-DOS  worry  about  Windows  now? 
Why  not  wait  a  year  or  two  and  see  if 
Windows  has  any  significant  pene¬ 
tration  of  the  user  base  I  am  con¬ 
cerned  with  and  then  decide  wheth¬ 
er  to  learn  about  its  innards.”  You 
may  be  right.  On  the  other  hand,  Mi¬ 
crosoft  made  it  clear  at  the  seminar 
that  much  of  the  functionality  of  to¬ 
day’s  Windows  (especially  the  multi¬ 
tasking  and  memory  management) 
will  be  migrated  downward  into  the 
MS-DOS  kernel  in  future  versions.  In  a 


sense,  Windows  can  be  thought  of  as 
a  sneak  preview  of  DOS  4  and  5  (in 
fact,  the  combination  of  MS-DOS  2  or  3 
and  Windows  provides  everything 
we  were  hoping  for  in  the  expected 
multitasking  MS-DOS  for  the  8086/88- 
based  PCs,  and  then  some). 

Windows  apparently  has  even 
more  significance  for  80826-based 
PCs.  Many  of  us  have  been  a  bit  ap¬ 
prehensive  about  the  upcoming  Pro¬ 
tected  Mode  versions  of  MS-DOS.  Mi¬ 
crosoft  has  been  quite  guarded  on 
this  topic  until  now,  and  the  outlook 
has  been  further  confused  by  leaks 
from  IBM  that  it  is  developing  its  own 
Protected  Mode  operating  system 
and  by  IBM's  recent  announcement 
that  it  is  planning  to  use  Digital  Re¬ 
search’s  Concurrent  DOS  on  a  PC/AT- 
based  point-of-sale  product.  At  the 
seminar,  Microsoft  officials  (includ¬ 
ing  Steve  Ballmer  and  Bill  Gates)  were 
suddenly  surprisingly  forthcoming 
with  details  about  a  Protected  Mode 
MS-DOS.  This  may  indicate  that  the 
major  problems  connected  with  this 
product  have  finally  been  solved. 

During  a  panel  discussion  with 
members  of  the  Windows  develop¬ 
ment  team  and  some  outside  Win¬ 
dows  application  developers,  Gates 
asserted  that  the  Protected  Mode  ver¬ 
sion  of  MS-DOS  will  be  completely  up¬ 
ward  compatible  with  current  MS- 
DOS  versions  and  applications. 
Programs  that  are  not  well  behaved 
(such  as  those  that  write  directly  to 
the  video  refresh  buffer)  will  simply 
be  executed  in  Real  Mode  and  the 
fact  that  the  operating  system  runs  in 
Protected  Mode  will  be  invisible  to 
them.  In  a  way,  this  commitment  to 
upward  compatibility  is  somewhat 
unfortunate.  Programs  running  in 
Real  Mode,  even  under  the  control  of 
a  Protected  Mode  OS,  can  circumvent 
the  80286 's  mechanisms  for  protect¬ 
ing  one  task  from  another. 

In  other  seminar  sessions,  guide¬ 
lines  were  given  for  writing  well-be¬ 
haved  programs  under  current  ver¬ 
sions  of  MS-DOS  that  will  be  able  to 
run  in  Protected  Mode  on  future  ver¬ 
sions  and  take  full  advantage  of  the 
16-megabyte  memory  space. 
Ballmer,  who  has  taken  much  of  the 
flack  for  the  many  delays  in  Win¬ 
dows  and  was  the  author  of  the  fa¬ 
mous  "before  the  snow  falls”  an¬ 
nouncement,  made  a  startling 
assertion.  He  said  that  well-behaved 


Windows  applications  created  with 
the  Windows  development  kit  will 
run  in  Protected  Mode  on  the  upcom¬ 
ing  PM  version  of  MS-DOS  without  re¬ 
compilation. 

As  for  its  own  commitment  to  Win¬ 
dows,  Microsoft  laid  it  on  the  line  in 
unmistakable  terms.  The  company 
said  that  all  future  Microsoft  applica¬ 
tions  (not  languages)  for  the  IBM  PC 
that  are  not  just  evolutionary  up¬ 
grades  of  existing  packages  will  be 
Windows-dependent.  Apparently,  a 
port  of  Excel  from  the  Mac  to  the  PC 
is  already  underway  for  Windows. 
At  first  glance,  such  a  policy  seems  a 
bit  rash,  but  it  may  not  be  as  risky  as  it 
sounds.  The  current  Microsoft  appli¬ 
cation  packages  for  the  PC  (Word, 
Multiplan,  and  so  forth)  have  been 
quite  popular,  and  their  quality  is 
high;  if  future  packages  live  up  to  the 
same  standards,  they  may  prove  in 
themselves  to  be  a  potent  driving 
force  for  Windows. 

Those  of  us  who  attended  the  semi¬ 
nar  each  received  a  copy  of  the  new 
retail  release  of  the  Windows  Soft¬ 
ware  Development  Kit.  This  is  a  for¬ 
midable  package  indeed,  consisting  of 
some  900  pages  of  typeset  documenta¬ 
tion  in  two  volumes  and  a  fistful  of 
diskettes.  The  12  floppies  hold  a  spe¬ 
cial  version  of  Windows  with  debug¬ 
ging  support,  Windows  function  li¬ 
braries  for  C  and  Pascal,  a  library  of 
macros  for  the  folk  determined  to 
stick  with  assembler,  an  update  to  cer¬ 
tain  parts  of  the  Microsoft  C  3.0  com¬ 
piler,  a  special  linker,  a  modified  SYM- 
DEB  that  can  be  used  with  an  external 
terminal  or  hooked  to  the  PC’s  serial 
port,  a  dialog  box  editor,  and  so  forth. 
A  diskful  of  C  source  code  for  sample 
Windows  applications  is  also  includ¬ 
ed.  Of  course,  in  order  to  develop 
Windows  programs,  you  must  also 
buy  the  Microsoft  C  compiler,  Pascal 
Compiler,  or  Macro  Assembler  sepa¬ 
rately. 

The  manuals  for  the  development 
kit  are  nicely  laid  out  and  typeset  but 
consist  largely  of  reference  material 
that  is  extremely  dense.  Only  about  a 
quarter  of  the  material  gives  any 
guidance  on  the  overall  program¬ 
ming  of  a  Windows  application,  and 
even  in  that  section,  it's  rather  diffi¬ 
cult  to  see  the  forest  for  the  trees.  At 
the  seminar,  very  helpful  talks  giving 
a  more  cosmic  view  were  given  by 
Microsoft  programmers  who  have 
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been  working  within  the  Windows 
environment  for  two  years  or  more 
and  an  additional  volume  of  proceed¬ 
ings,  programming  guidelines,  de¬ 
bugging  examples,  and  sample 
source  code  was  given  to  each  attend¬ 
ee.  Taken  together,  these  remove 
much  of  the  start-up  fright  factor 
from  coding  for  Windows.  If  you  are 
considering  or  embarking  on  a  Win¬ 
dows-specific  application,  I’d  highly 
recommend  that  you  sign  up  for  one 
of  the  scheduled  developer’s  semi¬ 
nars — it  will  save  you  dollars  and 
hours  in  the  long  run. 

At  this  time,  the  ante  for  program¬ 
mers  who  want  to  work  with  Win¬ 
dows  is  high.  By  the  time  you  add  up 
the  cost  of  a  PC/AT  with  512K  RAM,  a 
hard  disk  and  an  EGA  (the  develop¬ 
ment  configuration  I  would  recom¬ 
mend),  the  Windows  development 
kit,  the  Microsoft  C  compiler,  and 
possibly  a  trip  to  Bellevue  or  Boston 
to  attend  the  Microsoft  Windows 
classes,  you  are  talking  about  a  lot  of 
money.  And  if  you  aren't  a  C  pro¬ 
grammer,  you’re  largely  out  of  luck 
for  the  present.  The  Pascal  and  as¬ 
sembler  support  for  Windows  devel¬ 
opment  seems  rather  half-hearted  at 
best,  and  there  are  no  bindings  at  all 
for  FORTRAN,  COBOL,  or  BASIC  compil¬ 
ers. 

If  Microsoft  is  really  committed  to 
get  Windows  moving  among  soft¬ 
ware  developers,  I  have  a  few  sug¬ 
gestions  for  things  it  could  do  rela¬ 
tively  quickly:  release  a  Windows- 
specific  version  of  BASIC  similar  to 
Mac  BASIC;  release  a  low-cost  set  of 
QuickBASIC  bindings  to  Windows;  re¬ 
lease  a  lower  cost,  simplified  Win¬ 
dows  development  kit  for  C  pro¬ 
grammers;  and  release  a  Turbo 
Pascal  Windows  toolkit.  All  these 
things  should  be  priced  around  $100 
to  remove  them  from  the  "I  wonder 
if  I  can  talk  my  company  into  buying 
this”  category  and  put  them  in  the 
MasterCard/Visa,  impulse-buy  cate¬ 
gory.  Of  course,  I  am  writing  this  in 
February,  so  when  you  read  this  in 
June,  some  lower-cost  developer 
products  may  already  be  history. 

The  development  kit  can  be  or¬ 
dered  directly  from  the  Microsoft  Te¬ 
lemarketing  Group  [(800)  426-9400] 
and  currently  costs  $500. 


I  Building  Overlays 

1  Dr.  Glenn  Roberts  of  the  Mitre  Corp. 
j  responded  to  David  Rabber's  request 
for  information  on  the  overlay  capa¬ 
bility  of  the  Microsoft  linker  (Decem¬ 
ber  1985  column).  He  writes:  "We  ob¬ 
tained  Version  3.01  of  the  Microsoft 
linker  as  part  of  the  Microsoft  C  com¬ 
piler  package.  This  version  of  the  link¬ 
er  supports  overlays  and  the  follow- 
j  ing  information  on  it  is  condensed 
j  from  the  Microsoft  documentation. 
"You  specify  overlays  in  the  list  of  j 
modules  that  you  submit  to  the  linker 
by  enclosing  them  in  parentheses. 
Each  parenthetical  list  represents 
one  overlay.  As  an  example,  if  the  fol- 
j  lowing  were  your  response  to  the 
'Object  Modules’  prompt: 

Object  Modules  [.OBJ]: 

a  -Mb + c)  -I-  (e + f) + g  -Hi) 

then  (h+c),  (e  +f,  and  i  are  overlays. 
"Some  pertinent  notes: 

•  Overlays  are  loaded  into  the  same  re¬ 
gion  of  memory,  so  only  one  can  be 
resident  at  a  time. 

•  Duplicate  names  in  different  over¬ 
lays  are  not  supported,  so  each  mod¬ 
ule  can  occur  only  once  in  a  program. 
•The  linker  replaces  calls  from  the 
root  to  an  overlay  and  calls  from  an 
overlay  to  another  overlay  with  a 
software  interrupt,  followed  by  the  J 
module  identifier  and  offset.  The  de-  | 
fault  interrupt  for  calling  this  overlay 
manager  is  03FH. 

•  The  names  of  the  overlays  are  ap¬ 
pended  to  the  EXE  file,  and  the  name 

i  of  this  file  is  encoded  into  the  pro¬ 
gram  so  that  the  overlay  manager 
can  access  it.  If  the  manager  cannot 
find  this  file,  it  will  prompt  you  for 
the  file's  name.  After  you’ve  supplied 
the  name,  you  can  later  swap  disks  in 
the  associated  drive.  The  overlay 
|  manager  will  detect  this  when  it  J 
needs  an  overlay  that  is  on  a  disk  that  I 
has  been  removed  and  will  prompt  j 
I  you  to  replace  the  disk  and  ‘strike 
any  key  when  ready.’ 

•  The  overlay  manager  is  smart  J 
|  enough  to  search  the  current  path  i 

for  the  EXE  file. 

•  Control  to  overlay  modules  must  be 
|  passed  through  far  call/return  se¬ 
quences  because  the  linker  finds 
these  and  replaces  them  with  the  ! 
overlay  interrupt.  This  rules  out  the 
use  of  indirect  calls  across  overlays  | 


via  pointers. 

•  You  can  change  the  default  inter¬ 
rupt  used  to  call  the  overlay  manager 
using  a  switch  on  the  linker: 

/OVERLAYlNTERRUPTmumber 

where  number  can  be  o— 0FFH. 

"I  should  mention  that  I  haven't  ex¬ 
perimented  with  the  overlaying  capa¬ 
bilities  of  this  linker.  I’ve  merely  stat¬ 
ed,  in  condensed  form,  the 
information  in  the  Microsoft  docu¬ 
mentation.” 

Another  Resource  for 
Programmers 

The  Programmer's  Journal,  edited  by 
Robert  Keller,  is  rapidly  developing 
into  a  sort  of  modern-day  equivalent 
of  the  original  Dr.  Dobb's  Journal  of 
Computer  Calisthenics  and  Orthodon¬ 
tia.  Casual  and  gossipy,  yet  stuffed 
with  useful  information,  it  definitely 
deserves  a  look.  Contact  the  maga¬ 
zine  at  P.O.  Box  30160,  Eugene,  OR 
97403;  (503)  484-2162. 

DDJ  on  CompuServe 

One  of  the  Data  Libraries  (DL2)  on  the 
CompuServe  DDJ  Forum  is  devoted  to 
the  16-Bit  Software  Toolbox,  and  most 
of  the  program  listings  published 
here  in  the  last  year  or  so  are  already 
available  for  downloading.  If  there 
are  particular  programs  from  farther 
back  in  the  history  of  this  column  that 
you  would  like  to  see  placed  on  the 
DL,  please  let  me  know.  Also,  I’d  like 
to  encourage  everyone  to  use  the  DDJ 
Forum  to  send  me  comments,  sugges¬ 
tions,  criticisms,  and  programs.  I  guar¬ 
antee  quick  response! 

DDJ 
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In  this  column  dedicated  to  Pascal, 
Ada,  and  Modula-2 — descendants 
of  the  ALGOL  language — I  will  discuss 
language  and  implementation  issues 
as  well  as  applications  written  in 
them.  The  livelihood  of  any  column 
draws  from  readers'  interaction. 
DDJ's  CompuServe  forum  is  an  excel¬ 
lent  place  for  fast  feedback  and  dia¬ 
logue;  the  U.S.  mail  is  the  slower  alter¬ 
native.  You  are  invited  to  share  your 
tips,  tricks,  and  programming 
techniques. 

In  this  issue  I’ll  discuss  two  topics. 
The  first  part  of  the  column  deals 
with  simulating  overloaded  proce¬ 
dures  and  functions  in  Pascal  and 
Modula-2.  The  second  part  looks  at 
exporting  opaque  types  and  data  hid¬ 
ing  in  Modula-2. 

Overloading  Procedures 

An  overloaded  procedure  or  func¬ 
tion  is  one  that  exists  simultaneously 
in  several  different  versions  within 
the  same  program.  This  allows  you  to 
use  the  same  procedure  call  with  sev¬ 
eral  different  kinds  of  arguments.  An 
example  of  this  is  the  Pascal  intrinsic 
Writelinef  ),  which  can  take  any 
number  of  arguments  with  many  dif¬ 
ferent  data  types.  Unfortunately,  Pas¬ 
cal  and  Modula-2  do  not  allow  you  to 
write  overloaded  routines  explicitly 
because  you're  not  allowed  to  create 
two  functions  or  procedures  with  the 
same  name  in  the  same  code  body. 

A  Modula-2  program  can  import 
different  libraries  that  may  contain 
procedures  with  the  same  name. 
Thus  you  can  import  an  entire  li¬ 
brary  and  use  the  overloaded  proce- 


Namir  Clement  Shammas 

dure  prefixed  with  the  library  name. 
Consider,  for  example,  two  library 
modules  ReallnOut  and  (a  fictitious) 
LongReallnOut  that  take  types  REAL 
and  LONCREAL,  respectively,  and 
both  contain  a  procedure  called 
WriteReaK  J.  To  use  the  overloaded 
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WriteReaK  )  procedure,  you  can  call 
ReallnOut.WriteReaK  )  or  LongRealln¬ 
Out. WriteReaK  ).  Because  the  two 
procedures  called  WriteReal  are  in 
different  modules,  the  Modula-2 
compiler  is  able  to  accept  them. 

Variant  records  provide  a  way  to 
create  "simulated”  overloaded  pro¬ 
cedures.  The  simulation  stems  from 
the  fact  that  there  is  really  only  one 
copy  of  the  procedure.  Admittedly,  a 
bit  more  effort  is  required  to  make 
such  procedures  readable.  The  vari¬ 
ant  parts  of  a  record  enable  the  pro¬ 
gram  to  tackle  different  data  items 
varying  in  basic  type  or  number.  I'll 
use  three  examples.  The  first  over¬ 
loads  a  routine  that  handles  arrays  of 
different  basic  data  types.  In  this 
case,  the  macro  structures  are  similar 
or  identical  but  the  micro  structures 
are  different.  The  second  case  deals 
with  representing  the  same  informa¬ 
tion  with  alternate  notations.  The 
third  case  shows  a  stack  containing 
data  structures  of  several  types. 

The  first  example  (see  Listing  One, 
page  108)  shows  a  Pascal  procedure 
to  perform  a  histogram  count.  In  gen¬ 
eral,  the  input  is  an  array  of  data 
items  accompanied  by  an  array  of 
perfectly  sorted  histogram  bin  limits 
Each  bin  limit  gives  the  upper  and 
lower  bounds  for  the  values  to  fall 
within  one  of  the  output  slots  of  the 
histogram.  This  gives  the  flexibility 
that  the  histogram  bin  sizes  need  not 
be  equal.  Data  values  lying  outside 
the  histogram  limits  are  ignored.  The 
procedure  Count— Histogram  is  capa¬ 
ble  of  handling  arrays  of  REAL  as  well 
as  arrays  of  STRING  data  types.  For 
the  latter  type,  the  variant  records 
supply  additional  information.  They 


include  two  integers  that  mark  the 
first  and  last  characters  (within  each 
string)  of  the  substrings  to  be  used  for 
the  bin  comparison.  Notice  that  the 
Count  array  is  the  only  output  in  the 
variant  record.  Procedure  Count- 
Histogram  has  its  own  local  proce¬ 
dures  to  perform  the  frequency 
count  for  each  different  data  type. 
You  can  easily  add  similar  proce¬ 
dures  to  handle  arrays  of  integers  or 
characters. 

Similar  routines  can  be  written  to 
implement  various  searching  and 
sorting  techniques.  In  a  future  col¬ 
umn  I  will  discuss  generic  sorting. 
Generic  routines  provide  a  flexible 
solution  to  handle  a  wider  variation 
in  data  types. 

The  second  example,  shown  in 
Listing  Two,  page  108,  looks  at  the  sit¬ 
uation  in  which  information  can  be 
represented  by  alternate  notations. 
You  can  represent  a  complex  num¬ 
ber  (that  is,  a  point  on  a  two-dimen¬ 
sional  graph)  either  by  using  rectan¬ 
gular  coordinates  (x  and  y)  or  by 
polar  coordinates  (modulus  and  an¬ 
gle).  Thus  you  can  have  two  sets  of 
data  each  consisting  of  two  REAL 
numbers.  To  process  the  information 
you  must  know  what  sort  of  coordi¬ 
nates  are  supplied.  Listing  Two 
shows  a  simple  Pascal  procedure  to 
add  two  complex  numbers.  Each  of 
the  numbers  can  be  supplied  to  the 
procedure  as  rectangular  or  polar  co¬ 
ordinates,  indicated  by  the  Is— Polar 
field.  Similarly  the  output  can  be  ob¬ 
tained  in  either  coordinate  system. 
The  example  can  be  extended  to  sys¬ 
tems  of  three  or  more  dimensions. 

The  third  example  presents  a  stack 
that  handles  a  variety  of  data  types. 
Here,  the  differently  typed  items  are 
more  logically  related.  Compared 
with  the  histogram  count  example  in 
which  different  data  types  are  han¬ 
dled  in  parallel,  this  one  handles 
them  in  series. 

The  fields  of  the  variant  portion 
contain  the  same  number  of  identifi- 
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ers;  only  the  types  are  different.  List¬ 
ing  Three,  page  108,  shows  three  Pas¬ 
cal  routines  to  push,  pop,  and 
selectively  pop  stack  items.  The  na¬ 
ture  of  stack  and  queue  manipula¬ 
tions  permits  them  to  accept  multi¬ 
type  data  in  certain  applications. 
Notice  that  the  variant  record  con¬ 
tains  user-defined  record  structures. 
You  can  add  more  variant  fields 
without  changing  the  code  for  the 
procedures.  Unordered  lists  (single- 
and  double-linked)  can  be  construct¬ 
ed  in  a  similar  manner. 

Exporting  Opaque  Types 
and  Data  Hiding 

An  opaque  data  type  is  one  that  in¬ 
cludes  no  representation  of  the  inter¬ 
nal  structure  of  the  data.  An  example 
is  the  type  REAL,  the  internal  struc¬ 
ture  of  which  (the  exponent  and 
mantissa,  along  with  their  signs)  is 
not  available  to  the  programmer.  The 
Modula-2  feature  of  exporting 
opaque  types  and  data  hiding  (some¬ 
times  referred  to  in  Modula-2  books 
as  data  abstraction)  has  been  with  us 
all  along,  but  originally  it  was  a  luxu¬ 
ry  only  compiler  writers  enjoyed.  It 
was  impossible  for  us  to  use  a  data 
type  exported  from  another  module 
or  library  without  explicitly  stating 
its  internal  structure.  Now  this  situa¬ 
tion  has  changed  with  developments 
in  software  and  hardware,  and  Mo¬ 
dula-2  offers  similar  privileges  to  li¬ 
brary  module  developers.  This  is 
done  by  having  the  definition  mod¬ 
ule  state  the  exported  data  type  name 
only,  with  no  structure  definition. 
Hence,  the  opaque  type  is  born.  The 
implementation  module  has  the 
complete  type  definition  along  with 
all  the  routines  to  manipulate  it.  Mo¬ 
dula-2  requires  that  opaque  types  be 
defined  as  pointers  to  other  data 
types.  The  client  programs  importing 
the  opaque  types  do  not  have  access 
to  their  internal  structure,  and  thus 
they  cannot  have  their  own  proce¬ 
dures  to  manipulate  the  opaque 
types.  The  library  developer  is  re¬ 
sponsible  for  providing  every  rou¬ 
tine  needed! 

By  hiding  the  internal  structure  of 
an  opaque  type,  library  authors  can 
modify  it,  and  the  procedure  bodies, 
without  affecting  client  programs. 
They  may  want  to  do  this  for  a  vari¬ 
ety  of  reasons,  such  as  prototyping  or 
discovering  a  superior  or  more  con¬ 


venient  alternate  structure. 

Applications  for  exporting  opaque 
types  are  numerous.  The  simplest  ex¬ 
ample  is  string  libraries.  Table  1, 
below,  shows  four  alternative  defini¬ 
tions  for  an  opaque  string  type.  The 
first  three  string  types  use  a  finite  ar¬ 
ray  to  store  characters.  The  fourth 
type  uses  true  dynamic  dimensioning 
by  employing  the  imported  type 
ADDRESS. 

The  type  stringl  is  straightfor¬ 
ward.  The  implementation  proce¬ 
dures  must  rely  on  ASCII  zero  code  as 
the  string  terminator  for  partially 
filled  strings.  The  type  string2  incor¬ 


porates  a  string  length  counter.  Using 
it  along  with  the  predefined  HIGH( ) 
function,  which  returns  the  upper 
bound  of  the  character  array,  the  ap¬ 
propriate  string  lengths  are  man¬ 
aged.  Exporting  this  type  as  transpar¬ 
ent  may  cause  problems  with  user- 
written  procedures  that  corrupt  the 
length  counter,  and  thus  the  use  of  an 
opaque  type  in  this  situation  is  more 
attractive  and  justifiable.  The  third 
type  is  a  slight  modification  of 
string2,  adding  a  total  string  counter. 
Ford  and  Wiener1  discuss  this  string 
type  and  point  out  that  the  structure 
uses  the  total  length  field  dynamical- 


CONST  MaxLength  =  255;  (*  or  any  other  length,  up  to  65535  *) 

(*  Alternative  #  1  *) 

TYPE  Stringl  =  POINTER  TO  RECORD 

strch  :  array  [0.. MaxLength]  OF  char 

END: 

(*  Alternative  #  2  *) 

TYPE  String2  =  POINTER  TO  RECORD 
long  :  CARDINAL; 

strch  :  ARRAY  [0.. MaxLength]  OF  CHAR 

END: 

(*  Alternative  #  3  *) 

TYPE  String3  =  POINTER  TO  RECORD 
long, 

TotalLength  :  CARDINAL; 

strch  :  array  [0.. MaxLength]  OF  CHAR 

end: 

(*  Alternative  #  4  *) 

(*  Note:  ADDRESS  type  is  imported  from  module  system  *) 

TYPE  String4  =  POINTER  TO  RECORD 
long, 

TotalLength  :  CARDINAL; 
strch  :  ADDRESS 

END: 


Table  1:  Alternative  Modula-2  opaque  string  structures 


(*  Matrix  may  have  negative  indices  *) 

TYPE  Matrixl  =  POINTER  TO  RECORD 
FirstRowIndex, 

LastRowIndex, 

FirstColumlndex 
LastColumlndex  :  INTEGER; 

(*  ADDRESS  is  Imported  from  SYSTEM  *) 
MatrixMember :  ADDRESS 

END; 

(*  Matrix  with  zero  or  positive  indices  *) 

TYPE  Matrix2  =  POINTER  TO  RECORD 
LastRowIndex  , 

LastColumlndex  :  CARDINAL; 

(*  ADDRESS  is  Imported  from  SYSTEM  *) 
MatrixMember :  ADDRESS 

END; 


Table  2:  Dynamic  opaque  matrix  structure 
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ly.  The  ALLOCATE (  )  procedure  is 
used  instead  of  NEW( )  to  accomplish 
the  above  task.  Employing  ALLOCATE 
forces  the  run-time  system  to  create  a 
dynamic  structure  according  to  the 
actual  record  size,  which  may  be 
smaller  than  the  maximum  allowa¬ 
ble  size.  The  fourth  string  type  dif¬ 
fers  from  the  others  in  that  none  of  its 
fields  is  an  array  of  characters.  Like 
string3  it  contains  fields  to  keep  track 
of  the  current  string  length  and  the 
total  size  is  dynamically  allocated. 
The  field  of  type  ADDRESS  is  the 
pointer  that  locates  the  actual  charac¬ 
ter  string.  The  advantage  of  type 
string4  is  the  creation  of  strings  with 
tailored  sizes. 

Another  example  of  alternative 
representation  is  complex  numbers, 
discussed  earlier.  It  is  possible  to  have 
two  library  implementation  modules: 
one  for  rectangular  coordinates,  the 
other  for  polar  coordinates  (see  Ford 
and  Weiner:  177).  Because  opaque 


types  are  involved,  procedures  to  cre¬ 
ate  and  return  the  real  and  imaginary 
parts  of  a  complex  number  must  be 
supplied  to  client  programs. 

Modula-2  supports  only  one-di¬ 
mensional  open  arrays  in  procedure 
arguments.  Ford  and  Wiener  present 
a  dynamic  matrix  library  exported  as 
an  opaque  data  type.  The  matrix  is 
defined  as  a  pointer  to  a  record  that 
contains  the  upper  and  lower  dimen¬ 
sion  limits  and  an  identifier  of  type 
ADDRESS,  as  shown  in  Table  2,  page 
117.  This  structure  allows  you  to  cre¬ 
ate  matrices  tailored  to  size,  although 
speed  is  on  the  slow  side. 

Other  popular  data  structures  such 
as  binary  and  B-trees  can  also  be  ex¬ 
ported  as  opaque  types.  Multiway 
trees  such  as  the  B-tree,  B+  Tree,  B* 
Tree,2  and  B+  +  Tree3  examples  of 
complex  data  structures.  Library  da¬ 
tabase  developers  may  start  by  ex¬ 
porting  a  B-tree  structure  as  an 
opaque  type.  Hiding  the  exact  struc¬ 
ture  gives  them  the  ability  to  select 
one  of  the  above  structures  or  imple¬ 
ment  their  own  refinements,  which 


may  involve  adding  more  pointers  or 
resizing  the  B-tree  page.  One  problem 
generally  encountered  with  such 
data  types  occurs  when  you  perform 
I/O  with  files.  As  the  data  structure 
changes,  the  new  library  version 
must  be  able  to  identify  and  read  pre¬ 
vious  structures  saved  in  files. 

The  simple  example  presented  in 
Listing  Four,  page  109,  deals  with  a 
module  exporting  procedures  to  sim¬ 
ulate  a  basic  RPN  calculator  with  four 
stack  registers  (X,  Y,  Z,  and  T)  and  a 
LASTX  register,  similar  to  a  Hewlett- 
Packard  calculator.  Parts  A,  B,  and  C 
of  the  listing  show  the  definition  mod¬ 
ule  and  the  two  implementation  mod¬ 
ules,  respectively.  In  part  B  the  stack  is 
formed  by  five  scalar  identifiers, 
whereas  part  C  shows  an  array  repre¬ 
sentation.  The  zeroth  member  corre¬ 
sponds  to  the  LASTX  register,  the  first 
to  the  X  register,  and  so  on.  It  is  inter¬ 
esting  to  note  that,  while  using  the  ar¬ 
ray  representation,  a  FOR  loop  can  be 
used  to  push  and  pop  the  stack.  The 
scalar  representation  is  more  read¬ 
able,  however.  The  HPStackMod 
module  exports  four  basic  opera¬ 
tions — number  entry,  stack  clearing, 
recalling  LASTX  into  the  X  register, 
and  a  function  to  return  the  X  regis¬ 
ter.  The  latter  function,  which  may 
seem  extremely  trivial,  is  neverthe¬ 
less  essential  because  of  the  use  of  an 
opaque  type  to  represent  the  stack. 

An  Invitation 

I  encourage  you  to  send  me  short  util¬ 
ity  routines  or  programs  that  per¬ 
form  useful  tasks — for  example,  tap¬ 
ping  into  hardware  and  operating 
systems.  I'm  also  looking  forward  to 
the  validation  of  the  IBM  PC/AT  Ada 
compiler  by  Alsys  Inc.  Obtaining  a 
copy  of  this  will  help  my  discussions 
about  the  language. 

\otes 

1.  G.  Ford  and  R.  Wiener,  Modula-2:  A 
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2.  M.  Loomis,  Data  Management  and 
File  Processing  (Englewood  Cliffs, 
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OF  INTEREST 


Corporations  today  face 
the  same  problems  that 
motivated  the  Department 
of  Defense  (DOD)  to  create  a 
standard  programming 
language  and  eliminate  the 
proliferation  of  languages 
and  dialects  that  contribute 
to  astronomical  software 
upkeep  costs,  estimated  at 
80  percent  of  total  systems 
maintenance.  Mandated 
for  all  DOD  mission-critical 
applications,  the  Ada  pro¬ 
gramming  language  is  ex¬ 
pected  to  have  increasing 
importance  for  all  com¬ 
mercial  applications.  His¬ 
torically,  the  lack  of  com¬ 
pilers  has  inhibited  the 
widespread  use  of  Ada. 

An  Ada  compiler  for  the 
IBM  PC/AT  from  Alsys  en¬ 
ables  full-scale  Ada  applica¬ 
tion  programs  to  be  written 
for  the  PC.  Through  the  use 
of  protected  (virtual)  mode, 
the  compiler  permits  an  ap¬ 
plication  program  to  over¬ 
come  the  G40K  limitation 
imposed  by  the  DOS  operat¬ 
ing  system  and  to  access  ex¬ 
tended  memory  (up  to  16 
megabytes  on  the  PC/AT). 
The  compiler  is  packaged 
with  a  4-megabyte  memory 
board.  It  also  features  8086 
or  80286  instruction,  an  on¬ 
line  help  facility,  and  error 
checking.  The  compiler  for 
the  IBM  PC/AT  is  priced  at 
$3,000. 

Tartan  Laboratories 

has  developed  a  C  pro¬ 
gramming  language  com¬ 
piler  for  the  IBM  PC/RT. 
Both  an  Ada  and  a  Modula- 
2  compiler  for  the  IBM  PC/ 
RT  are  currently  under 
development. 

An  Ada  compiler  system 


for  the  IBM  PC,  PC/XT,  PC/ 
AT,  and  compatibles  is 
available  for  $895  from  Ar- 
tek  Corp.  The  compiler 
system  meets  virtually  all 
the  latest  DOD  specifications 
except  "tasking”  and  runs 
under  the  MS-DOS  or  PC-DOS 
operating  system  on  PC- 
compatible  computers  hav¬ 
ing  at  least  384K  of  memo¬ 
ry.  Hard-disk  mass  storage 
is  recommended  for  the  de¬ 
velopment  of  large  applica¬ 
tions.  Demonstration  disks 
are  offered  for  $29.95.  The 
full  system  is  available  to 
buyers  of  the  demonstra¬ 
tion  disk  for  $29.95  less  than 
the  regular  price. 

Artificial 

Intelligence 

Microsoft's  LISP  5.1  offers 
more  primitives,  greater 
capacity,  expanded  arith¬ 
metic,  improved  debug¬ 
ging,  and  faster  list  sorting 
than  do  earlier  versions.  It 
also  features  common  LISP 
support  and  split-screen 
capabilities.  Minimum  sys¬ 
tem  requirements  for  Ver¬ 
sion  5.1  are  a  PC  running 
MS-DOS  or  PC-DOS  2.0  or  lat¬ 
er,  128K  of  memory  (al¬ 
though  Microsoft  recom¬ 
mends  at  least  256K),  and 
one  disk  drive  (two  are  rec¬ 
ommended).  It  has  a  sug¬ 
gested  retail  price  of  $250. 

OPS83,  the  high-perfor¬ 
mance  expert  systems  pro¬ 
gramming  language  from 
Production  Systems 
Technologies,  is  available 
for  use  on  the  IBM  PC  and 
compatibles.  This  version 
of  OPS83  is  identical  to  the 
original  version  intro¬ 
duced  in  1984  for  use  un¬ 
der  VMS  and  Unix  on  the 
VAX  series  machines  and 
Apollo  Domain.  Recently,  it 
has  been  made  available 
for  use  on  the  MicroVAX, 
Sun  Workstation,  and 
AT&T’s  3B  series.  It  retails 
for  $1,950. 


An  integrated  systems 
development  environment 
for  planning,  analyzing, 
designing,  and  construct¬ 
ing  computer-based  infor¬ 
mation  systems  is  available 
from  KnowledgeWare. 
Called  the  Information  En¬ 
gineering  Workbench,  this 
software  family  uses  ex¬ 
pert  system  and  computer- 
aided  design  and  program¬ 
ming  techniques  to 
automate  information  en¬ 
gineering.  The  new  family 
includes  an  integrated  set 
of  diagramming  tools  for 
several  common  diagram 
types,  including  entity,  de¬ 
composition,  data-flow, 
and  action  diagrams. 

C Language 

Raima  Corp.  has  an¬ 
nounced  Version  2.1  of 
db-Vista,  its  database  man¬ 
agement  system  for  soft¬ 
ware  development  in  the  C 
programming  language.  It 
is  designed  for  use  with  MS- 
DOS  or  Unix-like  operating 
systems.  The  new  version 
features  improved  B-tree 
key  field  handling;  a  key- 
file  rebuild  utililty;  a  data¬ 
base  consistency  check  util¬ 
ity;  a  data-field  alignment 
check  utililty;  and  file- 
transfer  utilities  for  dBASE, 
R:base,  and  ASCII  files.  The 
db-Vista  multiuser  version 
costs  $990  with  source  and 
$495  without  source.  The 
single-user  version  is  avail¬ 
able  for  $495  with  source 
and  $195  without. 

High  C,  a  C  cross  compil¬ 
er  implemented  for  VAX/ 
VMS  running  on  the  Intel 
8086/88/186/188/286  fam¬ 
ily  of  microprocessors,  is 
available  from  Microtec 
Research.  High  C  features 
support  for  ROMable  code 
for  embedded  applica¬ 
tions,  nested  functions 
complete  with  up-level  ref¬ 
erences,  nested  functions 
passable  as  parameters,  a 


full  set  of  memory  models, 
three  integer  ranges,  and 
three  IEEE  real  precisions. 
The  product  also  contains 
many  compiler  controls 
and  options,  including  one 
for  strict  ANSI  standard 
checking.  The  complete 
High  C  software  package 
costs  $7,000  and  operates 
on  DEC  VAX  under  VMS. 

Computer  Innovations 
has  released  a  free  booklet 
on  its  Optimizing  C86  C 
compiler.  The  features  of 
the  C86  discussed  include 
language  conformance, 
Unix  compatibility,  and 
source-level  debugging  sup¬ 
port.  The  booklet  also  fea¬ 
tures  a  complete  listing  of 
run-time  options  and  func¬ 
tions. 

Fast  Programming  from 
Subject,  Wills  &  Co.  is  a  C 
generator  tool  for  business- 
application  developers. 
The  product  includes  a  B  + 
tree  index  facility,  a  field- 
independent  record  man¬ 
agement  system,  a  com¬ 
plete  set  of  run-time 
utilities,  a  library  of  C  rou¬ 
tines,  and  several  C  pro¬ 
gram  generators.  Fast  Pro¬ 
gramming  sells  for  $995  for 
a  site  license.  It  is  available 
for  PC-DOS  and  Xenix  on  the 
IBM  PC/AT  and  Unix  V  on 
the  AT&T  3B2/3B5  comput¬ 
er  line. 

Version  2.0  of  Bastoc 
from  JMI  Software  Con¬ 
sultants  translates  BASIC 
programs  into  C.  Bastoc  an¬ 
alyzes  the  use  of  numeric 
variables  to  determine 
which  floating-point  vari¬ 
ables  can  be  replaced  by  in¬ 
teger  variables.  Additional 
optimizations  include 
eliminating  unreachable 
code;  converting  BASIC  as¬ 
signment  statements, 
where  possible,  into  sim¬ 
pler  increment  or  decre¬ 
ment  operations  available 
in  C;  and  evaluating  string 
expressions  at  compile 
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time.  The  product  includes 
a  BASIC  compiler  program. 
Binary  versions  are  avail¬ 
able  for  the  IBM  PC  and 
compatible  systems  using 
MS-DOS,  the  AT&T  3B2  (Unix 
V),  the  AT&T  Unix  PC/3B1 
(Unix  V),  the  Badio  Shack 
Model  16  (Xenix),  Sperry 
5000  (Unix  V),  and  several 
additional  Unix  and  Unix- 
like  systems.  The  price  for 
single-user  systems  is  $495. 

Application 

Development 

Version  6  of  Netron’s  com¬ 
puter-automated  program¬ 
ming  development  soft¬ 
ware  for  the  Wang  VS 
includes  a  feature  that  al¬ 
lows  automatic  control  of 
in-house  screen  design 
standards  for  file-mainte¬ 
nance  programs.  The  new 
version  also  adds  back¬ 
ground  processing  from 
user-defined  function  keys 


and  supports  use  of  quali¬ 
fied  data  names.  The  pro¬ 
gram  includes  a  built-in 
standard  ANSI  74  COBOL 
and  is  suitable  for  running 
production  systems  of  any 
size  and  complexity. 

The  Oasys  68020  Toolkit 
features  a  complete  line  of 
compilers  (C,  Pascal,  FOR¬ 
TRAN-77),  assemblers  (in¬ 
cluding  linker,  loader  and 
librarian),  debuggers,  sim¬ 
ulators,  profilers,  real-time 
OS,  and  down-line  load 
utilities.  Support  for  the 
68881  floating-point  pro¬ 
cessor  is  also  provided.  The 
Toolkit  is  available  for  DEC 
VAX  (VMS,  Ultrix,  Unix),  DEC 
MicroVAX  (VMS,  Ultrix), 
Sun,  Apollo,  Pyramid,  PCs, 
and  other  68000  and  32000 
systems  running  Unix.  A 
typical  configuration  of  a  C 
compiler,  assembler,  link¬ 
er,  and  librarian  starts  at 
$3,200  in  single  quantities. 


Release  5.0  of  STSC's 
APL’Plus  PC  System  adds 
speed  to  the  development 
process  with  its  APL  lan¬ 
guage  notation.  The  run¬ 
time  version  is  an  adapta¬ 
tion  of  the  APL*Plus  PC 
system  specially  modified 
to  run  a  single  application. 
This  modified  interpreter 
enables  developers  to  in¬ 
clude  enough  of  the  APL- 
*Plus  system  to  run  their  ap¬ 
plications  but  not  enough  to 
allow  end-users  to  write  or 
modify  their  own  APL  pro¬ 
grams.  The  run-time  sys¬ 
tem  is  licensed  on  a  royalty 
or  per-copy  basis. 

Release  One,  Version 
3.06,  of  Q’Nial  from  Nial 
Systems  is  a  high-level  in¬ 
teractive  interpreter  that 
handles  symbolic  and  nu¬ 
meric  computation  with 
equal  facility.  It  is  used  pri¬ 
marily  in  logic  program¬ 
ming  and  other  artificial 


intelligence  applications.  A 
Q’Nial  license  costs  $300  for 
PC/XT/ AT  versions.  The  en¬ 
tire  package,  including  me¬ 
dia  and  shipping,  costs 
$375.  Educational  licenses 
are  half-price.  A  site  li¬ 
cense  for  educational  insti¬ 
tutions  costs  $500. 

For  the  IBM  PC 

DSD86  from  Soft  Advances 
is  a  full-screen  symbolic  de¬ 
bugging  program  for  IBM 
PC-compatible  computers 
running  PC-DOS  or  MS-DOS. 
DSD86  offers  a  built-in  win¬ 
dowing  system  for  a  user- 
controlled  screen  layout 
with  six  different  display 
types,  including  instruc¬ 
tions,  registers,  stack,  mem¬ 
ory,  and  source.  The  key¬ 
board  interface  can  be 
customized,  permitting  ar¬ 
bitrary  command  lines  to 
be  bound  to  any  Ctrl,  Alt,  or 
function  key.  A  recursive 
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macro  facility  allows  con¬ 
sistent  extensions  to  the  set 
of  45  commands  provided 
by  DSD86.  The  list  price  is 
$69.95. 

Programmers  for  the 
IBM  System/38  computer 
can  write  and  edit  RPGIII 
source  code  on  an  IBM- 
compatible  personal  com¬ 
puter  using  the  Baby/38 
Source  Entry  Utility  (SEU),  a 
software  package  from 
California  Software 
Products.  Baby/38  SEU 
emulates  the  System/38 
source  entry  utility  to  pro¬ 
vide  full-screen  editing 
without  the  expense  of  Sys¬ 
tem/38  hardware.  Moving 
editing  functions  off-line  to 
a  PC  frees  the  System/38 
for  other  tasks  and  permits 
programming  to  continue 
even  if  the  system  is  down. 
Baby/38  SEU  requires  an 
IBM  or  fully  compatible  PC 
with  a  minimum  of  384K 
memory,  DOS  2.0  or  later, 
parallel  printer  port,  and 
dual-floppy  or  floppy-  and 
hard-disk  drives. 

Applied  Data  Research 
has  released  Version  2.0  of 
ADR/PC  Datacom,  a  PC- 
based  query  and  report 
writing  facility.  PC  Data¬ 
com  supports  the  ex¬ 
change  of  data  between  an 
IBM  PC  and  a  mainframe  as 
well  as  other  PC  functions. 
The  new  version  features 
PC-based  query  creation 
and  host  data  download 
and  upload,  a  full-function 
report  writer,  data  export 
and  import  for  the  ex¬ 
change  of  data  between  PC 
spreadsheets  and  other  ap¬ 
plication  software,  and  a 
procedure  facility  for  unat¬ 
tended  and  repetitive 
tasks.  The  product  oper¬ 
ates  on  any  standard  IBM 
PC,  PC/XT,  or  PC/AT  com¬ 
puter  using  PC-DOS  2.0  or 
later.  It  requires  a  mini¬ 
mum  of  512K  memory  and 
two  dual-sided,  floppy-disk 


drives  or  a  hard-disk  drive. 
The  IBM  3270  PC  is  also  sup¬ 
ported  and  requires  640K 
of  memory. 

Flagstaff  Engineering 

has  announced  three  prod¬ 
ucts — File  Connection, 
Word  Connection,  and 
Tape  Connection — for 
data/text  transfer  to  and 
from  the  IBM  PC  or  compa¬ 
tibles.  File  Connection  is  a 
3V2-,  5V4-,  and  8-inch  disk 
subsystem  that  interfaces 
to  a  PC  and  allows  users  to 
transfer  files  from  many 
different  systems.  Word 
Connection  allows  trans¬ 
fers  between  different 
word-processing  systems, 
such  as  Displaywriter,  La¬ 
nier,  OS/6,  NBI,  Wang,  Xe¬ 
rox  860,  CPT,  Microsoft 
Word,  Multimate,  and 
WordStar.  The  Tape  Con¬ 
nection  is  a  half-inch  mag¬ 
netic  tape  drive  interface 
that  allows  transfer  of  files 
from  a  PC  to  tape  and  back. 

Maxit,  a  memory  card 
with  software  that  expands 
available  memory  on  an 
IBM  PC,  PC/XT,  PC/AT,  or 
compatible  computer,  is 
available  from  McGraw- 
Hill  Software.  Maxit  re¬ 
quires  DOS  2.0  or  later  and 
can  fill  out  the  memory  of 
the  IBM  PC/AT,  taking  it 
from  512K  to  640K  and  be¬ 
yond.  Maxit  is  priced  at 
$195. 

Hallock  Systems  has  an¬ 
nounced  three  enhance¬ 
ments  to  its  Pro68  product 
line.  DOS68  is  a  PC-DOS-com- 
patible  operating  system 
designed  for  use  on  the 
Pro68  or  Pro68/10  co¬ 
processor  cards.  It  is  avail¬ 
able  for  use  with  C,  Pascal, 
Forth,  BASIC,  and  FORTRAN. 
The  system  sells  for  $150. 
Pro68/10  is  a  single  printed- 
circuit  card  that  can  be  in¬ 
stalled  in  any  full-size  PC, 
PC/XT,  or  PC/AT  bus  slot. 
The  card  includes  a  68010 
microprocessor  running  at 
12  MHz,  up  to  1,024K  of  on¬ 
board  16-bit  parity-checked 
memory,  provisions  for  a  6- 


MHz  math  processor,  two 
serial  I/O  channels,  a  16-bit 
680x0  expansion  bus,  and  a 
proprietary  dual-ported  PC 
bus  interface.  Pro68/10  is 
available  in  two  configura¬ 
tions,  costing  from  $1,995 
for  the  512K  version  and 
from  $2,195  for  the  1,024K 
version.  RTX68  is  a  time- 
sliced  multitasking  execu¬ 
tive  that  supports  up  to  256 
concurrent  tasks.  Each  task 
is  assigned  one  of  256  possi¬ 
ble  priority  levels  that  can 
be  changed  during  run 
time  on  a  dynamic  basis. 
RTX68  is  designed  to  run 
concurrently  with  the  host 
system  PC-DOS.  It  is  avail¬ 
able  for  $150. 

The  IBM  PC-compatible 
RS-232  5V4-inch  Floppy  Data 
Storage  and  Transfer  Sys¬ 
tem  is  available  from  Ana¬ 
log  &  Digital  Peripherals. 
It  features  host  and/or 
manual  controls,  ASCII  or 
full  binary  operation,  baud 
rates  switch  selectable 
from  110  baud  to  19. 2K 
baud,  and  automatic  data 
verification.  It  is  available 
in  110  VAC  stand-alone  or 
OEM  configurations.  The 
stand-alone  system  is 
priced  at  $1,095. 

Communications 

Quadram  has  launched  its 
MainLink  line  of  micro-to- 
mainframe  communica¬ 
tions  solutions  with  four 
3278/79  emulation  prod¬ 
ucts.  Two  of  the  products, 
the  MainLink  Standard  co¬ 
axial  connection  and  the 
MainLink  Plus  coaxial  con¬ 
nection,  link  directly  to  an 
IBM  3274  or  3276  cluster 
controller  for  local  or  re¬ 
mote  processing.  Both  are 
Irma  compatible.  They  are 
also  equipped  with  soft- 
loaded  microcode,  permit¬ 
ting  upgrades  to  be  made 
with  a  floppy  disk.  The 
MainLink  Standard  remote 
and  MainLink  Plus  remote 
attach  via  synchronous 
modem  to  an  IBM  3705, 
3725,  or  equivalent  com¬ 


munications  controller  in 
SNA/SDLC  mode.  Both  per¬ 
mit  emulation  of  an  IBM 
3274  cluster  controller  and 
3287  host-addressable 
printer.  The  four  products 
retail  as  follows:  MainLink 
Standard  coaxial,  $895; 
MainLink  Plus  coaxial, 
$1,145;  MainLink  Standard 
remote,  $545;  MainLink 
Plus  remote,  $985. 

SoftCraft  has  a  new  re¬ 
lease  of  its  Btrieve  file  man¬ 
agement  software  for  the 
IBM  PC/AT  and  compatibles. 
Btrieve  4.0  and  Btrieve/N 
4.0  (for  multiuser  and  LAN 
systems)  feature  variable- 
length  records,  data  en¬ 
cryption,  password  protec¬ 
tion,  and  a  file-level  verify 
option.  Both  are  for  soft¬ 
ware  development  in  BA¬ 
SIC,  Pascal,  COBOL,  C,  FOR¬ 
TRAN,  Modula-2,  and  APL. 
They  cost  $245  and  $595, 
respectively. 

Network-OS  6.0,  a  Net- 
bios-compatible,  network 
operating  system,  supports 
DOS  3.1,  all  major  network 
topologies,  and  Novell  file 
and  record  locking.  Avail¬ 
able  from  CBIS,  Network- 
OS  is  menu-driven,  and 
commands  are  presented 
on  hierarchical,  pull-down 
screens.  LAN  resources  are 
addressed  by  user-defined 
object  names  and  mapped 
by  mouse  or  keyboard.  The 
retail  list  price  of  Network- 
OS  is  $995.  Interface  boards 
cost  $295. 

Lamar  Micro  has  devel¬ 
oped  a  65C02  cross  assem¬ 
bler  program  for  the  Atari 
520  ST  on  Atari  format  disk. 
This  program,  called  C02 
Cross  Assembler,  allows 
the  Atari  to  act  as  a  soft¬ 
ware  development  system 
for  Apple,  Atari,  and  Com¬ 
modore  computers  that 
use  the  6502  or  65C02  mi¬ 
croprocessor.  The  price  of 
the  program  is  $89.95. 

TDI  Software  has  re¬ 
leased  a  Modula-2  for  the 
Commodore  Amiga.  The 
software  features  full  in- 
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terface  to  ROM  Kernal,  In¬ 
tuition  and  AmigaDOS,  32- 
bit  native  code 
implementation,  support 
for  transcendental  func¬ 
tions  and  real  numbers, 
separate  compilation  of 
modules  with  version  con¬ 
trol,  Code  statement  for  in¬ 
line  assembly  code,  and  the 
ability  to  locate  and  identi¬ 
fy  errors  in  source  code. 
The  Modula-2  comes  in 
regular  and  developer's 
versions.  The  developer's 
version  has  an  extra  disk 
containing  all  the  defini¬ 
tion  module  sources,  a 
symbol  file  decoder,  link 
and  load  file  disassemblers, 
a  source  file  cross-refer- 
encer,  the  kermit  file- 
transfer  utility,  and  the 
source  code  for  several  of 
the  Amiga  modules.  The 
retail  price  of  the  regular 
version  is  $89.95;  the  devel¬ 
oper’s  version  is  $149.95. 

Peachtree  Technology 
has  introduced  the  T-33e 
Back-Up  Subsystem.  The  T- 
33e  utilizes  the  existing  ex¬ 
ternal  floppy  port  on  any 
IBM  PC,  PC/XT,  PC/AT,  or 
compatible.  It  is  MS-DOS- 
compatible  and  can  back 
up  30  megabytes.  An  LED 
readout  provides  users 
with  tracking,  power,  and 
drive  information  and  of¬ 
fers  self-diagnostic  capabil¬ 
ities,  including  an  on-board 
error-detection  device.  The 
T-33e  retails  for  $795  and 
comes  with  two  10-mega- 
byte  reels.  It  also  comes  in 
an  internal  half-height 
configuration  that  retails 
for  $695. 

Mastercom-Telecommu- 
nications  Utility  is  a  smart- 
terminal  and  file-transfer 
utility  available  for  the  IBM 
PCjr  and  most  IBM  PC-DOS- 
and  CP/M-80-compatible 
computers.  Mastercom, 
available  from  The  Soft¬ 
ware  Store,  is  designed  to 
capture  data  onto  a  disk 
and/or  printer,  send  files, 
and  transfer  files  using  the 
Christensen  XMODEM  er¬ 


ror-correcting  protocol.  It 
includes  auto-dial,  auto-an- 
swer,  host-mode  unattend¬ 
ed  operation,  batch-file 
transfer,  directory  display, 
file  erase,  file  rename,  disk- 
drive  logging,  stored  re¬ 
sponses,  and  more. 

Samsung  Semiconduc¬ 
tor  has  introduced  two 
families  of  high-perfor¬ 
mance  CMOS  logic  prod¬ 
ucts:  the  54/74  Advanced 
High-Speed  CMOS  and  the 
54/74  High-Speed  CMOS. 
The  two  product  families 
contain  63  devices,  includ¬ 
ing  octal  buffers,  octal 
transceivers,  octal  latches, 
and  inverters.  They  also 
feature  low  power  dissipa¬ 
tion,  high  levels  of  noise 
immunity,  low  input  cur¬ 
rents,  wide  operating  volt¬ 
age  supply  and  tempera¬ 
ture  ranges,  4,000V  ESD 
protection,  and  the  ability 
to  handle  latchup  trigger 
currents  above  200  ma. 

The  Epsilon  Extension 
Language  from  Lugaru 
Software  is  an  interpret¬ 
ed,  dynamically  linked  ex¬ 
tension  language  that  re¬ 
sembles  C,  augmented 
with  functions  and  vari¬ 
ables  to  facilitate  writing 
editor  extensions.  It  fea¬ 
tures  source  code  for  all 
commands,  unlimited  file 
size,  an  on-line  tutorial,  an 
EMACS-style  command  set, 
language  support,  com¬ 
mand-name  and  file-name 
completion,  and  full  DOS 
path  support.  Epsilon's 
price  is  $195. 

Watcom  Products  has 
released  Maple,  an  interac¬ 
tive  system  for  algebraic 
computation.  Maple  pro¬ 
vides  diagnostic  and  de¬ 
bugging  facilities  and  sup¬ 
ports  two  output  formats: 
two-dimensional,  multi- 
line  format  and  one-di¬ 
mensional,  line-printing 
mode.  It  is  available  for  IBM 
VM/SP  CMS,  Digital  VAX/ 
VMS,  and  Unix  (4.2BSD)  for  a 
yearly  license  fee  of  $1,400 
for  commercial  users. 
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White  Sciences'  Icon 
Builder  software  allows  the 
generation  of  graphics  im¬ 
ages  that  can  be  printed, 
overlayed  on  a  digitizing 
tablet  surface,  and  used  to 
augment  the  limited  key¬ 
board  space  in  the  con¬ 
struction  of  icon-oriented 
user  interfaces  to  applica¬ 
tion  programs.  Icon  Builder 
is  composed  of  four  soft¬ 
ware  modules:  a  graphics 
program,  a  template  editor, 
a  template  install  program, 
and  an  overlay  print  pro¬ 
gram.  It  retails  for  $79.95. 

BMC  Software’s  Data 
Packer  II  is  a  second-gener¬ 
ation  IMS  utility  that  pro¬ 
vides  multiple  database 
compression  options.  Data 
Packer  II  reduces  DASD 
space  requirements,  often 
by  more  than  75  percent, 
thereby  reducing  the 
many  direct  costs  affected 
by  DASD  needs  and  high 
transaction  levels.  The 
product  is  available  at 
$25,000  for  a  perpetual 
lease  on  the  first  CPU. 

RM/COBOL  from  Ryan- 
McFarland  Corp.  is  a  GSA- 
certified  implementation  of 
the  ANSI  X3.23  74  COBOL 
standard.  It  is  available  un¬ 
der  an  OEM's  custom  oper¬ 
ating  system  or  under  stan¬ 
dard  systems.  RM/COBOL 
features  an  indexed  file-ac¬ 
cess  method,  record-  and 
file-level  locking,  full  arith¬ 
metic  capability,  and  inter¬ 
active  screen-handling 
capabilities. 

XTree,  Version  2.0,  from 
Executive  Systems  is  de¬ 
signed  to  simplify  file  and 
directory  handling  -by  pro¬ 
viding  single  keystroke 
commands  to  access,  de¬ 
lete,  rename,  view,  move, 
list,  or  show  files  within 
any  directory  on  a  floppy 
and  hard  disk.  Version  2.0 
requires  an  IBM  PC  or  PC/AT 
with  19K  of  memory  and 
MS-DOS  2.0  or  PC-DOS.  The 


program  retails  for  $49.95. 

The  Sibec-II,  a  single¬ 
board  microcontroller,  is 
available  from  Binary 
Technology.  Sibec-II  fea¬ 
tures  the  8052-AH  CPU  with 
full  floating-point  BASIC. 
The  auto  baud  rate  RS-232 
connector  allows  users  to 
connect  a  terminal  and  be¬ 
gin  programming.  The  unit 
is  available  for  $295. 
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Exactly  two  years  ago  vve  pub¬ 
lished  a  rev  iew  of  Borland's 
Turbo  Pascal;  within  the  next 
two  months  vve  expect  to  review 
Turbo  Prolog,  assuming  we  get  the 
product  in  time  (the  editor’s  perenni¬ 
al  lament).  When  I  finish  this  column 
1  intend  to  drive  to  Scotts  Valley  and 
request  a  copy  in  person.  That  some¬ 
times  works. 

Column?  you  ask,  flipping  through 
back  issues,  asking  your  fickle  memo¬ 
ry  what  was  on  this  page  before.  Cer¬ 
tainly  not  this  column  with  a  goofy 
photo  of  the  editor-in-chief  posed 
like  Peter  Norton.  What  are  they  do¬ 
ing  to  DDJ  now? 

Glad  you  asked.  This  is  indeed  a 
new  column,  written  by  me,  Mike 
Swaine,  editor-in-chief,  a  column 
born  of  the  need  to  have  new  editor 
Nick  Turner  and  me  flame  in  parallel 
(he  gets  the  editorial  page)  and  of  the 
desire  to  put  an  opinion  column  on 
the  last  page  like  many  other  maga¬ 
zines  do. 

Oh,  fine.  Now  Dili  will  start  sound¬ 
ing  like  Info  World.  Ersatz  Dvorak, 
right?  Well,  no;  I  hope  this  will  be  a 
\  DDJ- type  hack-page  column,  dealing 
with  DDJ- type  issues  from  a  DDJ-type 
i  perspective.  If  the  styles  of  other  col¬ 
umnists  influence  this  column,  they 
will  be  the  the  columnists  who  influ¬ 
enced  me  in  my  formative  years. 

1  read  and  enjoyed  John  Camp¬ 
bell's  convention-challenging  editori¬ 
als  in  Analog  Science  Fiction  maga¬ 
zine  oven  after  1  grew  up  and  learned 
that  they  were  sophomoric  and 
slightly  cracked.  I  was  permanently 
warped  by  Martin  Gardner’s  rich. 

|  witty,  and  diligently  researched 
Mathematical  Games  column  in  Sci¬ 
entific  American,  and  I  imitated  it  in  a 
puzzle  column  of  my  own  on  the 
hack  page  of  InfoWorld  for  a  year  or 
so.  More  recently,  I  liked  Hal  Harden- 
bergh's  quirky  column-that-ate-the- 
newsletter  in  DTAC.K  Grounded,  but  I 
don’t  have  room  here  to  imitate  Hal. 

What  will  this  column  cover?  The 
usual  stuff:  significant  new  software 


products,  books,  trends,  phenomena. 
I  admire  Jon  Bentley's  Programming 
Pearls  in  Communications  of  the  ACM, 
which  have  been  collected  into  a 
book  also  titled  Programming  Pearls 
(Reading,  Mass.:  Addison- Wesley, 
1986).  Bentley  has  staked  out  as  his 
domain  insight  and  creativity  in  pro¬ 
gramming.  Fertile  ground,  which  he 
tills  like  a  native.  1  think  his  is  the  best 
new  computer  book  of  1986. 

A  good  column  should  stimulate  its 
readers  to  think,  not  try  to  think  for 
them.  I  don’t,  for  example,  know  the 
significance  of  Microsoft’s  decision 
not  to  support  .COM  files  in  future 
versions  of  DOS  (beyond  the  fact  that 
it’s  a  repudiation  of  DOS’s  illegitimate 
descent  from  CP/M),  but  I  suspect 
there  may  he  ramifications  that  Mi¬ 
crosoft  hasn't  considered. 

A  good  column  asks  questions,  hut 
not  just  the  most  obvious  ones.  Will 
Borland  sell  hundreds  of  thousands 
of  copies  of  Turbo  Prolog?  Maybe,  but 
what  would  it  signify  if  it  did?  Oddly, 
despite  the  fact  that  Pascal  and  PRO¬ 
LOG  are  from  different  planets,  the 
experience  of  Turbo  Pascal  could 
provide  an  idea  of  how  Turbo  Prolog 
will  he  received  -  breathless  reviews 
in  the  computer  press,  reckless 
spending  by  under-informed  com¬ 
puter  owners,  confusion  over  the  sig¬ 
nificant*  of  the  PROLOG  language, 
mistaking  a  good  user  interface  for 
product  depth.  Turbo  Prolog  could 
he  absurdly  successful  for  reasons  no 
less  absurd.  And  yet,  the  effect  on 
professional  software  development 
could  turn  out  to  be  negligible. 

Finally,  I  hope  to  tell  about  the 


work  of  an  enterprising  software  de¬ 
veloper  with  a  genuinely  new  idea 
each  month.  Take  my  cousin  Corbett, 
who,  having  lost  his  shirt  in  the  soft¬ 
ware  look-alike  market  when  his  line 
of  software  (called  Look  and  Feel 
Ware  and  marketed  under  the  Kal- 
|  vin  Klone  label)  ran  up  against  some 
stiff  competition,  hit  upon  one  of 
those  ideas  that  leave  you  speechless 
with  awe. 

Corbett's  latest  line  of  products  is 
called  Tomorrow  s  Software.  Tomor¬ 
row's  Software  does  nothing  except 
I  display  so-far-unused  icons,  shapes, 
i  and  colors  on  the  screen.  Corbett  s  vi¬ 
sionary  idea  is  to  stake  out  new  visual 
metaphors  in  order  to  collect  royal¬ 
ties  from  people  who  will  later  learn 
what  to  do  with  them.  The  hall-closet 
metaphor.  The  hero-sandwich  meta¬ 
phor.  The  sheep-entrails  metaphor.  I 
think  he’s  onto  something.  Just  yes- 
|  terday  he  called  to  tell  me  that  he’d 
found  a  color  that  had  never  been 
put  to  functional  use  on  the  comput¬ 
er  screen,  and  he  was  applying  for  a 
patent  on  its  use.  The  big  question  is 
whether  he  can  sue  Steven  Spielberg 
I  over  his  use  of  the  color  purple. 

Yeah,  but  what’s  this  Borland  busi- 
j  ness?  you  ask,  ignoring  the  last  two 
paragraphs,  if  Turbo  Prolog  may 
j  have  only  negligible  significance  for 
software  developers,  why  review  it 
in  a  software  developer's  magazine? 
Well,  what  1  really  suspect  is  that  Bor¬ 
land  is  onto  something.  I  think  it  s  just 
possible  that  Turbo  Prolog  will  be  sig¬ 
nificant  in  the  history  of  software, 
hut  it  will  be  so  only  if  Borland  is  suc- 
j  cessful  in  getting  it  quickly  into  col¬ 
lege  classrooms  and  only  if  the  prod- 
j  uctisgood. 

So  if  you'll  excuse  me.  I'm  oft"  to 
Scotts  Valley. 

Late  news  dept.:  Dvorak  makes  bold 

move  to  PC  Magazine. 


Michael  Swaine 

editor-in-chief 


Dr.  Dobb  s  Journal,  June  1986 

446 


128 


#«7  JULY  1986 

2.95  (3,95  CANADA) 


Software  Tbols 

FOR  THE  PROFESSIONAL  PROGRAMMER 


■  Forth  Standards 
Proposal 


Forth  in  a  Bottle 


Forth  &  Extended 
Memory 


Forth  Structured 


IK® 


JULY  1986 


CONTENTS 


VOLUME  11  ISSUE  7 


Improving  Forth 
control 
structures 

Forth  gets  all  wet 


Traversing 

without 

recursing 

Gi  ving  Forth 
more  room 


What  are  Forth 
prog  ram  m  ers 
really  like? 


Dr.  Dobb's  Journal  of 

Software  Tools 


ARTICLES 


^  FORTH:  A  Forth  Standards  Proposal  30 

by  George  VV.  Shaw  II 

George  presents  a  comprehensive  approach  to  solving  the 
problems  of  control  structures  in  the  Forth  83  Standard. 

FORTH:  Forth  Goes  to  Sea  40 

^  by  Everett  Carter 

An  implementation  in  which  Forth  controls  a  self- 
contained  robot  probe  used  to  study  the  Gulf  Stream 

FORTH:  Forth  motions  for  the  IBM  PC  46 

by  Craig  A.  Lindley 

T  his  article  illustrates  the  use  of  windows  in  a  Forth 
environment  and  shows  how  to  integrate  an  application 
with  window  routines. 

TELECOMMUNICATIONS:  The  CompuServe  B  Protocol  .14 

by  Levi  Thomas  and  Nick  Turner 
T  he  rest  of  the  listings 


COLUMNS 


^  C  CHEST:  Binary  Trees,  Compilers  IS 

by  Allen  Holub 

Allen  explains  a  nonrecursive  tree-traversal  routine  and 
another  that  prints  trees.  Microsoft  responds  to  Allen's 
comments  about  its  C  compiler. 

^  16-BIT  SOFTWARE  TOOLBOX:  Forth  and  the  EM8  106 

by  Ray  Duncan 

A  PC/Forth  interface  to  expanded  memory  allows 
declaration  and  use  of  huge  arrays.  Readers  refine  the  TEE 
filter  and  take  issue  with  Ray’s  criticisms  of  Concurrent 
DOS 

►  STRUCTURED  PROGRAMMING:  Forth  113 

by  Michael  Ham 

Our  Forth  columnist  introduces  the  language  and  its 
programmers,  as  well  as  himself. 

FORUM 


6 

S 

s 

14 

IZS 


EDITORIAL 

by  Nick  Turner 
LETTERS 
by  you 
CARTOON 
by  Rand  Renfroe 
DO.I  ON  LINE: 

How  to  Get  On 
SWAINE’S  FLAMES: 
Independence 
by  Michael  Swaine 


PROGRAMMER'S 

SERVICES 

DR.  DOBB  S  CATALOG:  73 

i  DDJ  products — all  in  one 
|  place 

OF  INTEREST:  130 

|  Many  new  products  of 
j  interest  to  programmers 
ADVERTISER  INDEX:  I  36 
I  Where  to  find  those  ads 


About  the  (lover 

The  cover  was  designed  by  Jan- 
I  aia  Donaldson  and  created  by 
Dan  Silva  on  a  Commodore 
Amiga.  Dan  used  the  Deluxe 
Paint  program  he  designed  tor 
Electronic  Arts 


This  Issue 

Welcome  to  our  sixth  annual  spe¬ 
cial  issue  on  the  Forth  language. 
Our  feature  article  proposes  a 
comprehensive  set  of  standards 
for  extended  control  structures. 
Everett  Carter  puts  Forth  in  a  !x>t- 
tle,  and  Craig  A.  Lindley  opens  a 
window  on  easy-to-use  imple¬ 
mentations.  We’re  also  introduc¬ 
ing  a  new  columnist  whose  spe¬ 
cialty  is  you  guessed  it  Forth. 


Next  Issue 

In  the  hot  month  of  August  why 
not  dive  into  C?  Ixist  August,  we 
broke  ground  with  a  new  kind  of 
software  review  It  was  more 
technical  and  deeper  in  detail 
than  the  usual  fare  and  used 
carefully  designed  “. surgical  ' 
benchmarks.  This  year  we  re¬ 
prise  and  improve  the  process 
with  an  up-to-date  comparison 
of  17  C  compilers  for  MS-DOS. 
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Concern  has 
been  ex¬ 
pressed  that 
we  are  abandoning 
Forth.  We  re  not.  We 
have,  though,  devot¬ 
ed  less  attention  to 
the  language  in  the 
past  year  and  intend 
to  redress  this,  start¬ 
ing  with  this  Forth  is¬ 
sue.  Michael  Ham, 
our  new  columnist  sharing  the  Struc¬ 
tured  Languages  column,  is  an  ac¬ 
complished  Forth  programmer  and 
one  of  the  most  eloquent  voices  in  the 
Forth  community.  We’re  looking  for¬ 
ward  to  publishing  more  Forth  arti¬ 
cles  in  future  issues,  particularly 
those  that  demonstrate  the  unique 
advantages  of  Forth's  threaded,  ex¬ 
tensible,  reverse  Polish  nature. 

Michael  Odawa,  vice  president  of 
the  Software  Entrepreneur's  Forum 
and  director  of  the  Software  Services 
Association,  sent  us  a  letter  about  a 
new  set  of  tax  regulations  that  are  up 
for  consideration  here  in  California. 
The  new  legislation,  if  passed,  would 
be  grossly  unfair  to  independent  soft¬ 
ware  authors.  Briefly,  the  proposed 
revision  to  the  State  Board  of  Equal¬ 
ization's  Regulation  No.  1502  would 
apply  a  sales  tax  of  6-7  percent  (de¬ 
pending  on  the  county)  to  all  soft¬ 
ware  royalty  income,  as  well  as  some 
software-related  business  transac¬ 
tions  (such  as  installation  and  mainte¬ 
nance  of  software).  Neither  of  these 
forms  of  income  is  currently  subject 
to  sales  tax,  and  neither  should  be 
both  represent  charges  for  labor,  not 
sales  of  physical  assets.  This  ruling 
runs  completely  contrary  to  Sections 
6011  and  6012  of  the  Revenue  and 
Taxation  code,  in  which  labor 
charges  are  explicitly  excluded  from 
sales  taxation. 

One  key  issue  here  is  the  distinc¬ 
tion  between  services  and  manufac¬ 
tured  goods.  Under  the  tax  code,  ser¬ 
vices  are  not  subject  to  sales  tax.  The 
new  legislation  would  make  the  me¬ 


dium  used  to  deliver 
a  new  piece  of  soft¬ 
ware  determine  the 
taxability  of  the  sale. 

If  you're  a  soft¬ 
ware  author  in  Cali¬ 
fornia,  this  law 
would  directly  affect 
you.  If  you  live  else¬ 
where,  you  should 
be  aware  that  wide- 
ranging  legal  prece¬ 
dents  can  be  set  by  such  legislation. 
Mr.  Odawa  can  be  reached  through 
j  the  Software  Entrepreneur's  Forum 
at  (415)  854-7219.  We  urge  program- 
|  mers  to  educate  California  state  legis¬ 
lators  about  this  legislation. 

Authors  often  ask,  "How  do  1  write 
a  manuscript  that  you  will  want  to 
publish?"  Call  me  directly,  tell  me 
about  your  article,  and  make  sure  1 
send  you  copies  of  our  Writer's 
Guidelines  and  Style  Sheet.  But  that’s 
|  only  the  first  step.  There  are  so  many 
"good  things  to  know"  about  writing 
for  magazines  that  whole  books  have 
|  been  written  on  the  subject.  Starting 
this  month,  I’d  like  to  bring  you  some 
advice  of  my  own.  If  you're  working 
(or  thinking  of  working)  on  an  article, 
|  read  on. 

Keep  in  mind  that  space  is  often  at 
I  a  premium.  Explain  (briefly)  what 
the  problem  w'as  that  you  solved  and 
j  explain  the  solution.  Then  summa¬ 
rize  briefly  and  mention  where  your 
software  is  available. 

Now  is  the  time  to  get  to  work  on 
j  articles  for  the  next  68000  issue  (Janu- 
1  arv  1987).  The  deadline  for  that  issue 
is  September  15.  Remember,  if 
you  get  your  article  to  me  well  before 
that  date  there  will  be  time  for  re¬ 
writes — otherwise,  if  it's  not  perfect 
it  might  not  be  published.  If  you  have 
any  ideas  you'd  like  to  discuss,  give 
me  a  call  at  (415)  366-3600. 


Nick  Turner 
editor 
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Not  for  Profit? 

Dear  DDJ, 

Your  most  recent  name 
change  has  brought  into  fo¬ 
cus  a  matter  which  has 
been  irritating  me  for  some 
time:  The  copyright  decla¬ 
ration  stating  that  pub¬ 
lished  programs  are  for 
"personal  use  only,  not  for 
profit."  Your  "Software 
Tools”  are  now  said  to  be 
"for  the  professional  pro¬ 
grammer.”  Most  profes¬ 
sional  programmers,  in  my 
experience,  are  in  the  busi¬ 
ness  for  profit  (or  at  least  to 
keep  food  on  the  table).  Giv¬ 
en  the  confusing  (at  least  to 
me)  state  of  litigation  con¬ 
cerning  software  protec¬ 
tion,  even  to  the  extent  of 
reverse  engineering  now 
apparently  illegal,  I  find 
myself  wondering  if  I  dare 
read  any  magazines  for 
fear  that  I  might  uncon¬ 
sciously  use  a  line  of  some¬ 
one  else's  code  for  profit.  I 
am  particularly  irritated 
when  I  note  that  the  code  in 
question  has  been  copied 
largely  from  another 
source.  K  &  R  seems  to  be  a 
rich  source  of  freshly  copy¬ 
righted  material,  for 
example. 

A  specific  example 
which  I  found  recently:  An 
"author”  took  the  code  for 
GREP.C  distributed  by  DEC, 
added  * defines  so  that  it 
would  compile  under  an¬ 
other  compiler,  and  copy¬ 
righted  it  as  "not  for  profit,” 
"cannot  modify  or  distrib¬ 
ute,”  and  so  on.  Does  this 
mean  DEC  can’t  use  it 


anymore? 

I  would  like  to  see  fur¬ 
ther  discussion  of  program 
protection  and  publication 
matters  in  DDJ.  In  the 
meantime,  could  you  per¬ 
suade  some  of  your  au¬ 
thors  to  state  "portions 
may  be  used  in  applica¬ 
tions  providing  suitable 
credit  is  given”  or  some¬ 
thing  to  that  effect? 

Allen  R.  Balmer 

6845  West  Henrietta  Rd. 

Rush,  NY  14543 

DDJ  has  always  been  in  fa¬ 
vor  of  public-domain  soft¬ 
ware;  unfortunately,  the  line 
between  public-domain  and 
copyrighted  code  has  be¬ 
come  increasingly  blurred. 
Even  the  laws  seem  a  little 
confused  at  times.  When  a 
software  author  modifies  a 
public-domain  program 
and  releases  the  modified 
version,  is  he  or  she  entitled 
to  copyright  it ?  Does  it  de¬ 


pend  on  the  amount  and  na¬ 
ture  of  the  modifications 
made?  We  welcome  your 
point  of  view. — ed. 

Who  is  DDJ  For? 

Dear  DDJ, 

When  I  subscribed  to  DDJ 
three  years  ago,  the  maga¬ 
zine  was  described  as  "for 
users  of  small  computer 
systems.”  A  year  later 
(March  1984),  it  became  "for 
the  experienced  in  micro¬ 
computing.”  Two  months 
after  that  it  became  "...  for 
advanced  programmers.” 
Now  you  are  ", .  .for  the 
professional  programmer.” 
It  seems  that  you  are  be¬ 
coming  "for”  a  smaller  and 
smaller  readership. 

By  some  stretch  of  imagi¬ 
nation  I  might  still  be  con¬ 
sidered  eligible  to  be  a  sub¬ 
scriber,  but  your  next 
redefinition  will  surely  ex¬ 
clude  me.  But  it  probably 
won't  matter,  for  by  that 


time  DDJ  will  likely  be 
merely  an  index  of  what’s 
available  on  your  bulletin 
board. 

Why  not  just  publish  the 
magazine  and  let  the  indi¬ 
vidual  decide  if  the  maga¬ 
zine  is  for  him? 

Dave  Sullivan 

207  Maclane  St. 

Palo  Alto,  CA  94306 

As  the  market  for  computer 
magazines  grows  larger 
and  more  confusing,  it  be¬ 
comes  increasingly  impor¬ 
tant  for  each  magazine  to 
carefully  target  its  audi¬ 
ence.  DDJ’s  audience  has  al¬ 
ways  been  a  very  devoted 
and  well-defined  group  of 
people,  and  we  d  like  to  stay 
focused  on  that  group.  This 
means  that  people  who  are 
looking  for  introductory  ar¬ 
ticles  on  programming  in 
BASIC  or  who  need  to  learn 
how  to  use  their  new 
spreadsheet  will  have  to 
look  elsewhere.  But  it's  also 
important  not  to  get  too  car¬ 
ried  away.  We  think  Mr. 
Sullivan  has  a  point.  What 
do  you  think? — ed. 

Right  to  Assemble 

Dear  DDJ, 

Mr.  Campbell’s  The  Right 
to  Assemble  column 
(March  1986)  on  computing 
integer  square  roots  pre¬ 
sents  a  clever  modification 
of  Newton’s  Method  that  is 
considerably  more  effi¬ 
cient  than  previous  imple¬ 
mentations  that  have  ap¬ 
peared  in  the  pages  of  DDJ 
and  other  magazines. 

The  essence  of  Newton's 
Method  is  to  guess  the  val¬ 
ue  of  the  root  and  then  to 
compute  successively  bet¬ 
ter  guesses,  using  a  simple 
formula,  until  the  desired 
accuracy  has  been 
achieved.  Mr.  Campbell 
uses  an  ingenious  scheme 
to  arrive  at  a  good  initial 
guess.  As  a  result,  very  few 
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iterations  of  Newton's 
Method  are  required  and 
the  execution  time  is  dra¬ 
matically  reduced. 

I  would  like  to  present  a 
different  approach  to 
guessing  the  root  that  is  not 
as  elegant  as  that  used  by 
Mr.  Campbell  but  is  even 
faster.  I  empirically  deter¬ 
mined  several  formulas, 
each  of  which  provides  a 
good  guess  at  the  root  for 
some  range  of  argument 
values  (for  example,  one 
formula  for  arguments  in 
the  range  2—255,  another 
for  the  range  256—4095, 
and  so  on).  Each  formula  is 
something  like  (A  *  X)  +  B 
where  A  and  B  are  con¬ 
stants  and  X  is  either  the 
entire  argument  or  just  the 
high  byte  of  the  argument. 


The  guesses  are  good 
enough  so  that  a  single  iter¬ 
ation  of  Newton’s  Method 
either  gives  the  correct 
square  root  or  a  value  that  is 
high  by  one.  Then,  a  simple 
test  determines  whether  or 
not  to  decrement  the  value. 

The  CALC— ROOT  proce¬ 
dure  (Listing  One,  page  60) 
implements  this  idea  in 
8088/8086  assembly  lan¬ 
guage.  The  TIME  proce¬ 
dure  (also  Listing  One)  was 
used  to  benchmark  my 
routine  on  an  IBM  PC.  The 
full  benchmark  ( TIME- 
ROOT  routine)  ran  98  sec¬ 
onds.  Deducting  7  seconds 
for  looping  overhead,  add¬ 
ed  by  the  benchmark  ( TI¬ 
ME-OVER  routine),  it  took 
91  seconds  to  compute 
983,040  roots  or  about  92 
microseconds  per  root  as 
compared  to  183  microsec¬ 
onds  reported  by  Mr. 


Campbell  for  his  16032  rou¬ 
tine.  My  algorithm  works 
as  follows: 

1.  If  the  argument  equals 
zero  or  one  then  the  square 
root  equals  the  argument 
and  I  just  return  its  value. 

2.  If  the  argument  is  be¬ 
tween  2  and  255  inclusive, 
set  Guess  =  Argument/16 
+  3  and  go  to  Step  7.  The 
division  by  16  is  a  4-bit  shift 
to  the  right. 

3.  If  the  high  byte  of  the  ar¬ 
gument  is  between  1  and 
15  inclusive,  set  Guess  =  4  * 
(high  byte  of  the  argument) 
+  13  and  go  to  Step  7.  The 
multiplication  is  a  shift  left 
of  two  bits. 

4.  If  the  high  byte  of  the  ar¬ 
gument  is  between  16  and 
127  inclusive,  set  Guess  = 
(high  byte  of  the  argument) 
+  50  and  go  to  Step  7. 

5.  If  the  high  byte  of  the  ar¬ 


gument  is  between  128  and 
254  inclusive,  set  Guess  = 
(high  byte  of  the  argument) 
+  40.  If  this  guess  is  greater 
than  255,  set  Guess  =  Z55 
and  go  to  Step  7. 

6.  If  the  high  byte  of  the  ar¬ 
gument  equals  255  then  the 
root  is  255  and  I  return  that 
value. 

7.  Get  the  quotient  of  the 
argument  divided  by  the 
guess.  I  use  an  8-bit  DIV 
which  saves  70  clock  cycles 
compared  to  a  16-bit  DIV.  I 
can  do  this  because  I  have 
excluded  (in  Step  6  above) 
the  one  case  that  could  pro¬ 
duce  overflow. 

8.  Set  New  Guess  =  ( Guess 
+  Quotient )/2.  The  division 
by  2  is  a  1-bit  rotate. 

9.  New  Guess  is  either  the 
correct  square  root  or  is 
high  by  one.  To  see  which 
it  is,  I  square  New  Guess.  If 
New  Guess  ~2  is  less  than  or 
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equal  to  the  argument, 
then  the  square  root  equals 
New  Guess  or  else  it  equals 
New  Guess  —  1. 

This  method  is  an  exam¬ 
ple  of  perspirational  rather 
than  inspirational  pro¬ 
gramming.  I  wrote  a  small 
BASIC  program  (Listing 
Two,  page  62)  designed  to 
test  out  different  formulas. 
After  some  tedious  hours 
trying  various  possibilities  I 
found  a  set  of  ranges  and 
formulas  that  worked. 

My  BASIC  program  is 
quite  fast  because  it  only 
tests  argument  values  that 
are  one  less  than  a  perfect 
square  (for  example,  num¬ 
bers  of  the  form  N~2  —  1). 
These  tend  to  be  the  worst 
case  situations  because  the 
exact  root  of  such  numbers 
is  very  near  to  N  while  the 
integer  root  is  N  —  1. 

The  TEST  procedure 
(Listing  One)  was  used  to 
verify  the  accuracy  of  the 
root  for  all  65536  argument 
values.  In  this  test,  I 
checked  that  the  square  of 
the  root  is  less  than  or 
equal  to  the  argument  and 
that  (root  +  1)  “2  is  greater 
than  the  argument. 

Robert  Pirko 

211  West  56th  St. 

Apt.  36L 

New  York,  NY  10019 
Dear  DDJ, 

I  noticed  The  Right  to  As¬ 
semble  column  discussing 
integer  square  roots  as  im¬ 
plemented  on  the  68000 
and  the  32000  in  the  March 
1986  issue.  I  wish  to  further 
illustrate  the  advantage  of 
using  the  higher-level  in¬ 
structions  of  the  32000  with 
a  listing  of  my  routine  to 
perform  a  floating-point 
square  root  in  software.  It 
uses  a  format  similar  to 
IEEE  double  precision,  ex¬ 
cept  that  I  put  the  expo¬ 
nent  on  the  right  to  reduce 
the  number  of  opera¬ 


tions  required.  My  16032 
with  a  7.16-MHz  clock 
takes  190  microseconds  to 
do  the  double-precision 
square  root  (including  vari¬ 
able  passing  overhead). 
This  is  1,113  times  faster 
than  BASCOM  does  it  on  my 
Z80  system  (3.68  MHz,  1 
wait  state).  Because  I  don’t 
have  access  to  a  68000  com¬ 
puter,  I  don’t  know  how  it 
would  fare  in  this  task. 

In  Listing  Three,  page  62, 
you  will  notice  there  is  no 
looping  and  there  are  no 
calls  to  the  floating-point 
multiply  or  divide  rou¬ 
tines.  The  algorithm  used  is 
called  Newton’s  Method 
and  iteratively  executes 
the  following  equation: 

Y  =  Y/2  +  (X/2I/Y 

The  equation  is  based  upon 
the  use  of  a  derivative  to  ex¬ 
trapolate  and  calculate  a 
more  precise  guess.  The  bi¬ 
nary  exponent  is  a  great  aid 
in  choosing  the  first  guess. 
We  know  to  start  with  that 
the  mantissa  of  the  answer 
will  be  between  1  and  2; 
furthermore,  the  even-or- 
odd  condition  of  the  origi¬ 
nal  exponent  tells  us  if  the 
mantissa  of  the  answer  will 
be  above  or  below  the 
square  root  of  2.  With  this 
guidance,  we  make  the  first 
guess  either  1.189  or  1.68. 
This  is  enough  of  a  start  so 
that  four  iterations  is  al¬ 
ways  enough  to  obtain  the 
required  53  bits  of  preci¬ 
sion.  Only  in  rare  cases 
would  three  iterations  be 
enough,  so  we  always  do 
four  iterations  without  any 
testing.  Because  the  preci¬ 
sion  of  the  result  more  than 
doubles  with  each  itera¬ 
tion,  the  first  three  itera¬ 
tions  can  be  performed 
with  less  precision,  and  the 
compactness  of  the  32000 
instructions  makes  it  easy 
to  take  advantage  of  this 
fact.  Notice  in  the  listing, 
starting  at  label  SOfl2,  how 
easy  it  is  to  do  the  first  three 


iterations  with  32-bit  preci¬ 
sion  on  the  2000.  The  DE/D 
R3,R4  instruction  takes  a  64- 
bit  value  in  R4R5  and  di¬ 
vides  it  by  the  32-bit  value 
in  R3.  It  puts  the  quotient  in 
R5  and  the  remainder  in 
R4.  Four  machine-code  in¬ 
structions  to  evaluate  the 
whole  equation  is  what  I 
would  call  efficient. 

Neil  R.  Koozer 

Kellogg  Star  Rt. 

Box  125 

Oakland,  OR  97462 

Help 

Dear  DDJ, 

We  are  a  nonprofit  organi¬ 
zation  founded  to  help  the 
handicapped  and  disabled 
acquire  job  skills  and  jobs 
with  the  assistance  of  PCs. 
Our  staff  helps  coordinate 
the  efforts  of  rehabilitation 
agencies  and  educational 
institutions.  Whenever 
possible,  we  supply  the 
needed  PC  equipment  at 
no  cost  and  train  people  to 
use  it. 

To  disseminate  informa¬ 
tion  and  reach  and  encour¬ 
age  the  handicapped  and 
disabled,  we  publish  a  bi¬ 
monthly  newsletter  Per¬ 
sonal  Computer  Opportuni¬ 
ties  for  the  Handicapped.  If 
you  wish  to  subscribe, 
please  send  your  name  and 
address.  We  ask  that  you 
make  a  contribution  of  a 
minimum  of  $10.  This  con¬ 
tribution  is  fully  tax  deduct¬ 
ible.  If  you  are  handi¬ 
capped  or  prefer  not  to 
make  a  contribution,  drop 
us  a  note  and  we  will  give 
you  a  subscription  at  no 
charge. 

We  deeply  appreciate 
any  assistance  you  can  give 
us. 

James  R.  Nichols, 

Personal  Opportunities 
for  the  Handicapped 

P.O.  Box  374 

Spicer,  MN  56288 

Corrections 

Dear  DDJ, 

Thank  you  for  including 


our  software  in  the  March 
1986  issue  of  DDJ.  There  is  a 
slight  error  in  that  para¬ 
graph  which  depreciates 
the  value  of  our  hardware. 
It  should  read  ”...  LAB  40  is 
a  structured  parallel  port 
that  takes  16  memory  or 
I/O  locations ...” 

The  article  has  it  reading 
16K  (the  K  should  be 
omitted). 

Scott  Vanderlip 

75  Southgate  Ave. 

Suite  6 

Daly  City,  CA  94015 
Dear  DDJ, 

By  this  time  you  have  un¬ 
doubtedly  caught  the  er¬ 
rors  in  The  Right  to  Assem¬ 
ble  column  in  March  1986. 

The  worst  error  is  the 
definition  of  the  (integer) 
square  root  of  an  integer,  at 
the  top  of  column  2.  By 
your  definition,  the  square 
root  of  17  (or  of  any  prime 
number)  would  be  1. 

The  others,  at  the  top  of 
column  3,  lead  you  to  say  in 
one  sentence  that  "4  is  not 
the  correct  root”  and  in  the 
next  that  "the  integer 
square  root  of  24  is  4.”  In 
the  same  sentence,  you 
have  "24  divided  by  4 
equals  5.” 

Dorothy  Wolfe 

245  Hathaway  Ln. 

Synnewood,  PA  19096 

Dear  DDJ, 

Thank  you  for  your  ex¬ 
cerpt  on  our  company  in 
your  January  (1986)  Of  In¬ 
terest  column. 

We  would  like  to  point 
out  that  you  mentioned 
our  company  name  as  ATC 
International  in  your  col¬ 
umn  when  actually  it 
should  have  been  ACS 
International. 

Janet  M.  Heidenreich 

Advanced  Computer 

Solutions  International 

2105  Luna  Rd. 

Suite  330 

Carrollton,  TX  75006 

DDJ 

(Listings  begin  on  page  60.) 
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For  those  of  you  who 
missed  it  the  first  time,  here 
is  how  to  log  on  to  the  DDJ 
Forum. 

1.  Get  yourself  a  Compu¬ 
Serve  account.  (Call  Compu¬ 
Serve  at  (800)  848-8199  for 
information. ) 

2.  Log  on  to  CompuServe 
and  type  go  ddj  at  the 
prompt.  This  will  bring  you 
into  the  Display  Area,  the 
Read  Only  (noninteractive) 
module  of  the  SIG.  Here 
you'll  find  information 
about  the  DDJ  Forum. 

3.  Select  the  last  menu 
choice  from  the  Display 
Area  Menu.  This  will  bring 
you  into  the  Forum  where 
the  message  boards,  Data 
Libraries,  and  real-time 
conferencing  features  are. 
That’s  also  where  you'll 
find  me  and  columnists 
such  as  Mike  Ham,  Namir 
Shammas,  Ray  Duncan,  and 
Allen  Holub. 

4.  Type  I  at  the  Top  Menu. 
This  will  give  you  a  list  of 
commands  and  a  thumbnail 
sketch  of  the  Forum 's  struc¬ 
ture  and  features.  You 
should  capture  this  list  and 
print  it  out.  It  s  handy  to  use 
as  a  map  until  you  acquaint 
yourself  with  the  territory. 

5.  Read  the  bulletins  and  help 
files.  Type  B  at  the  Top 
Menu  to  read  the  bulletins. 
These  provide  more  infor¬ 
mation  about  various  as¬ 
pects  of  the  Forum.  I  also 
recommend  that  you  go  to 
DLO  (type  DLO  at  the  Top 
Menu)  and  browse  the  help 
files  there.  To  do  this,  type 
BRO  at  the  DL  menu.  When  it 
asks  you  for  KEYWORDS, 
type  HELP.  The  best  help  file 
for  a  quick  start  is  EZSIG 
HELP. 

That  should  get  you  start¬ 
ed  folks.  Of  course  the  only 
real  way  to  learn  how  the 
system  works  is  to  work  on 
the  system  <grin>.  Try 


things  out,  make  a  few  mis¬ 
takes,  get  the  feel  of  it.  And  if 
all  else  fails,  ask  that  *  SYSOP 
person — she'll  be  glad  to 
help. 

— Levi  Thomas  (*SYSOP) 

The  following  is  an  on-line 
exchange  that  took  place  in 
the  Forum's  House  of  AL¬ 
GOL  (the  on-line  version  of 
Namir  Shammas'  Struc¬ 
tured  Programming  col¬ 
umns). 

Modula-2 

11- Mar-86 

Sb:  Modula-2  Tools 
Fm:  Bill  73047,2624 
To:  All 

I  am  just  getting  started  in 
Modula-2  although  I  have 
programmed  in  just  about 
everything  else.  I  am  writ¬ 
ing  a  simple  multitasking 
dispatcher  for  a  fun  project 
I'm  developing.  When  I  get 
it  to  where  I  like  it,  I'll  let 
you  know  if  you’re  inter¬ 
ested.  I  suspect  that  I'm  re¬ 
inventing  the  wheel,  but  I 
haven't  been  able  to  find 
anything  like  it  in  the  pub¬ 
lic  arena. 

12- Mar-86 

Sb:  Modula-2  Tools 
Fm:  Bob  76703,532 
To:  Bill 

I  assume  you  are  aware  of 
MODUS,  the  Modula-2  User 
Group?  If  not,  I'll  gladly 
provide  you  with  an  ad¬ 
dress.  Check  out  recent  is¬ 
sues  of  ACM  SIGPlan  No¬ 
tices.  (It  should  be  available 
at  most  libraries.) 

The  June  1985  issue  con¬ 
tains  two  Modula-2  articles. 
One  of  them,  entitled  "Two 
Approaches  to  Implement¬ 
ing  Generic  Data  Structures 
in  Modula-2,"  is  by  Weiner 
and  Sincovec,  the  gentle¬ 
men  with  a  reasonable  Mo¬ 
dula-2  book  to  their  credit. 

The  December  1985  issue 
contains  three  articles  re¬ 
lating  to  Modula-2,  includ¬ 


ing  one  from  a  user  of  both 
Modula-2  and  Ada. 

The  articles  you  will  be 
most  interested  in  are  enti¬ 
tled  "Modula-2  Process  Fa¬ 
cilities”  and  "Modula-2  and 
the  Monitor  Concept.” 
These  are  by  D.  A.  Swery 
and  are  in  the  November 
1984  issue.  Both  articles  are 
reasonably  well  written 
and  both  contain  source 
code.  The  first  article  ex- 
tend's  Dr.  Wirth's  binary 
semaphores  to  counting 
semaphores,  and  the  sec¬ 
ond  is  a  Modula-2  imple¬ 
mentation  of  Hoare’s  moni¬ 
tor  concept.  That  both 
semaphores  and  monitors 
can  easily  be  implemented 
in  Modula-2  (without  re¬ 
sorting  to  assembly)  is  an 
excellent  example  of  the 
power  of  Modula-2’s  co¬ 
routines. 

The  October  1984  issue 
has  an  article  about  imple¬ 
menting  semaphores  un¬ 
der  Unix  without  kernel 
changes.  Some  code  (in  C)  is 
included  as  examples.  This 
article  is  of  interest  because 
it  makes  minimal  assump¬ 
tions  about  the  underlying 
OS. 

The  January  1986  issue 
contains  an  article  entitled 
"Detection  of  Deadlocks  in 
Multiprocess  Systems,” 
which  should  be  of  interest 
to  people  designing  tasking 
systems. 

13-Mar-86 
Sb:  Modula-2  Tools 
Fm:  Bill 
To:  Bob 

Thanks  much  for  the  info. 
I’ll  check  in  the  company 
library  for  the  SIGPlan  No¬ 
tices.  Could  you  please  give 
me  the  address  for  MODUS? 
I’m  afraid  I'm  a  Pascal  bigot 
and  ignorant  of  the  Mo¬ 
dula-2  user  community. 
I'm  rapidly  converting! 
Would  there  be  a  more  def¬ 
inite  way  of  asking  for  the 


SIGPlan  info?  Sometimes 
the  library  isn't  too  sure  of 
the  really  technical  stuff. 
Thanks  again! 

14-Mar-86 
Sb:  Modula-2  Tools 
Fm:  Bob 
To:  Bill 

The  address  of  MODUS  is 
MODUS 

c/o  George  Symons 
P.O.  Box  51778 
Palo  Alto,  CA  94303 
(415)  322-0547 

Dues  are  $20/academic 
year.  The  basic  benefit  is 
four  newsletters/year.  The 
membership  form  asks  for 
name,  company  (if  appro¬ 
priate),  address,  phone, 
electronic  address,  and 
which  implementations  of 
Modula-2  you  use.  In  addi¬ 
tion  there  are  three  options: 

1.  Don't  print  my  phone 
number  on  MODUS  rosters. 

2.  Print  only  my  name  and 
country  in  any  rosters. 

3.  Don’t  release  my  name 
on  any  mailing  lists. 

When  you  join,  you’ll  be 
sent  all  back  issues  for  the 
current  year. 

Your  librarian  should  be 
able  to  look  up  the  SIGPlan 
Notices  issues  using  the 
dates  given.  SIGPlan  No¬ 
tices  is  the  actual  name  of 
the  magazine.  It  is  a  month¬ 
ly  publication  of  ACM’s  (As¬ 
sociation  for  Computing 
Machinery)  Special  Inter¬ 
est  Group  for  Program¬ 
ming  Languages. 

If  your  company  library 
doesn't  have  SIGPlan  No¬ 
tices,  many  public  libraries 
have  it.  It  really  is  quite 
common. 

20-Mar-86 

Sb:  Logitech's  Modula-2 
Fm:  Bill 
To:  Bob 

I've  just  acquired  Logitech's 
Modula-2. 1  had  the  ITC  (still 
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have  it,  actually)  and  found 
it  much  too  buggy.  So  far 
the  only  problem  I've 
found  with  Logitech  is  that 
I  didn’t  go  for  the  "sources” 
right  off.  But .  .  .  that's  for 
when  the  checkbook  gets 
back  to  a  plus  balance  I 
guess.  On  a  similar  subject, 
what  are  all  the  Modula-2 
folks  reading  out  there?  I 
just  ordered  the  Wirth  third 
edition  from  the  publisher, 
but  I  suspect  that  other 
good  Modula-2  books  are 
available.  I  have  the  "Ship¬ 
builder's”  book  but  found  it 
to  be  much  too  low  a  level. 
As  a  lifetime  systems  pro¬ 
grammer,  I  need  meat  to 
keep  me  happy — none  of 
this  "cute”  stuff.  (Do  "real 
systems  programmers” 
read  "cute”?)  I  noticed  that 


McGraw-Hill  (in  the  CServe 
electronic  mail)  had  Olgl- 
vie(sp?)’s  book  for  sale.  Is  it 
any  good?  Any  other  sug¬ 
gestions? 

19-Mar-86 

Sb:  Turbo  Multitasking 
Fm:  Jean  76606,671 
To:  Sysop — All 
Hi!  I  bought  my  first  DDJ 
last  week  (never  too 
late.  .  .  ).  I  found  the  paper 
about  multitasking  with 
Turbo-Pascal  very  interest¬ 
ing.  I  looked  for  an  IBM  XT 
version  in  your  DLs.  Can  I 
expect  to  see  it  one  of  these 
days?  I’m  a  new  IBM  user 
(I'm  more  used  to  Apple- 
Pascal)  and  I  didn't  find  all 
addresses  to  drive  the  mo¬ 
dem.  Also,  does  someone 
here  know  if  Logitech's 
Modula-2/86  Version  2.0 
compiler  (the  one  an¬ 
nounced  for  $89)  supports 


all  Modula-2  features  (espe¬ 
cially  coprocessing)? 

19- Mar-86 

Sb:  Logitech's  Modula-2 
Fm:  Steve  70003,1326 
To:  Jean 

Yes,  it  is  all  there.  I  have 
been  working  with  Logi¬ 
tech’s  Modula-2  for  about  a 
month  now.  It  is  for  real,  a 
production  compiler.  I 
have  it  running  on  my  DEC 
Rainbow  (the  editor  is  only 
for  the  IBM  PC).  I  have  al¬ 
ready  written  a  simple  ter¬ 
minal  program  in  Modula- 
2.  I  have  no  problem 
getting  to  INTs  and  inter¬ 
rupt  vectors. 

20- Mar-86 

Sb:  Logitech’s  Modula-2 
Fm:  Bob 
To:  Jean 

Yes!  Logitech's  Modula-2/86 
does  support  the  entire  lan¬ 
guage,  including  corou¬ 
tines,  TRANSFER,  and  lO- 
TRANSFER.  UOTRANSFER 
implies  being  able  to  write 
interrupt  handlers  in  Mo¬ 
dula-2,  which  can  in  fact  be 
done  using  Logitech’s  com¬ 
piler.) 

Logitech’s  Modula-2/86  is 
probably  the  best  Modula-2 
for  the  IBM  PC,  clones,  and 
the  8086  in  general. 

21- Mar-86 

Sb:  Logitech's  Modula-2 
Fm:  Bill 
To:  Jean 

I  have  the  debuggers — Post 
and  Runtime.  Both  are  un¬ 
real  and  well  worth  every 
cent.  I,  too,  forewent  the 
"sources”  and  will  order 
them  as  soon  as  the  check¬ 
book  recovers  from  all  the 
other  things  I  have  gotten 
in  the  last  few  weeks.  Al¬ 
though  you  don’t  "need” 
them  to  run  the  compiler, 
they  would  be  nice  as  it  is 
through  the  sources  that 
you  can  customize  the  com¬ 
piler/editor/linker  options. 
It  would  also  be  nice  to  see 
the  internals  of  some  of  the 
library  modules.  (I  am,  alas, 


a  "real”  systems  program¬ 
mer  and  not  seeing  the  real 
code  deprives  me  of  my  sat¬ 
isfaction.)  I  hope  that  this  fo¬ 
rum  on  Modula-2  gets  going 
as  I  am  just  learning  this 
language  (it’s  probably 
number  20  or  so)  and  it’s  the 
best  so  far.  Now,  if  some¬ 
body  will  just  point  me  to 
an  Ada  compiler  environ¬ 
ment  for  the  PC,  I'll  move 
on  (hee,  hee).  ...  You  must 
understand,  I  dearly  love 
my  "toys”  (got  it  from  my 
father)  and  technical  stuff 
gets  me  high. 

20-Mar-86 

Sb:  Logitech's  Modula-2 
Fm:  Jean 
To:  Steve 

Thanks  to  Steve,  Bob,  and 
Bill  for  your  answers! 
Great  feedback  in  this  SIG! 
So,  think  I’m  gonna  order 
that  Modula-2.  An  IBM  SW 
user  suggested  I  buy  the 
Utility  package  (for  Post¬ 
mortem  debugger)  and 
Sources  features.  Sources 
are  expensive  ...  I  don’t 
know.  . .  so  I'm  happy  to 
find  help.  I’ll  make  my  first 
steps  in  that  great  lan¬ 
guage,  the  normal  step  af¬ 
ter  Pascal.  So,  thanks  again! 
Jean  (ps:  Are  you  all  "real 
system  programmers”? — I 
am  an  amateur  program¬ 
mer!) 

DDJ 
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Trees  and  More  on  Microsoft  and  Lattice  Compilers 


My  main  topics  this  month  are  bi¬ 
nary  trees  and  C  compilers.  I'll 
look  at  a  couple  of  fancy  tree-printing 
routines  and  at  a  nonrecursive  tree- 
traversal  routine.  Before  leaping  into 
trees,  though: 

A  IV e  h  Version  of  the  Shell 

DDJ  is  now  shipping  a  new  version  of 
the  shell  that  originally  appeared  in 
this  column.  In  addition  to  fixing  all 
the  bugs  I  know  about,  I've  included 
several  significant  enhancements  in 
the  new  version.  Pipes  are  now  sup¬ 
ported  (you  can  even  put  the  pipe  tem¬ 
porary  files  on  a  RAM  disk  if  you  want). 
The  alias  and  history  expansion  rou¬ 
tines  have  also  been  improved  consid¬ 
erably.  You  can  now  say: 

a  foo  echo  foo 
a  bar  echo  bar 
a  foobar  'foo;bar' 

as  well  as: 

!!  >bar;  !pat 

DOS-compatible  prompt  support  has 
been  added  ( $t ,  $d,  $e,  and  so  on).  You 
can  change  the  escape  character 
from  backslash  to  another  character 
so  you  can  use  backslash  as  a  path 
separator.  Ey.it  takes  a  value  so  that  a 
batch  file  that  was  called  as  a  subrou¬ 
tine  from  another  batch  file  can  re¬ 
turn  a  value  to  the  calling  process. 
Sstatus  is  supported  (it  works  a  bit  like 
errorlevel  does). 


by  Allen  Holub 


Most  important,  all  the  C  shell  con¬ 
trol  flow  commands  (except  goto )  are 
now  supported.  In  particular,  there  is 
an  IF  .  .  .  THEN  .  .  .  ELSE  mechanism, 
WHILE  and  FOREACH  loops,  and  a  C- 
like  SWITCH  statement.  Complicated 
expression  analysis  is  supported  in 
these  statements,  using  several  opera¬ 
tors  (f  ),  +,  — ,  *,  /,  %,  <=,  >=,  <,  >, 


!=,  =  =, !,  &&,  and  /  / ).  You  can  cre¬ 
ate  and  modify  variables  (with  an  @ 
command).  In  short,  you  can  now  ac¬ 
tually  write  real  shell  scripts. 

Upgrades  from  Version  1  are  avail¬ 
able  from  DDJ  for  $6. 

Printing  a  Tree 

Ever  since  I  was  an  undergraduate, 
I've  wanted  to  write  a  routine  that 
printed  binary  trees  graphically — 
that  drew  a  picture  of  the  tree,  show¬ 
ing  with  dashes  and  arrows  where 
all  the  pointers  went  and  which 
nodes  were  where.  So  this  month,  I 
finally  sat  down  and  did  it.  In  fact  I 
did  it  twice — once  for  an  in-order  tra¬ 
versal  and  once  for  a  preorder  tra¬ 
versal.  Output  from  the  tree-printing 
routines  is  shown  in  Figures  1  and  2, 
page  19. 

The  tree-printing  routines  are  in 
Listing  One,  page  68.  The  sinorderf  ) 
function  (lines  70—94)  is  included  to 
show  how  the  basic  algorithm 
works.  The  static  variable  depth 
keeps  track  of  the  depth  of  the  cur¬ 
rent  node  in  the  tree.  The  root  is  at 
depth  0,  its  children  are  at  depth  1, 
and  so  on.  The  subroutine  does  an  in- 
order  traversal  in  the  normal  way. 
Instead  of  just  printing  each  node, 
however,  it  prints  depth  tabs  and 
then  prints  the  node.  This  way,  the 
farther  down  a  node  is  in  the  tree,  the 
farther  to  the  right  it  will  appear  on 
the  page. 

A  sample  output  is  shown  in  Figure 
3,  page  19.  There  are  two  problems 
here.  First,  because  there  are  no  con¬ 
necting  lines,  it's  a  little  hard  to  see 
the  internal  connections  in  the  tree. 
Second,  a  mirror  image  of  the  tree 


has  been  printed.  Because  a  normal 
in-order  traversal  looks  like: 

traverse!  root ) 

{ 

traverse  (left) 
print  the  root 
traverse  (right) 

} 

the  leftmost  node  of  the  left  subtree 
will  be  printed  first.  A  glance  at  Table 
3  shows  that  the  output  is  back¬ 
ward — the  leftmost  node  ends  up  on 
the  far  right. 

Both  these  problems  are  corrected 
in  the  subroutine  inorder  (lines 
120—156).  Fixing  the  mirror-image 
problem  is  easy.  You  just  change  the 
traversal  algorithm  to: 

traverse)  root ) 

{ 

traverse  (right) 
print  the  root 
traverse  (left) 


Getting  the  lines  is  a  little  more  diffi¬ 
cult.  The  problem  is  the  vertical  lines 
(printed  with  /  characters).  A  bit  map 
is  kept  in  which  each  bit  corresponds 
to  a  particular  depth  in  the  tree.  If  a 
bit  is  set,  then  a  /  is  printed  when  you 
arrive  at  the  equivalent  depth  in  the 
output.  So,  all  you  need  to  do  is  set 
and  clear  these  bits  at  the  appropri¬ 
ate  time.  The  relationships  between 
the  bit  map  and  the  final  picture  are 
illustrated  in  Figure  4,  page  19. 

If  you  set  and  clear  the  bits  in  the 
simplest  possible  way  (that  is,  set  the 
bit  on  line  131  of  Listing  One  and 
clear  it  on  line  153),  a  picture  such  as: 

!  +-g 

+  — f-  + 

!  +  — e 

d— + 

!  +  — c 

+— b— + 

!  + — a 
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is  created.  You  can  avoid  the  topmost 
line  by  adding  horizontal  lines  as  you 
ascend  rather  than  descend  the  tree. 
That  is,  the  horizontal  line  for  node/ 
won’t  be  added  until  after  you've 
processed  node  g.  This  is  done  in  the 
code  on  line  147  by  setting  the  bit  for 
the  current  level  after  a  node  has 
been  printed.  Setting  the  next  level  if 
there  is  no  right  child  (line  135)  avoids 
problems  such  as: 

+-g-+ 

:  +— f 

!  +  — e — + 

d— + 

and 

f~  + 

+— e 

+— d— + 

where  a  line  is  omitted. 

There  are  two  situations  in  which  a 
bottom  extraneous  line  is  created: 

+  — i 

+— h - h 

g--+ 

!  !  !  +~f 

!  +— e— + 

+ — d — + 

!  +— b 

To  get  rid  of  the  extraneous  line  to 
the  left  of  the  b,  you  need  to  know 
whether  the  current  node  is  a  left  or 
right  child.  You  can  then  clear  the  ap¬ 
propriate  bit  when  you  process  a  left 
child.  In  the  above  example,  if  node  d 
knows  that  it's  a  left  child,  it  can  clear 
the  bit  at  its  own  depth  before  de¬ 
scending.  This  way  the  extra  line 
isn't  printed  to  the  left  of  the  b.  The 
variable  amleft  indicates  whether  the 
current  node  is  a  left  or  right  descen¬ 
dant.  It  should  be  set  to  0  the  first  time 
inorder(  )  is  called. 

The  second  extra  line  (to  the  left  of 
the  /)  is  actually  left  over  from  pro¬ 
cessing  node  i.  Because  there  was  no 
left  child,  the  test  I  just  described 
wasn't  performed.  This  situation  is 
addressed  by  the  code  on  lines 
149—152.  If  there's  no  left  descen¬ 
dant  for  the  current  node,  you'll  al¬ 
ways  clear  the  bit  at  depth  +1.  In  the 
above  example,  because  node  h  has 
no  left  descendant,  it  will  clear  the 
extra  bit  before  ascending.  The  prob¬ 
lem  of  no  right  child  is  addressed  on 


lines  132-135. 

The  preorderf  )  routine  (lines 
172—203)  uses  more  or  less  the  same 
process.  A  new  problem  pops  up 
here.  You  need  to  print  an  occasional 
blank  line  so  that  the  output  doesn’t 


Figure  1:  Printing  a  balanced  tree 


Figure  2:  Printing  an  unbalanced 
tree 


look  like  the  following  example: 
d 

+ - b 

I  + - a 

I  + - c 

+ - f 

+ - e 

+ - g 

(there  should  be  a  blank  line  above 
the/ node).  The  code  to  do  this  is  on 
lines  195  —  199.  A  blank  line  is  printed 
if  the  current  node  is  a  right  descen¬ 
dant  and  has  no  children.  In  the 
above  example,  this  will  happen  at 
nodes  c  and  g.  The  mirror-image  is¬ 
sue  is  not  a  problem  in  a  preorder  tra¬ 
versal  because  you  usually  want  to 
read  down  the  columns  (as  in  the 
above  example).  If  you  applied  the 
same  mirror-image  reversal  to  the 
preorder  traversal  that  you  used  in 
the  in-order  traversal,  nodes  a  and  c 
(and  nodes  e  and  g)  would  be  trans¬ 
posed  incorrectly. 

The  bit-map  routines  ( setbitf ),  test- 
bit(  ),  and  makebitmapf ) )  originally 
appeared  in  this  column  more  than  a 


Figure  3:  Output  from  sinorderj  ) 


Figure  4:  Relationships  between  bits 
and  lines 
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year  ago.  They're  reproduced  in  List¬ 
ing  Two,  page  71. 

IVonrecursive  Tree  Traversal 

One  of  the  problems  with  most  tra¬ 
versal  algorithms  is  that  they’re  re¬ 
cursive.  If  a  tree  degrades  to  a  linked 
list,  you'll  need  as  many  recursion 
levels  as  there  are  nodes  in  the  tree. 
Each  recursion  level  requires  its  own 
stack  frame,  so  assuming  a  10-byte 
stack  frame,  you'll  need  1,000  bytes 
of  stack  to  traverse  a  degraded,  100- 
node  tree.  This  can  cause  problems  if 
huge  amounts  of  stack  aren’t  avail¬ 
able,  so  occasionally  it’s  useful  to  give 
up  the  simplicity  of  a  recursive  algo¬ 
rithm  for  an  iterative  one. 

It’s  easy  to  search  for  a  node  or  in¬ 
sert  a  node  into  a  tree  in  a  nonrecur¬ 
sive  way  because  you  never  have  to 
remember  where  you  came  from. 
That  is,  you  only  have  to  descend  to 
the  proper  node  and  never  have  to  go 
back  up  again.  A  nonrecursive 
search-and-insert  function  is  given 
on  lines  30  —  GG  of  Listing  One. 

Nonrecursive  traversal  is  a  harder 
problem  because  you  have  to  go 
backward.  In  a  recursive  traversal 
routine,  the  pointer  to  the  previous 
node  is  stored  on  the  run-time  stack, 
as  part  of  the  current  subroutine’s 
stack  frame.  That  is,  the  pointer  to 
the  current  node  is  passed  to  a  recur¬ 
sive  subroutine  as  a  parameter.  That 
parameter  won't  be  modified  by  sub¬ 
sequent  recursive  calls  because  it’s 


stored  on  the  stack  by  each  successive 
recursive  call. 

In  an  iterative  traversal,  you  don't 
have  the  luxury  of  a  run-time  stack. 
One  solution  to  this  problem  is  to 
maintain  your  own  stack  of  pointers 
to  previous  nodes  as  a  static  data 
structure,  thereby  moving  the  previ¬ 
ous-node  information  from  the  run¬ 
time  stack  to  the  static  data  area.  This 
method  wastes  space,  though,  be¬ 
cause  you  already  have  a  convenient 
place  to  store  the  previous-node 
pointers — in  the  tree  itself.  As  you  de¬ 
scend  the  tree,  you  can  reverse  the 
pointer  that  you  just  used  to  get  to  the 
current  node  so  that  it  now  points 
back  up  to  the  previous  node.  As  you 
ascend  back  up,  you  reverse  the 
pointer  again.  The  basic  traversal  al¬ 
gorithm  is  shown  in  Table  1,  below. 

Deciding  in  which  direction  to  go 
when  you’re  at  any  given  node  is  a 
problem.  You’ll  go  through  every 
node  three  times —  once  on  the  way 
down,  once  again  as  you  ascend  from 
the  left,  and  a  third  time  as  you  as¬ 
cend  from  the  right.  The  problem  is 
resolved  by  "marking”  a  node  after 
you’ve  printed  the  left  subtree  but 
before  you  descend  right  (that  is,  the 
second  time  you  visit  it).  This  way, 
when  you  come  back  up  from  the 
right,  you  can  look  at  the  mark  and 
decide  to  ascend  rather  than  go  right 
again.  Only  one  bit  is  needed  to  mark 
a  node,  so  because  my  nodes  have  an 
ASCII  string  as  one  of  their  fields,  I  set 
the  high  bit  of  the  first  character  in 
the  string  to  mark  a  node.  Macros  to 
set,  clear,  and  test  this  bit  are  on  lines 


23—25  of  Listing  One.  If  an  extra  bit 
isn’t  available,  you  can  always  add  a 
tag  field  to  the  LEAF  structure,  but  it 
seemed  like  a  waste  of  memory  to  do 
that  here. 

The  routine  /r_travf  )  (on  lines 
245  —  301  of  Listing  One)  is  a  straight¬ 
forward  implementation  of  the  algo¬ 
rithm  in  Table  4.  It  does  an  in-order 
traversal.  Comments  are  inserted  in 
the  code  to  show  where  preorder  or 
postorder  visits  should  go  (remove 
the  in-order  visits  in  these  cases).  The 
pres  variable  points  at  the  node  cur¬ 
rently  being  visited.  The  prev  vari¬ 
able  points  at  the  present  node’s  par¬ 
ent.  Next  is  just  a  convenient  place  to 
put  things  as  you  reverse  pointers. 

There  are  other  nonrecursive  tra¬ 
versal  algorithms  (the  most  interest¬ 
ing  is  the  Robson  traversal,  which 
doesn't  need  to  mark  nodes),  but 
they’re  all  more  complicated  to  im¬ 
plement  than  a  simple  link-reversal 
algorithm.  If  you’re  interested  in 
these  other  methods,  look  at  Thomas 
A.  Standish's  book  Data  Structure 
Techniques  (Reading,  Mass.:  Addison- 
Wesley,  1980),  74-83. 

Microsoft  C,  Version  3.0 

To  no  one's  surprise,  I  received  a  call 
from  Microsoft  soon  after  my  review 
of  its  compiler  was  published  in  the 
March  1986  C  Chest.  The  company 
was  (perhaps  justifiably)  miffed,  so  I 
agreed  to  give  it  equal  time  in  the  col¬ 
umn — fair  is  fair.  Sandra  Jacobson 
(product  manager,  Systems  Lan¬ 
guages)  at  Microsoft  sent  me  the  fol¬ 
lowing  letter  in  response  to  that 
review: 

"We  appreciate  Allen  Holub's  com¬ 
ments  regarding  the  Microsoft  C 
compiler.  We  try  to  improve  each 
version  of  the  compiler  through  com¬ 
ments  and  recommendations  from 
users  and  reviewers. 

"Although  we  agree  with  many  of 
the  comments  made  by  Allen,  as  they 
have  also  been  recommended  to  us 
by  other  users  of  Microsoft  C,  we  still 
disagree  with  some  major  points.  The 
following  comments  and  recommen¬ 
dations  have  been  incorporated  into 
Version  4.0  of  the  compiler: 

1.  We  have  improved  the  internal  er¬ 
ror  messages  that  are  displayed.  We 
have  also  improved  on  the  error  re¬ 
covery  in  the  parser. 

2.  The  command-line  interface  has 


do  forever 

iff  present  node  is  marked  ) 

Clear  mark, 
else 

whilef  there’s  a  left  child ) 

Visit  present  node  if  doing  preorder  traversal. 
Go  left. 

Visit  pres  node  if  in-order  or  preorder  traversal. 
Visit  present  node  if  postorder  traversal, 
iff  no  previous  node ) 
break 

iff  previous  node  is  marked ) 

Go  up  from  a  right  child, 
else 

Go  up  from  a  left  child. 

Visit  present  node  if  in-order  traversal. 

Mark  the  present  node. 

Go  right. 


Table  1:  A  link-reversal  tree-traversal  algorithm 
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been  improved  to  correct  the  127- 
byte  limit  for  flags  passed  to  each  of 
the  compiler  passes  from  the  driver. 
There  is  still  a  127-byte  limit  on  invok¬ 
ing  the  compiler  from  the  command 
line.  We  have  also  improved  on  the 
error  recovery  in  the  parser. 

3.  The  internal  error  and  problems 
with  the  spawn  function  have  been 
fixed. 

4.  Because  of  requests  from  users  of 


Microsoft  C,  we  have  included  the  C 
start-up  code  with  Version  4.0  of  the 
C  compiler.  It  is  considerably  more 
than  100  lines  of  code,  and  these  rou¬ 
tines  should  be  used  only  by  experi¬ 
enced  C  programmers  who  have  a 
complete  understanding  of  C  and  MS- 
DOS.  This  will  considerably  help  peo¬ 
ple  who  want  to  create  ROMable 
code. 

5.  The  documentation  on  the  exten¬ 
sions  near  and  far  has  been  improved 
in  Version  4.0. 

"We  feel  that  some  of  the  problems 


that  Allen  discussed  were  based  on 
incorrect  assumptions: 

•  The  differences  between  the  way  a 
Microsoft  library  routine  works 
and  .  .  .  the  equivalent  Unix  routine’ 
are  specified  in  Appendix  B  of  the  Li¬ 
brary  Reference  Manual:  'A  Common 
Library  for  XENIX  and  MS-DOS.'  [I 
missed  it,  sorry. — Allen] 

•  In  reference  to  .  .  strncpy  pads  out 
the  string  with  nulls  to  the  maximum 
count — why?’,  our  implementation 
of  strncpy  is  compatible  with  the 
Unix  System  V  definition  of  strncpy 
as  well  as  the  definition  in  the  devel¬ 
oping  ANSI  standard.  Both  require 
padding  of  the  target  string.  [I  still 
wonder  why,  but  the  problem  isn  t  Mi¬ 
crosoft  's. — Allen  1 

•  With  respect  to  Allen’s  concern 
about  *endif:  '. . .  it  ignores  the  last 
line  of  a  file  if  it  isn't  terminated  with 
a  new  line.  An  #endif  without  a  CR 
gives  an  "unexpected  end  of  file” 
message.'  The  developing  ANSI  stan¬ 
dard  (which  we’re  following  closely) 
specifies  that  a  new-line  character 
(CR-LF)  is  required  as  the  last  charac¬ 
ter  of  every  source  file  that  is  refer¬ 
enced  via  an  # include  statement.  Be¬ 
cause  any  file  may  be  referenced  in 
this  way,  Microsoft  C  does  not  differ¬ 
entiate  between  included  source  and 
main  source.  lOh  come  off  it.  How 
hard  can  it  be  to  check  for  EOF  as  well 
as  CR-LF?— Allen] 

"We  try  to  provide  products  that 
are  worthy  of  use  by  a  wide  variety 
of  users,  both  in-house  and  outside 
Microsoft.  We  encourage  a  strong  di¬ 
alogue  between  our  users  and  our 
product-support  group.  Allen  claims 
that  we  don't  support  our  product, 
yet  he  told  us  that  he  didn’t  contact 
Microsoft  to  verify  that  his  problems 
were  valid  or  to  report  them.  [Mea 
culpa. — Allen)  The  best  way  for  a  user 
of  Microsoft  C  to  make  sure  that  cor¬ 
rections  and  recommendations  to  the 
compiler  are  made  is  to  contact  Mi¬ 
crosoft  Technical  Support  at  (206)  882- 
8089.  Problem  reports  can  also  be 
sent  to  us  at  our  new  address:  Micro¬ 
soft  Corp.,  Technical  Support,  16011 
N.E.  36th  Way,  P.O.  Box  97017,  Red¬ 
mond,  WA  98073-9717.  For  compiler 
errors,  we  suggest  that  the  localized 
problem  be  sent  in  on  a  disk.” 

I’m  tempted  not  to  carry  this  dis¬ 
cussion  any  farther,  but  some  of  Ms. 
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Jacobson's  points  deserve  comment. 
Though  my  remarks  both  here  and 
in  the  original  review  are  critical  of 
the  compiler  (criticism  is,  after  all, 
the  point  of  a  critical  review),  I  do 
think  the  Microsoft  C  compiler  is  a 
good  product  (at  least  when  contrast¬ 
ed  with  other  available  compilers).  I 
use  it  myself.  It  could  be  a  better 
product,  though,  and  I’m  hoping  that 
a  public  discussion  of  its  faults  will 
spur  Microsoft  into  making  a  few  es¬ 
sential  changes.  All  too  often,  new 
products  are  greeted  with  encomi¬ 
ums  rather  than  real  analyses,  and  I 
think  that  honest  critique  from  a 
working  programmer's  perspective 
is  important.  Nobody  benefits  if  I 
don't  talk  about  problems  I  find  in  a 
product  just  because  the  manufactur¬ 
er  of  that  product  claims  that  they'll 
be  fixed  in  the  next  version.  Even  if 
the  technical-support  group  can  tell 
me  about  a  bug  over  the  phone,  the 
bug  still  exists,  and  not  everyone  can 
spend  lots  of  time  on  the  phone  to 
Washington.  I  don’t  want  to  antago¬ 
nize  Microsoft.  What  I  do  want  is  a 
better  compiler,  and  I  honestly  be¬ 
lieve  that  public  discussion  is  the  only 
way  to  bring  this  about. 

1  would  love  to  say  that  the  Micro¬ 
soft  C  compiler  is  the  greatest  thing 
since  peanut  butter,  but  I  couldn't  say 
that  about  Version  3.0  without  my 
nose  growing  several  inches.  I’ve  not 
received  a  review  copy  of  Version  4.0 
yet,  but  it  sounds  as  though  most  of 
the  major  faults  in  the  compiler  (at 
least  the  bugs  and  the  error-recovery 
problems)  have  been  fixed.  I  look  for¬ 
ward  to  getting  a  copy. 

One  major  problem  that  isn’t  ad¬ 
dressed  in  the  letter  is  the  poor  over¬ 
all  quality  of  the  User's  Guide.  To  my 
mind  a  user's  guide  for  a  C  compiler 
shouldn't  also  try  to  teach  you  how  to 
use  DOS — that’s  what  the  DOS  manual 
is  for.  I  hope  that  Microsoft  will  seri¬ 
ously  consider  rewriting  it  for  expe¬ 
rienced  programmers  who  can  read 
above  a  sixth-grade  level.  As  for  tech¬ 
nical  support,  at  $400  for  the  compil¬ 
er,  I  think  Microsoft  should,  at  the 
very  least,  send  out  an  occasional 
newsletter  listing  all  known  bugs  and 
work-arounds  for  them  (I’ve  suggest¬ 
ed  this  to  Microsoft,  and  it  is  consider¬ 
ing  it).  If  the  firm  doesn’t  tell  you 


about  a  known  bug,  then  the  bug  is 
undocumented,  whether  or  not  that 
bug  was  discovered  after  the  docu¬ 
mentation  was  printed.  By  the  same 
token,  the  technical-support  phone 
number  should  be  a  toll-free  number 
(it  isn’t).  Having  to  pay  peak-hour 
phone  rates  to  find  out  about  a  bug 
that  should  have  been  reported  in  a 
newsletter  is  just  adding  insult  to  in¬ 
jury.  Finally,  I  don’t  consider  sending 
in  a  bug  report  and  getting  an  answer 
at  some  indeterminate  future  date  to 
be  adequate  support.  I  want  to  call 
and  get  an  answer  right  then.  If  the 
normal  technical-support  person 
can’t  answer  a  question,  I  want  to  be 
connected  to  someone  who  can.  It 
seems  reasonable  to  have  to  pay  ex¬ 
tra  for  this  kind  of  support,  but  I 
think  it  should  be  available.  (Micro¬ 
soft  is  considering  doing  this,  too.) 

Microsoft,  of  course,  is  not  alone  in 
providing  inadequate  (I  think)  techni¬ 
cal  support,  and  in  all  fairness,  it 
seems  to  be  interested  in  improving 
its  support  process.  I  think  there's  a 
technical-support  problem  in  the  in¬ 
dustry  as  a  whole.  A  "these  guys  are 
just  hobbyists,  so  what  do  they  need 
source  code  or  schematics  for?”  atti¬ 
tude  seems  to  prevail.  My  fond  hope 
is  that  Microsoft,  which  in  my  experi¬ 
ence  is  a  major  offender  in  this  de¬ 
partment,  will  have  a  change  of 
heart  and  lead  the  way  for  better 
technical  support  in  the  industry 
overall.  All  hardware  should  be 
shipped  with  schematics  and  a  com¬ 
plete  technical  description.  Period. 
All  software  documentation  should 
explain  low-level  internals  in  depth, 
and  source  code  should  always  be 
available  if  you  need  it.  Period. 

Lattice  C,  Version  3.0 

I  received  a  copy  of  Version  3  of  the 
Lattice  C  compiler  (3. OF  to  be  exact)  a 
few  months  ago,  and  I’ve  finally  had 
a  chance  to  look  at  it.  This  version 
represents  a  significant  improve¬ 
ment  over  previous  versions.  Func¬ 
tion  prototyping  (strong  type  check¬ 
ing  of  subroutine  arguments)  has 
been  added,  and  the  compiler  has 
been  made  more  Unix-compatible 
overall  (for  example,  unsigned  is  now 
a  modifier  rather  than  a  type).  The 
library  has  also  been  expanded  con¬ 
siderably.  If  you  have  an  earlier  ver¬ 
sion  of  the  compiler,  I’d  definitely 
recommend  an  upgrade,  even  if  you 


have  to  pay  for  it. 

To  test  the  compiler,  I  recompiled 
all  the  routines  in  the  /util  program 
package  that  DDJ’s  currently  distrib¬ 
uting.  I  found  both  good  and  bad 
things.  The  code-size  problem  has 
been  addressed.  The  .exe  files  are 
now  considerably  smaller  than  they 
used  to  be.  On  the  average,  Lattice  ex¬ 
ecutables  are  only  7  percent  larger 
than  the  Microsoft  executables  (gen¬ 
erated  from  the  same  source  code). 
Some  of  the  Lattice  executables  are 
literally  half  the  size  of  the  Microsoft 
versions,  however. 

The  compiler's  error  messages  are 
pretty  good,  and  there  is  now  some 
lint- like  support.  For  example: 

foo( ) 

{ 

int  i; 

return; 

} 

gives  the  error  message  "FOO.c  5 
Warning  93:  no  reference  to  identifi¬ 
er  'i'."  Like  lint,  however,  this  kind  of 
error  checking  can  generate  needless 
noise.  For  example: 

fool ) 

{ 

int  i; 

int  a=l; 

for(  a;  a;  i  +  +  ) 
i  =  6; 

} 

generated  "FOO.c  6  Warning  94:  unin¬ 
itialized  auto  variable  'i'.”  I’d  like  to 
see  a  way  to  disable  these  lint-like  er¬ 
ror  messages  (with  the  exception  of 
the  function  prototype  warnings). 

The  Lattice  compiler  has  several 
subroutines  [ dosintf  ),  for  example] 
that  have  the  same  names,  but  differ¬ 
ent  calling  conventions,  from  those 
of  the  Microsoft  compiler.  This  situa¬ 
tion  came  about  because  they  were 
originally  the  same  compiler,  but  I 
wish  one  or  the  other  of  the  manu¬ 
facturers  would  change  its  subrou¬ 
tine  names.  Microsoft  provides  an  in¬ 
clude  file  with  * defines  that  takes 
care  of  most  of  the  changes.  Lattice 
should  provide  a  similar  file  to  go  in 
the  other  direction. 

There  are  a  few  Unix  I/O  library 
functions  missing  from  the  library, 
though  there  are  often  functional 
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equivalents  in  the  library.  Lattice 
doesn't  have  a  staff  J  system  call,  for 
example.  It  has  several  functions  that 
give  you  the  same  information  as 
would  stat  [for  example,  getfa(  )  and 
access (  J].  Nonetheless,  I’d  like  to  see  a 
Unix-compatible  function,  too. 

I  also  found  a  couple  of  trivial  but 
annoying  bugs — for  example,  the  en¬ 
vironment  string  vector  array  [point¬ 
ed  to  by  the  envp  argument  to 
main(  j]  isn't  terminated  in  the  right 
place  (there's  one  too  many  entries, 
and  the  last  one  is  garbage). 

A  rather  weird  bug  showed  up 
when  I  tried  to  redirect-append  OX 
the  output  from  Lattice-compiled 
programs  from  the  Microsoft-com¬ 
piled  shell.  The  Lattice-compiled  pro¬ 
grams  overwrote  the  file  rather  than 
adding  text  to  the  end  of  it.  The  same 
programs  had  no  problem  when 
running  under  command.com,  and 
they  also  worked  fine  with  simple  re¬ 
direction  (»  with  the  shell.  I’m  not 
blaming  Lattice  for  this  one  [seeing  as 
Microsoft  C  has  spawnf  )  problems,  I 
suspect  the  problem  lies  there],  but 
the  problem  did  arise. 

Finally,  Lattice  told  me  that  my 
version  of  the  compiler  had  bugs  in 
the  in-line  8087  code  generation. 
Though  these  particular  problems 
should  be  fixed  by  the  time  you  see 
this  column,  I  ha ven  ’t  received  an  up¬ 
date  so  I  can’t  verify  this. 

Perhaps  the  biggest  potential  prob¬ 
lem  with  the  compiler  is  the  docu¬ 
mentation.  Lattice  has  returned  to 
the  insanity  of  a  manual  augmented 
with  a  Technical  Bulletin.  The  manual 
I  received  was  the  same  one  that  was 
shipped  with  Version  2.15.  It  is  sup¬ 
plemented  with  a  Technical  Bulletin 
that  is  almost  the  same  size  as  the 
manual.  At  least  there's  an  index  that 
references  both  volumes,  but  it's  still 
annoying  to  have  to  go  back  and 
forth — I  always  seem  to  pick  up  the 
wrong  volume.  The  Technical  Bulle¬ 
tin  lists  all  the  library  routines  in 
strict  alphabetical  order,  which  is 
good.  The  manual  itself  does  not, 
however — routines  are  grouped  by 
function,  another  annoyance  when 
you’re  trying  to  find  something. 
Moreover,  the  bulletin  doesn't  have  a 
functional  index  (one  that  groups  li¬ 
brary  routines  by  function  and  then 


provides  a  capsule  description  of 
each  routine).  It  has  an  alphabetical 
index  with  capsule  descriptions,  but 
this  isn't  much  use  if  you  know  what 
you  want  to  do  but  don't  know  the 
name  of  the  routine  that  does  it.  A 
note  came  with  the  compiler  saying 
that  the  company  is  working  on  a  sin¬ 
gle,  integrated  manual  that  will  be 
sent  to  all  registered  users  at  no 
charge,  but  I  haven’t  seen  this  new 
manual  yet. 

Another  problem  is  the  amount  of 
work  you  have  to  do  to  compile  a 
program.  The  Lattice  compiler 
comes  with  a  horde  of  batch  files  and 
libraries.  Even  with  these  batch  files, 
compiling  is  not  a  one-step  process 
because  you  have  to  juggle  parame¬ 
ters  to  the  linker  too.  It’s  up  to  you  to 
remember  what  libraries  to  link.  One 
of  the  things  I  really  like  about  the 
Microsoft  compiler  is  the  one-step  cl 
driver  program.  It's  an  almost  exact 
look-alike  of  the  Unix  cc  driver  and 
takes  most  of  the  pain  out  of  compil¬ 
ing.  It  figures  out  what  libraries  to 
link  and  even  invokes  the  linker  for 
you.  The  Lattice  compiler  could  ben¬ 
efit  immeasurably  from  the  inclusion 
of  a  similar  driver  program. 

One  final  problem:  The  Lattice 
compiler  still  can’t  generate  assem¬ 
bly-language  source  files  directly. 
Lattice  provides  you  with  a  program 
that  disassembles  object  modules,  but 
I've  never  liked  this  approach.  It’s 
just  too  awkward  to  use.  With  any 
new  release  of  a  compiler,  it’s  critical 
to  be  able  to  see  the  code  that  the 
compiler  generates.  That’s  the  only 
way  to  tell  if  an  error  is  yours  or  if  it  is 
a  bug  in  the  compiler  itself.  Object- 
module  disassembly  makes  it  unnec¬ 
essarily  difficult  to  get  at  the  assem¬ 
bly-language  source.  It’s  also  another 
program  that  could  potentially  intro¬ 
duce  bugs  into  acceptable  object  code 
(though  I've  never  seen  this  happen,  I 
worry  about  it). 

In  conclusion,  I  think  this  version 
of  the  compiler  is  significantly  better 
than  previous  versions.  Lattice  is 
back  in  the  running,  at  least  in  terms 
of  features  and  code  size.  The  compil¬ 
er,  in  spite  of  all  its  improvements,  is 
not  a  clear  winner,  though.  Some  of 
the  problems  (such  as  the  8087  bugs) 
are  the  result  of  a  too-early  release 
date.  Similarly,  the  library  documen¬ 
tation  in  its  present  form  is  not  really 
acceptable  (though  it's  a  lot  better 


than  some  manufacturers’  docu¬ 
mentation).  The  compiler  is  also 
harder  to  use  than  I’d  like,  and 
the  library  is  not  as  Unix-compatible 
as  I'd  like.  On  the  other  hand,  Lattice 
not  only  gives  you  root-module 
sources  but  will  also  sell  you  the 
source  for  the  rest  of  the  I/O  library. 
(I’ve  heard  talk  of  Microsoft  doing  the 
latter,  but  I  haven't  seen  an  official 
announcement  yet.  Microsoft  is  re¬ 
leasing  the  root  module  with  Version 
4.0.  Manx  gives  you  all  the  sources  if 
you  buy  its  professional  package.) 
Various  sources  for  the  error-pro¬ 
cessing  routines  are  also  included 
with  the  Lattice  compiler  package.  So 
this,  too,  is  a  good  product.  I  like  it, 
but  there’s  plenty  of  room  for 
improvement. 

Coming  Attractions 

Next  month  I’ll  continue  looking  at 
trees.  I’ll  refine  the  in-order  graphic 
traversal  routine  a  little  further,  and 
I’ll  look  in  depth  at  AVL  balanced 
trees.  AVL  trees  are  guaranteed  to  be 
almost  perfectly  balanced  (the  imbal¬ 
ance  is  at  most  one  level),  so  they’re 
very  useful  when  you  want  a  best- 
case  access  time  and  don’t  care  if  it 
takes  a  little  longer  to  create  the  tree. 
I’ll  also  look  at  the  problem  of  delet¬ 
ing  a  node  from  a  binary  tree. 

Availability 

The  shell  is  available  from  DDJ  (see 
advertisement  on  page  78).  All  the 
code  published  this  month  is  avail¬ 
able  both  on  CompuServe  (type  go 
ddjforum)  and,  for  $25,  on  an  IBM  PC- 
compatible  disk  from  Software  Engi¬ 
neering  Consultants,  P.O.  Box  5679, 
Berkeley,  CA  94705.  The  tree  routines 
that  I'll  look  at  next  month  are  on  the 
same  disk. 

DDJ 


(Listings  begin  on  page  68.) 

Vote  for  your  favorite  feature/article. 
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A  Forth  Standards  Proposal: 

Extended 

Control  Structures 

by  George  W.  Shaw  II 


The  control 
structures  in 
the  Forth  83 
Standard  leave  some¬ 
thing  to  be  desired. 

This  is  less  stressful 
than  it  seems  as  all 
Forth  programmers 
or  systems  implementors  simply  write  their  own  pre¬ 
scriptions  for  the  ills  that  plague  them  most.  Unfortunate¬ 
ly,  of  those  published,  all  fail  to  supply  a  general  solution 
to  the  problems,  few  are  written  in  a  manner  that  would 
pass  the  Standards  Team,  and  none  of  them  are  part  of 
the  current  standard. 

Many  partial  solutions  have  been  made  public,  but  a 
complete  solution  becomes  riddled  with  new  words  or 
plagued  by  unclear  or  nonstandard  syntax.  Many  efforts 
solve  only  limited  problems  or  do  not  maintain  compatibil¬ 
ity  with  existing  control  structures.  It  seems  clear  that  of¬ 
ten  the  authors  are  not  aware  of  the  general  problem,  are 
able  to  solve  only  a  specific  fragment,  or  overgeneralize 
their  solution  at  the  expense  of  compatibility  and  clarity.1 

The  Standard 

Table  1,  page  31,  lists  the  syntax  of  the  standard  control 
structures.  They  are  fairly  simple.  The  standard  does  not 
specify  the  implementation  of  standard  words,  only  their 
behavior.  The  code  for  the  control  structures  in  most 
Forth  implementations,  however,  is  very  close  to  that 
presented  in  Listing  One,  page  82.  (For  clarity,  compiler 
security  is  omitted.)  Note  that  the  listing  includes  the  Sys¬ 
tem  Extension  Word  Set  compiler-layer  words  >MARK, 
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>  RESOLVE,  <MARK, 
and  <RESOLVE.  The 
System  Extension 
Word  Set  nucleus- 
layer  words  BRANCH 
and  ?BRANCH  are  as¬ 
sumed  available,  as 
well  as  the  nonstan¬ 
dard  run-time  words  (DO),  (LEAVE),  (LOOP),  and  (+LOOP). 

There's  more  than  one  way  to  strip  a  parity  bit,  and  the 
standard  control  structure  words  are  no  exception.  One 
implementation  variant  of  interest  is  LEAVE,  which  is  used 
to  exit  a  DO  loop.  The  implementation  options  were  the 
first  step  in  reaching  the  solution  presented  in  this  article. 

The  History 

In  Forth  79,  LEAVE  does  not  exit  DO  loops  directly  but 
typically  adjusts  the  DO  loop's  parameters  so  that  the  next 
time  LOOP  or  +LOOP  executes  the  loop  will  terminate. 
With  the  new,  better  DO-loop  operation  specified  in 
Forth  83,  the  old  LEAVE  behavior  no  longer  works.  LEAVE 
cannot  adjust  the  DO-loop  parameters  so  that  LOOP  or 
+LOOP  can  reliably  determine  if  they  should  terminate. 
A  different  behavior  of  LEAVE  is  required.  Hence,  Forth  83 
specifies  that  LEAVE  exits  the  loop  immediately. 

That  is  fairly  straightforward,  right?  Wrong.  Because 
LEAVE  must  be  conditionally  executed  to  be  useful  (see  Ta¬ 
ble  1),  it  must  have  the  ability  to  exit  from  within  any 
structure  in  which  it  might  be  nested,  to  the  point  just  past 
the  next  LOOP  or  +LOOP.  Because  Forth  is  very  struc¬ 
tured,  during  compilation  almost  all  branch  and  structure 
addresses  are  simply  nested  on  the  stack  and  resolved 
from  the  stack.  Thus,  compiling  an  “unstructured''  branch 
to  just  after  LOOP  or  +LOOP  pierces  the  nested  levels  and 
must  be  handled  differently.  To  further  complicate  things, 


The  structures  proposed  in  this 
article  cover  almost  every  control 
structure  ever  proposed. 
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the  standard  specifies  that  multiple  LEAVES  are  allowed  in 
a  DO  loop.  One  of  two  approaches  is  usually  taken  to  solve 
the  compilation  problem. 

In  the  first  approach,  the  address  just  after  LOOP  or 
+LOOP  is  stored  with  the  loop  parameters  and  is  accessed 
when  LEAVE  is  executed.  It  is  easy  to  compile  because 
there  is  no  branch  address  to  resolve  during  compilation. 
This  approach  also  uses  minimal  overall  memory  and 
actually  saves  memory  with  multiple  LEAVES  compared 
to  the  second  approach.  Its  limitations  are  that  all  LEAVES 
branch  to  the  same  place  (not  a  problem  within  the  stan¬ 
dard)  and  additional  loop  parameter  space  is  required  for 
each  nesting  level  of  a  DO  loop. 

The  second  approach  is  to  allow  each  compiled  LEAVE 
its  own  branch  address.  (See  Listing  One.)  It  uses  minimal 
overall  memory  when  a  single  LEAVE  exists  in  a  DO  loop 
(99  percent  of  the  cases)  and  just  slightly  more  memory 
(for  each  branch  address)  than  the  first  approach  when 
multiple  LEAVES  exist  in  a  DO  loop.  This  approach  also 
uses  minimal  loop  parameter  memory  and  allows  each 
LEAVE  its  own  unique  destination,  albeit  nonstandard.  It 
appears  difficult  to  compile,  but  this  is  not  the  case.  The 
branch  addresses  are  simply  maintained  in  a  linked  list, 
the  LEAVE-LIST,  which  is  resolved  by  LOOP  or  +LOOP. 
Linked  lists  are  often  needed  elsewhere  in  the  Forth  sys¬ 
tem,  so  the  overhead  of  the  compiling  words  >MARKLIST 
and  >RESOLVESLlST  may  be  nonexistent.  Once  you  accept 
the  power  vs.  compilation-complexity  trade-off,  some 
very  useful  structures  can  be  built. 

LEAVE  naturally  appears  somewhat  unstructured, 
though  it  does  comply  with  the  structured  programming 
rule  it  seems  to  break  most  flagrantly.  Structured  pro¬ 
gramming  requires  that  each  program  module  have  a 
single  entry  point  and  a  single  exit  point.  In  a  DO  loop,  the 
entry  point  is  at  DO,  and  the  exit  point  is  just  after  LOOP  or 
+LOOP.  LEAVE  branches  to  just  after  LOOP  or  +LOOP.  In  a 
puff  of  logic,  LEAVE  becomes  somewhat  structured. 

Common  Extensions 

Most  Forth  implementations  extend  the  standard  control 
structures  a  bit,  frequently  in  the  area  of  BEGIN  loops. 
These  are  fairly  simple  and  obvious  extensions  that,  de¬ 
spite  these  facts,  are  nonstandard.  If  you  replace  the  cor¬ 
responding  standard  style  code  in  Listing  One  with  the 
code  in  Listing  Two,  page  82,  you  have  typical  extensions. 
These  upgrades  are  significant,  but  no  great  shakes. 

The  behaviors  of  the  typical  extensions  are  not  part  of 
the  standard  but  are  compatible  with  it.  They  allow  the 
syntax  additions  shown  in  Table  2,  right.  Code  for  the 
CASE  statement  listed  in  Table  2  is  not  supplied  because  it 
is  probably  not  a  candidate  for  standardization  because 
its  usefulness  is  limited.  OF  only  allows  checking  for  the 
equality  case  on  a  16-bit  value.  If  the  values  are  equal,  the 
code  following  OF  is  executed;  otherwise  execution  con¬ 
tinues  after  ENDOF. 

Unresolved  Problems 

The  extensions  are  useful  and  implementation  is  fairly 
simple,  so  what  is  the  problem?  (See  Table  3,  right.)  All  the 
problems  listed  stem  from  the  desire  to  determine  the 
exit  trail  of  a  loop.  A  programmer  trying  to  write  stan¬ 
dard  code  is  currently  required  to  float  a  flag  or  value  on 


the  stack  (heaven  forbid  you  should  use  a  variable)  to  indi¬ 
cate  the  exit  trail.  Because  you  cannot  exit  where  you 
need  to,  you  must  retest  after  the  loop  for  what  you  al¬ 
ready  knew  when  you  were  in  the  loop  but  had  to  lose. 

The  first  three  problems  apply  to  standard  control 
structures: 

1.  Because  all  LEAVES  branch  to  the  same  point,  it  is  impos¬ 
sible,  without  retesting  a  flag  or  condition,  to  determine 
which  exit  was  used. 

2.  Because  LEAVE  and  LOOP  or  +LOOP  continue  after  loop 
termination  at  the  same  place,  it  is  impossible,  without 
retesting  a  flag  or  condition,  to  determine  how  the  loop 
was  terminated. 

3.  There  is  no  mechanism  for  directly  exiting  through  mul¬ 
tiple  levels  of  BEGIN  loops  or  DO  loops.  The  only  method 
currently  available  is  to  ripple  a  flag  all  the  way  out. 
Knowing  how  the  loop  was  exited  would  also  be  useful 
here. 

The  last  two  problems  apply  only  to  common  extensions: 


4.  Because  all  WHILE s  in  a  BEGIN  loop  branch  to  the  same 


IF  THEN 

IF  ELSE  THEN 

BEGIN  UNTIL 

BEGIN  WHILE  REPEAT 

DO  LOOP 

DO  +  LOOP 

DO  IF  LEAVE  THEN 

LOOP 

DO  IF  LEAVE  THEN 

+  LOOP 

Table  1:  Forth  83  Standard  control  structures 


BEGIN 

REPEAT 

BEGIN 

WHILE  WHILE  .. 

.  REPEAT 

BEGIN 

WHILE  WHILE  .. 

.  UNTIL 

CASE 

OF  ENDOF  OF 

ENDOF  .. 

.  ENDCASE 

Table  2:  Common  nonstandard  extensions 


Standard: 

1 .  Can’t  handle  each  LEAVE  exit  separately  without  retesting  for 
the  exit  condition  after  exit 

2.  Can’t  handle  LOOP  termination  separately  from  LEAVE  exits 

3.  Can’t  exit  directly  through  multiple  levels  of  begin-loops  or 
do-loops 

Common  Extensions: 

4.  Can’t  handle  each  while  exit  separately  without  retesting  for 
the  exit  condition  after  exit 

5.  Can’t  handle  until  termination  separately  from  while  exits 


Table  3:  Limitations  of  standard  control  structures  and 
common  extensions 
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Proposed  Extensions 


BEGIN  IF  LEAVES  ...  REPEAT  THEN 

BEGIN  IF  LEAVES  ...  UNTIL  ELSE  THEN 

BEGIN  IF  LEAVE  THEN  .  .  .  REPEAT 

BEGIN  IF  LEAVE  THEN  .  .  .  UNTIL 

BEGIN  BEGIN  IF  LEAVES  .  .  .  REPEAT  OUTSIDE  REPEAT  THEN 

BEGIN  BEGIN  IF  LEAVES  .  .  .  REPEAT  OUTSIDE  UNTIL  ELSE  THEN 

CASE  IF  LEAVES  IF  LEAVES  .  .  .  ENDCASE 

DO  IF  LEAVES  .  .  .  LOOP  THEN 

DO  IF  LEAVES  ...  +LOOP  THEN 

DO  DO  IF  LEAVES  .  .  .  LOOP  OUTSIDE  (+)LOOP  THEN 

DO  DO  IF  LEAVES  ...  +LOOP  OUTSIDE  (+)LOOP  THEN 


Suggested  Additions  for  Efficiency 


DO 

?  LEAVE 

LOOP 

DO 

?LEAVE 

+  LOOP 

DO 

7LEAVES 

LOOP 

THEN 

DO 

7LEAVES 

+  LOOP 

THEN 

IF 

IF  . 

,  .  IF 

THENS 

IF 

IF  .. 

.  .  IF 

ELSES 

THEN 

Table  4:  Proposed  extensions  and  additions 


IF  THEN 

IF  ELSE  THEN 

BEGIN 

UNTIL 

BEGIN 

REPEAT 

BEGIN 

WHILE  REPEAT 

BEGIN 

WHILE  WHILE  . 

..  REPEAT 

BEGIN 

WHILE  WHILE  . 

..  UNTIL 

BEGIN 

IF  LEAVES  .  .  . 

REPEAT  THEN 

BEGIN 

IF  LEAVES  .  .  . 

UNTIL  ELSE  THEN 

BEGIN 

IF  LEAVE  THEN 

. . .  REPEAT 

BEGIN 

IF  LEAVE  THEN 

.  .  .  UNTIL 

BEGIN 

BEGIN  IF  LEAVES  .  .  .  REPEAT  OUTSIDE  REPEAT  THEN 

BEGIN 

BEGIN  IF  LEAVES  .  .  .  REPEAT  OUTSIDE  UNTIL  ELSE  THEN 

DO 

LOOP 

DO 

+  LOOP 

DO 

IF  LEAVE  THEN 

LOOP 

DO 

IF  LEAVE  THEN 

+  LOOP 

DO 

IF  LEAVES  .  .  .  LOOP  THEN 

DO 

IF  LEAVES  .  .  .  +  LOOP  THEN 

DO 

DO  IF  LEAVES 

.  .  LOOP  OUTSIDE  (+)LOOP  THEN 

DO 

DO  IF  LEAVES 

..  +  LOOP  OUTSIDE  (+)LOOP  THEN 

DO 

7LEAVE  LOOP 

DO 

7LEAVE  +LOOP 

DO 

7LEAVES  LOOP 

THEN 

DO 

7LEAVES  +LOOP 

THEN 

CASE 

IF  LEAVES  IF 

LEAVES  ...  ENDCASE 

IF  IF  ...  IF  THENS 

IF  IF  ...  IF  ELSES 

THEN 

Table  5:  Proposed  standard  control  structures 
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point  (just  after  REPEAT  or  UNTIL),  it  is  impossible  to  deter¬ 
mine  which  exit  was  used  without  retesting  a  flag  or 
condition. 

5.  When  an  UNTIL  terminates  a  BEGIN  loop  containing  one 
or  more  WHILES,  it  is  impossible  to  determine  how  the 
loop  was  terminated  without  retesting  a  flag  or  condition. 

About  90  percent  of  the  loops  coded  can  be  coded  with¬ 
out  too  much  effort.  It  is  difficult,  if  not  impossible,  to  code 
the  other  10  percent  without  resorting  to  setting  a  variable 
or  using  some  other  unworthy  method.  Without  solutions 
similar  to  those  below,  many  programmers  have  spent 
hours  trying  to  code  reasonably  efficient  complex  loops. 

Proposed  Extensions 

Having  collected  this  information,  what  can  be  deduced 
about  the  problem? 

1.  The  exit/termination  cases  following  loop  execution 
need  to  be  handled  better. 

2.  The  problems  are  identical  for  both  DO  loops  and  BEGIN 
loops. 

3.  The  loop  exit  word  must  be  executed  conditionally  to 
be  useful. 

4.  The  THEN  following  LEAVE  is  redundant  because  no 
code  between  LEAVE  and  THEN  can  ever  be  executed. 

5.  Given  that  the  conditional  exit  test  produces  only  exit 
and  don  't-eyit  results,  there  are  only  two  cases  that  must 
be  made  programmable:  the  exit  case  and  the  don ’t  exit 
case. 

Given  these  deductions,  the  following  preferences  are 
likely: 

1.  Because  the  problems  are  the  same  for  both  DO  loops 
and  BEGIN  loops,  a  common  syntax  would  be  valuable — 
something  such  as  LEAVE  but  more  flexible. 

2.  Because  the  exit  word  must  be  used  conditionally,  in¬ 
troduction  of  the  word  with  an  IF- type  word  is  necessary. 
A  syntax  similar  to  LEAVE  is  probable. 

3.  Because  the  THEN  after  LEAVE  is  redundant,  our  word 
should  incorporate  the  THEN  function. 

4.  Because  the  destination  of  our  exit  branch  is  deter¬ 
mined  by  the  programmer,  a  THEN- type  destination 
marker  is  necessary. 

5.  Because  the  don't-eyit  condition  continues  execution 
after  the  IF-ELSE-THEN  clause  (at  the  old  THEN  point)  and 
execution  after  exit  resolves  to  execute  elsewhere,  our 
exit  word  could  be  considered  analogous  to  ELSE. 

We  might  now  draw  the  following  conclusion:  A  condi¬ 
tional  exit  with  a  structure  similar  to  IF-ELSE-THEN  would 
be  appropriate,  with  the  IF-ELSE  part  existing  inside  the 
loop  and  the  THEN  part  indicating  the  destination.  Fur¬ 
thermore,  the  current  IF-ELSE-THEN  words  perform  ex¬ 
actly  the  desired  functions,  except  that  the  ELSE-type 
word  needs  to  discard  the  loop  parameters  when  exiting 
a  DO  loop.  Hence,  if  a  word  were  added  to  the  IF-ELSE- 
THEN  family  to  perform  the  appropriate  ELSE- type  func- 
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tion,  a  complete  structure  and  syntax  would  exist. 

The  proposed  word  is  LEAVES  and  belongs  to  the  IF- 
ELSE-THEN  family.  The  name  is  appropriate,  being  similar 
to  LEAVE.  It  reads  well,  and  it  expresses  immediacy.  The 
word  OUTSIDE  is  also  proposed  to  allow  exiting  several 
levels  of  BEGIN  loops  or  DO  loops  directly.  Examples  of 
their  uses  are  represented  in  Table  4,  page  32.  The  addi¬ 
tional  words  presented  in  this  article  are  proposed  to  be 
part  of  the  standard  as  a  new  word  set,  or  even  better  as  a 
new  level  above  the  existing  Required  Word  Set. 

Implementation 

As  described  above,  the  Forth  83  LEAVE  was  not  obvious  to 
implement.  It  does,  however,  open  the  door  to  the  control 
structure  implementation  solution.  Thanks  to  David  Har- 
ralson,whom  I  met  at  the  1985  FORML  Conference  inAsilo- 
mar,  California,  for  extending  the  concept.  He  presented 
a  paper  there  2  that  seemed  to  solve  all  the  problems  (and 
more)  but  completely  lacked  compatibility  with  the  cur¬ 
rent  standard.  We  formed  a  working  group  at  the  meet¬ 
ing  to  discuss  the  problem,  spent  several  hours  on  the 
telephone,  and  exchanged  several  letters  during  the 
months  that  followed.  His  functional  but  nonstandard  im¬ 
plementation,  combined  with  a  partial  solution  I  had  al¬ 
ready  achieved,3  evolved  into  the  results  seen  here.  By 
working  together  we  were  able  to  extract  the  key  con¬ 
cept  from  his  paper:  All  forward  references  are  to  be 
maintained  in  linked  lists  during  compilation. 

We  actually  took  his  paper  and  worked  backward, 
eliminating  the  overgenerality  of  his  structures  that  pre¬ 
vented  them  from  being  standard  compatible.  I  then  re¬ 
solved  the  syntax  difficulties  and  decided  upon  behavior¬ 
al  rules  for  LEAVES  and  OUTSIDE.  Finally,  I  spent  many 
hours  staring  at  the  walls  and  scrawling  on  paper  until 
one  by  one  the  implementation  problems  of  the  more 
conservative  standard-compatible  syntax  were  resolved. 
Out  of  this  also  came  an  almost  free,  flexible  CASE  state¬ 
ment.  Listing  Three,  page  82,  is  the  result. 

As  mentioned,  all  forward  references  are  maintained 
in  linked  lists.  Harralson  prefers  to  keep  the  list  head 
pointers  on  the  stack;  I  prefer  to  use  variables  (sometimes 
a  useful  poison).  I  find  the  variable  implementation  much 
more  clear  even  though  it  may  be  slightly  larger.  It  is  also 
more  easily  modifiable  if  additional  forward  referencing 
structures  are  added  in  the  future.4 

Three  words  need  to  be  added  to  the  System  Extension 
Word  Set  to  handle  forward  compiled  linked  lists: 
> MARKLIST ,  >RESOLVELIST,  and  >RESOLVESLIST .(See 
Listing  Three.)  Notice  that  the  first  and  last  words  are 
already  in  the  system  if  approach  2  (Listing  One)  is  taken 
to  implement  the  standard  LEAVE  operation.  If  the  extend¬ 
ed  control  structures  presented  here  are  adopted,  I  would 
expect  that  all  three  words  have  a  very  good  chance  of 
becoming  standard. 

Three  lists  are  maintained  by  the  system: 

1.  The  IF-LIST  links  all  IF  and  ELSE  branches.  These 
branches  are  resolved  by  ELSE  and  THEN  respectively. 
The  IF-LIST  is  also  used  to  hold  the  unresolved  LEAVES 


branches  once  outside  the  loop  structure.  This  is  how 
LEAVES  can  be  resolved  by  ELSE  or  THEN. 

2.  The  LEAVES-LIST  contains  all  LEAVES  branch  addresses 
while  inside  a  loop.  The  list  is  transferred  to  the  IF-LIST 
after  the  loop  end  is  compiled  to  allow  the  LEAVES  to  be 
resolved  by  appropriate  ELSEs  or  THENs. 

3.  The  LEAVE-LIST  is  a  list  of  LEAVE  branch  addresses,  main¬ 
tained  for  compatibility  with  the  current  LEAVE  function. 
The  list  is  resolved  by  LOOP,  +LOOP,  REPEAT,  and  UNTIL. 
LEAVE  can  be  used  inside  either  DO  loops  or  BEGIN  loops. 

Another  variable  maintained  by  the  system  is  LEAVE-CF. 
This  variable  is  the  key  that  allows  LEAVE  and  LEAVES  to 
work  in  both  BEGIN  loops  and  DO  loops.  CASE,  which  is 
used  by  BEGIN,  and  DO  set  the  value  of  LEAVE-CF  to  BRANCH 
and  LEAVE  respectively.  LEAVE-CF  thus  contains  the  com¬ 
pilation  address  (code  field)  of  the  proper  run-time  rou¬ 
tine  to  be  compiled  by  LEAVE  or  LEAVES,  depending  upon 
whether  a  BEGIN  loop  or  a  DO  loop  is  being  compiled.  The 
compilation  addresses  of  other  exit  routines  can,  of 
course,  be  stored  in  LEAVE-CF.  This  allows  LEAVE  or  LEAVES 
to  be  used  to  exit  almost  any  structure  added  to  Forth.  To 
allow  proper  structure  nesting,  all  list  heads  (IF-LIST, 
LEAVES-LIST,  and  LEAVE-LIST)  and  the  value  of  LEAVE-CF 
must  be  saved  during  compilation  and  the  lists  set  to  0  at 
the  beginning  of  each  new  structure  (BEGIN,  DO,  and 
CASE).  The  heads'  values  and  LEAVE-CF  are  restored  at  the 
end  of  each  structure  (UNTIL,  REPEAT,  LOOP,  +LOOP,  and 
ENDCASE). 

Comparing  the  complexity  of  the  new  implementation 
of  the  IF-ELSE-THEN  structure  in  Listing  Three  to  that  in 
Listing  One,  you  can  see  that  there  is  little  significant  dif¬ 
ference.  Also,  comparing  the  complexity  of  the  new  BE- 
GIN-WHILE-REPEAT  to  that  in  Listing  One  (ignoring  LOO- 
PEN  D  for  a  moment)  or  better  yet  to  the  commonly 
extended  version  in  Listing  Two,  you  can  see  that  here  too 
there  is  little  significant  difference.  The  proposed  struc¬ 
tures’  complexity  is  even  less  in  one  area,  as  WHILE  is  now 
an  alias  for  IF.  The  DO  loop  words  also  follow  this  tradition 
with  no  significant  difference  in  complexity  (LOOPEND 
somewhat  aside). 

Capability  is  not  free,  and  complexity  rears  its  ugly 
head  in  LOOPEND.  First,  within  LOOPEND,  the  backward 
branch  is  resolved  to  the  beginning  of  the  loop,  and  then 
an  entire  linked  list  of  branches  is  resolved  to  the  point 
immediately  following  the  end  of  the  loop.  For  DO  loops 
this  is  the  LEAVE-LIST ,  and  for  BEGIN  loops  it  is  the  IF-LIST 
(to  resolve  the  WHILE  exits).  BEGIN  loops  also  resolve  the 
LEAVE-LIST  after  LOOPEND.  If  any  LEAVES  were  compiled, 
the  list  heads  are  restored  and  then  tne  ena  or  tne  LEAVES- 
LIST  is  found  and  is  linked  to  the  front  of  the  IF-LIST.  The 
new  longer  list  replaces  the  IF-LIST.  This  slightly  complex 
but  necessary  process  allows  THEN  to  be  used  to  resolve 
LEAVES.  The  process  might  be  simplified  if  two  additional 
words  were  added  to  replace  ELSE  and  THEN  in  resolving 
operations  on  the  LEAVES-LIST.  This  unfortunately  inter¬ 
feres  with  the  operation  of  OUTSIDE.  Harralson  and  I  feel 
that  these  are  simply  two  more  words  added  to  remove  a 
small  amount  of  complexity  that  can  be  hidden  within 
the  bowels  of  the  system  word  LOOPEND,  especially  when 
the  IF-LEAVE-THEN  syntax  must  be  retained  for  compati¬ 
bility  with  the  current  standard. 
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The  last  looping-related  word  is  OUTSIDE.  This  word 
must  keep  the  branch  address  of  the  most  recent  LEAVES 
available  to  be  resolved  outside  the  next  level  of  loop.  This 
is  accomplished  by  simply  unlinking  the  top  item  from 
the  IF-LIST  into  the  the  top  of  the  LEAVES-LIST.  Outside  the 
next  level  of  loop,  the  branch  address  will  be  transferred 
back  to  the  IF-LIST  again  by  LOOPEND.  This  process  can  be 
repeated  as  necessary.  When  multiple  LEAVES  are  used, 
OUTSIDE  can  be  placed  between  LEAVES  resolutions  to 
work  upon  the  correct  one.  OUTSIDE  must  also  ensure 
that  LEAVES  unnests  the  correct  number  of  DO-loop  levels. 
Unfortunately,  I  cannot  disclose  this  mechanism  because 
it  is  proprietary  to  my  company's  product.  Note  that  be¬ 
cause  of  this  difference  in  unnesting  requirements,  the 
listed  code  for  OUTSIDE  will  not  properly  unnest  through 
a  nested  mixture  of  loops.  Though  easy  to  solve,  this  too  is 
proprietary. 

The  proposed  structures  give  you  an  almost  free  imple¬ 
mentation  of  a  CASE  statement.  It  compiles  in  a  manner 
exactly  equivalent  to  nested  IF-ELSE  statements  but  with  a 
more  readable  syntax  and  a  single  syntactic  nesting  level. 
This  is  equivalent  to  the  else  if  clauses  available  in  C,  Pascal, 
Ratfor,  and  Ada.5  It  can  also  be  implemented  more  directly 
by  implementing  THENS.  (See  Listing  Four,  page  83.)  Simi¬ 
larly,  the  AND1F  proposal  can  be  easily  implemented  by 
defining  ELSES.e  (See  the  examples  in  Listing  Five,  page  83.) 

The  new  LEAVES  structure  seems  even  more  unstruc¬ 
tured  than  the  old  LEAVE.  This  is  not  so.  The  single  exit 
point  of  the  module  simply  needs  to  be  redefined.  The 
program  flow  rejoins  at  the  THEN  of  the  outsidemost 
LEAVES — hence  one  entry  point,  one  exit  point.  In  anoth¬ 
er  puff  of  logic,  even  LEAVES  is  somewhat  structured. 
Working  with  the  same  rules,  when  OUTSIDE  is  consid¬ 
ered,  the  module  becomes  the  outsidemost  DO  to  the  outsi¬ 
demost  THEN,  which  resolves  a  LEAVES  within.  It  is  a 
much  harder  logical  stretch,  but  even  when  OUTSIDE  is 
considered,  this  oft-broken  rule  of  structured  program¬ 
ming  is  somewhat  fulfilled. 

Conclusions 

Listing  Five  lists  examples  of  almost  every  control  struc¬ 
ture  proposal  published  or  presented  to  date  and  the  cor¬ 
responding  solution  using  the  structures  proposed  in  this 
article.  All  the  bases  seem  to  be  covered.  Some  proposals 
may  have  been  omitted,  but  hopefully  none  represent 
structures  that  are  not  adequately  covered  by  the  includ¬ 
ed  proposals. 

Using  linked  lists  for  all  forward  references  might  be 
questioned.  Creating  a  new  /F-type  structure  for  the 
LEAVES',  operation  would  have  solved  that  class  of  prob¬ 
lem  just  as  well,  though  it  would  have  added  additional 
words  that  are  not  really  necessary.  The  almost-free  CASE 
statement  would  vanish  in  an  imposed  limitation  of  syn¬ 
tax.  This  would  complicate  OUTSIDE  and  preclude  the 
useful  ELSES  and  THENS  operations  without  adding  words 
to  mark  their  limits.  (See  the  <STEPS  example  in  Listing 
Five.) 

Table  5,  page  32,  summarizes  the  syntax  of  the  control 
structure  word  set  proposed  for  standardization.  It  is  com¬ 


pletely  compatible  with  the  current  standard  control 
structures  and  the  most  common  nonstandard  extensions. 
It  appears  to  emulate  all  the  tricks  that  have  been  proposed 
to  date  for  these  classes  of  control  structures.  It  implements 
in  19  words  (28  including  the  System  Extension  Word  Set) 
all  the  described  functions  compared  to  33  words  (41  in¬ 
cluding  the  System  Extension  Word  Set)  to  summarize  the 
other  proposals.  The  current  standard  has  11  words  (17 
including  the  System  Extension  Word  Set).  The  materia!  in 
this  article  was  presented  to  the  March  1986  meeting  of  the 
San  Francisco  Chapter  of  the  Forth  Interest  Group,  and  the 
members  voted  two  to  one  in  favor  of  standardization.  I 
hope  the  enthusiasm  continues. 
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ARTICLES 


Forth  Goes  to  Sea 


This  article  describes  an  imple¬ 
mentation  of  the  Forth  lan¬ 
guage  for  the  control  of  a  micropro¬ 
cessor-driven  laboratory  instrument. 
The  laboratory  in  this  case  is  the 
ocean;  the  processor  is  the  Motorola 
MC146805,  a  CMOS  6805  chip.  I  imple¬ 
mented  a  ROM-based  Forth  for  this 
chip  following  the  Forth  79  Standard 
as  closely  as  possible,  but  the  final 
version  (Listings  One  and  Two,  pages 
84  and  88)  has  several  differences 
from  the  standard.  The  deviations 
from  the  79  Standard  are  because 
there  is  no  mass  storage  and  all  the 
code  must  reside  in  ROM.  Memory 
constraints  are  also  important  be¬ 
cause  everything — the  managing 
software  and  the  data  itself — must  fit 
within  8K. 

The  RAFOS  Float  System 

Our  research  group  in  the  Graduate 
School  of  Oceanography  at  the  Uni¬ 
versity  of  Rhode  Island  has  spent  the 
last  two  years  studying  the  Gulf 
Stream  current  in  the  Atlantic  Ocean. 
The  primary  instrument  we  have 
been  using  is  known  as  a  RAFOS  float. 

The  origin  of  the  name  is  some¬ 
what  convoluted.  In  the  ocean  there 
is  a  sound  conducting  channel,  like  a 
waveguide,  called  the  SOFAR  chan¬ 
nel.  Its  depth  varies,  but  in  the  Atlan¬ 
tic  it’s  about  800  meters  deep.  Early  in 
the  1970s,  this  channel  was  utilized  in 
a  neutrally  bouyant  float.  These  ear¬ 
ly  floats  drifted  in  the  channel  emit¬ 
ting  sound  pulses  at  precisely  known 
times.  Listening  stations  on  shore 
picked  up  the  signals,  and  by  triangu¬ 
lating  from  several  stations,  the  float 
positions  were  determined.  These 
floats  were  called  SOFAR  floats.  We're 
now  using  new  floats  that  listen  pas¬ 
sively  to  fixed  sound  sources.  They 


Everett  Carter,  Graduate  School  of 
Oceanography,  University  of  Rhode 
Island,  Kingston,  RI  02881 


by  Everett  Carter 


Forth  has  a  long  his¬ 
tory  in  process  con¬ 
trol  and  data  acquisi¬ 
tion ,  but  its  use  in 
oceanography  is  new. 


thus  work  in  the  opposite  fashion 
from  SOFAR  floats,  hence  their  name 
RAFOS,  which  is  SOFAR  spelled  back¬ 
ward. 

The  RAFOS  float  is  made  of  Pyrex 
glass,  is  about  five  feet  long  and  about 
four  inches  in  diameter,  and  looks 
like  a  big  test  tube.  Inside  it  are  vari¬ 
ous  sensors,  batteries  for  power,  a  ra¬ 
dio,  and  an  MC146805  microprocessor 
that  controls  them  all. 

Our  sampling  scheme  involves  tos¬ 
sing  the  float  into  the  water  (where¬ 
upon  it  sinks  to  the  proper  depth)  and 
letting  it  drift  freely  for  30  to  45  days 
in  the  Gulf  Stream.  After  the  allotted 
time,  the  float  drops  its  ballast  weight 
and  comes  to  the  surface.  It  then 
turns  on  the  radio  and  transmits  its 
data  to  shore  via  satellite.  We  make 
no  attempt  to  recover  the  float — it 
would  cost  more  in  ship  time  than  it 
cost  us  to  build  the  float. 

Beginning  last  fall,  we  have  been 
contemplating  how  to  utilize  the 
next  generation  of  floats.  These  floats 
will  be  used  as  before  but  with  adap¬ 
tive  sampling  strategies  or  for  shorter 
intervals  interactively  with  a  ship. 
An  interactive  scenario  could  in¬ 
volve,  for  example,  putting  a  few 
floats  in  for  a  few  days  and  recover¬ 
ing  them  from  the  same  ship,  which 
then  puts  in  more  floats  in  a  way  that 
depends  upon  the  data  received  from 
the  first  floats. 

The  original  RAFOS  floats  were  all 
programmed  in  assembly  language, 
and  all  the  floats  had  the  same  pro¬ 


gram.  Assembly  code  for  the  interac¬ 
tive  floats  would  be  a  nightmare 
(imagine  writing  machine  code  late 
at  night,  while  seasick,  so  you  can  do 
the  experiment  the  next  day!).  Forth 
was  the  obvious  solution  to  the  prob¬ 
lem  of  how  to  get  the  sampling  pro¬ 
gram  into  the  float  efficiently. 

The  MC14G80S  Processor 

As  mentioned  previously,  the  proces¬ 
sor  in  the  float  is  the  Motorola 
MC146805,  which  is  basically  a  CMOS 
6805.  The  6805  is  a  6800  that  has  been 
specialized  for  process  controlling.  It 
was  the  only  CMOS  alternative  to  the 
1802  when  the  floats  were  first  de¬ 
signed  several  years  ago.  It  is  not  the 
ideal  choice  for  the  implementation 
of  Forth.  In  specializing  from  the  6800 
to  the  6805,  half  the  registers  and  sev¬ 
eral  instructions  were  thrown  away 
and  the  stack  could  not  be  accessed  (it 
saves  only  return  addresses  for  calls 
and  interrupts  and  the  registers  dur¬ 
ing  interrupts). 

One  class  of  instructions  that  are 
particularly  useful  in  implementing 
Forth  are  the  indirect  ones.  An  indi¬ 
rect  jump  instruction  causes  the  pro¬ 
cessor  to  jump  to  an  address  that  was 
pointed  to  by  the  contents  of  a  loca¬ 
tion,  and  that  location  is  identified  by 
a  register  or  other  memory  location. 
Some  processors  have  a  whole  family 
of  indirect  instructions,  jumps,  reads, 
writes,  and  so  on.  Some  of  these  in¬ 
structions  I  learned  to  live  without; 
others  I  had  to  emulate  in  self-modi¬ 
fying  software. 

The  6805  comes  in  several  versions. 
The  one  I  am  using  has  a  memory  ad¬ 
dress  space  of  only  8K,  which  puts 
severe  restrictions  upon  the  system 
because  everything — the  operating 
system,  the  application  program,  the 
memory-mapped  sensor  ports,  and 
the  data — must  all  coexist  in  only  8K. 
In  the  early  floats  that  were  pro¬ 
grammed  in  assembly  language,  the 
code  occupied  the  top  4K  (from  1000 
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hex  to  1FFF),  and  the  data  was  stored 
in  the  lowest  4K.  This  Forth  imple¬ 
mentation  tries  as  much  as  possible  to 
preserve  the  historical  partition  (it 
nearly  succeeds). 

The  Format  of  the  Header 

In  order  to  conserve  the  system’s 
memory  usage,  the  structure  of  the 
headers  is  modified  slightly.  Only  the 
character  count  and  the  first  three 
characters  are  saved  in  the  header. 
This  is  as  if  the  Forth  variable  WIDTH 
was  set  to  3  (note  that  WIDTH  does  not 
explicitly  exist  in  this  implementa¬ 
tion  and  that  all  words  that  would 
use  it  treat  it  as  a  constant  that  is  equal 
to  3).  The  count  byte  has  the  follow¬ 
ing  structure.  The  natural  character 
count  is  in  the  low  5  bits  (hence  allow¬ 
ing  words  up  to  31  characters  long). 
The  sixth  bit  is  the  smudge  bit;  it 
equals  1  when  the  word  is  smudged, 
thus  preventing  a  match  by  —FIND 
and  similar  words.  The  seventh  bit 
has  no  defined  use.  The  eighth  bit  is 
normally  0  but  is  set  to  1  for  immedi¬ 
ate  words  (this  bit  is  called  the  prece¬ 
dence  bit).  Although  strictly  this 
structure  does  not  violate  the  stan¬ 
dard,  it  is  not  the  usual  one.  Tradi¬ 
tionally,  bit  8  is  always  set  to  1  and  bit 
7  is  the  precedence  bit.  The  tradition¬ 
al  structure  was  not  used  in  order  to 
make  WORD  smaller — WORD  masks 
out  the  high-order  bit  of  every  byte 
that  it  examines  in  a  given  word's 
name  field  when  it  is  trying  to  find  a 
match.  In  the  traditional  format,  the 
count  byte  has  a  different  mask  from 
that  of  the  rest  of  the  name  field. 

The  format  of  the  header  is  thus 
the  count  byte,  followed  by  the  first 
three  characters  of  the  word,  a  point¬ 
er  to  the  name  field  (that  is,  the  count 
byte)  of  the  previous  Forth  word,  and 
finally  the  actual  code  for  the  word. 
Note  that  last  point.  After  the  link  is 
the  actual  code — that  is,  the  code 
field,  not  the  code  field  address. 

The  Inner  Interpreter 

The  Forth  interpreter  is  implement¬ 
ed  as  a  direct  threaded  interpreter 
because  of  the  limited  ability  of  the 
6805  processor  to  perform  address  in¬ 
direction.  My  reading  of  the  standard 
is  that  it  does  not  specify  the  type  of 
interpreter  you  should  use,  but  the 
interpreter  is  usually  implemented 
as  an  indirect  threaded  interpreter. 
The  direct  threaded  approach  means 


that  the  code  field  is  not  pointed  to  by 
a  pointer,  but  the  code  actually  be¬ 
gins  where  a  traditional  CFA  pointer 
would  normally  be  (so  that  ’  returns 
the  address  of  the  code  field,  not  the 
address  of  the  pointer  to  the  code 
field).  This  means  that  you  must  exer¬ 
cise  care  in  using  Forth  words  that 
manipulate  addresses  (CFA,  PFA,  NFA, 
and  so  on)  if  you  are  accustomed  to 
using  more  traditional  Forth  imple¬ 
mentations. 

Forth  in  ROM 

Even  though  this  implementation  of 
Forth  is  designed  to  be  ROM-based, 
some  code  resides  in  RAM  for  special 
reasons.  The  6805  has  special,  fast  in¬ 
structions  for  access  to  the  base  page 
(oooo  to  ooff  hex).  The  instructions  are 


Table  1:  List  of  initial  Forth  words 


fast  because  fewer  bytes  are  used  in 
those  instructions  and  because  some 
of  the  base  page  resides  physically 
within  the  processor  chip  itself.  Be¬ 
cause  the  processor  will  spend  the 
bulk  of  its  time  in  the  inner  interpret¬ 
er,  the  inner  interpreter  is  designed 
to  reside  in  the  base  page  (starting  at 
0080  hex). 

All  the  self-modifying  code  must 
reside  in  RAM  in  order  to  work;  this 
code  immediately  follows  the  inner 
interpreter  in  RAM.  The  limited  in¬ 
struction  set  of  the  6805  required  the 
simulation  of  some  instructions  (such 
as  indirect  jumps)  through  the  use  of 
self-modifying  code.  In  many  places  I 
found  I  needed  two  routines — one  to 
load  register  A  into  a  pointed-to  ad¬ 
dress  (an  indirect  write)  and  one  to 


DP 

01  DO 

the  dictionary  pointer 

START 

1E57 

where  the  outer  interpreter  is 

BASE 

10 

initial  base  is  hex  (note  that  this  is  a 
single-byte  variable) 

FORTH 

17E6 

points  to  the  NFA  of  the  last  dictionary 
entry  ( 1 ) 

CONTEXT 

0039 

points  to  FORTH 

CURRENT 

0039 

points  to  FORTH 

Table  2:  The  initial  values  of  the  system  variables.  All  values 
are  hexadecimal. 


TYPE 

WORD 

DP 

STATE 

C! 

LATEST 

SWAP 

IMMEDIATE 

2 

+ 

PAD 

R> 

BASE 

< 

+  - 

DDUP 

[COMPILE] 

THEN 

TIB 

<  +  LOOP> 
I 


EXIT 

<NUMBER> 

HERE 

CONTEXT 

ALLOT 

SP! 

-FIND 

2  + 

<# 

R@ 

SMUDGE 

> 

# 

#S 

BEGIN 

ELSE 

>IN 

DO 


EXECUTE 

DROP 

NOT 

CURRENT 

C, 

LIT 

CR 

COUNT 

[ 

U* 

OVER 

ROT 

ABS 

OR 

VARIABLE 

AGAIN 

WHILE 

'STREAM 

LOOP 


EMIT 

C@ 

1  + 

FORTH 

DUP 

COLD 

CREATE 

0 

] 

U/MOD 

#> 

HOLD 

0< 

SIGN 

AND 

COMPILE 

CONSTANT 

UNTIL 

REPEAT 

<DO> 

-I- LOOP 


BL 

@ 

HLD 

! 

+  ! 

QUIT 

TOGGLE 

1 

DEFINITIONS 
S  — >D 
>R 

M/MOD 

0= 

NEGATE 

XOR 


IF 

<.  ”> 

<LOOP> 

DNEGATE 
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(continued  from  page  41) 


get  the  value  at  that  address  into  A  (an 
indirect  read).  I  called  these  routines 
LOAD  and  GET  in  the  assembly  listing. 
For  generality,  I  wrote  them  to  in¬ 
clude  a  possible  offset  defined  by  reg¬ 
ister  X.  Many  routines  will  define  the 
16-bit  address  defined  at  LOAD+l  or 
GET+i  and  call  LOAD  or  GET.  Because 
they  get  modified,  LOAD  and  GET  are 
in  RAM,  and  because  they  can  be 
called  frequently,  they  are  in  the 
base  page. 

The  self-modifying  code  goes  be¬ 
yond  the  base  page,  but  I  made  an 
effort  to  place  the  most  frequently 
called  portions  within  the  base  page. 
The  predefined  user  variables 
(FENCE,  STATE,  FORTH,  CONTEXT,  CUR¬ 
RENT,  BASE,  HLD,  DP,  IN,  and  OUT)  and 


the  system  variables  (IP,  RP,  and  SP) 
also  reside  in  the  base  page. 

When  the  system  is  booted,  reset, 
or  upon  execution  of  COLD,  the  initial 
values  of  the  user  and  system  vari¬ 
ables,  the  inner  interpreter,  and  the 
self-modifying  code  are  all  copied 
from  ROM  to  their  executable  loca¬ 
tions  in  RAM.  A  note  about  how  the 
code  was  developed:  The  assembly 
code  was  cross  assembled  on  a  VAX 
750  using  the  XASM6805  cross  assem¬ 
bler  from  Intelligent  Devices  of  Min¬ 
nesota  (P.O.  Box  492,  Anoka,  MN 
55303).  The  IDM  cross  assembler  does 
not  allow  the  assembly  of  code  at  one 
location  for  execution  at  another. 
The  code  was  thus  written  for  its  tar¬ 
get  address,  then  the  hexadecimal  as¬ 
sembly  output  file  (which  is  in  Motor¬ 
ola’s  SI  format,  similar  to  the  CP/M 
HEX  format)  was  edited  manually  to 


change  the  compilation  address  for 
the  dozen  or  so  lines  that  needed 
changing. 

The  initial  vocabulary  consists  of 
the  words  listed  in  Table  1,  page  41; 
the  system  variables  are  initially  set 
to  the  values  shown  in  Table  2,  page 
41.  The  vocabulary  is  not  a  full  Forth 
word  set,  but  most  of  the  important 
(non-mass-storage)  words  are  there. 
We  usually  upload  all  the  MOD  arith¬ 
metic  words  from  a  microcomputer 
that  we  use  as  a  terminal  when  we 
use  the  float;  this  is  how  the  data- 
sampling  words  get  loaded  as  well. 
The  initial  system  memory  map  is 
shown  in  Figure  1,  left.  The  variable 
START  (at  address  002E  hex)  does  not 
have  a  header.  It  is  a  warm  boot  exe¬ 
cution  vector  (that  is,  the  address  at 
that  location  is  executed  when  QUIT  is 
invoked),  and  normally  it  points  to 
the  start  of  the  outer  interpreter.  A 
word  that  is  pointed  to  by  START 
should  be  a  Forth  word  that  is  an  infi¬ 
nite  loop  (such  as  a  BEGIN . . .  AGAIN 
structure)  because  it  is  effectively  the 
outer  interpreter  once  QUIT  is  execut¬ 
ed.  Note  that  QUIT  is  a  warm  boot;  it 
does  a  partial  system  reset.  It  clears 
the  stacks  and  sets  the  system  state  to 
execute,  then  it  goes  to  the  address 
pointed  to  by  START.  COLD  runs  the 
same  code  as  the  power-up  or  reset 
interrupt  does — it  resets  the  dictio¬ 
nary  pointer  and  FORTH  to  their 
power-up  default  values  and  sets  the 
CONTEXT  and  CURRENT  vocabularies 
to  FORTH.  (All  this  is  done  by  execut¬ 
ing  the  ROM-to-RAM  copy  described 
above.)  It  then  falls  through  to  QUIT. 

Error  Checking 

In  order  to  minimize  the  size  of  the 
system,  only  a  minimal  amount  of  er¬ 
ror  checking  is  implemented.  If  the 
system  does  not  find  a  word  in  the 
dictionary  and  it  cannot  subsequent¬ 
ly  interpret  it  as  a  number,  that  word 
is  echoed  back  to  the  terminal,  fol¬ 
lowed  by  a  question  mark.  When  this 
happens  the  user  stack  is  unaffected, 
but  the  FORTH  return  stack  is  cleared. 
Clearing  the  return  stack  effectively 
denests  the  system  from  any  process 
out  to  the  outer  interpreter.  The  sys¬ 
tem  is  then  waiting  for  user  input.  If 
the  system  was  in  the  compiling  state 
when  the  error  occurred,  it  will  be  in 
the  execution  state  after  the  error 
message.  This  means  that  if  a  word 
was  not  found  during  compilation, 
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FORTH 
ROM  #1 
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ROM  #2 


FORTH  STACK 


RETURN  STACK 
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Figure  1:  Memory  map 
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you  have  to  start  the  definition  from 
the  beginning  and  not  from  the  point 
where  the  error  occurred.  This  be¬ 
havior  for  compilation  errors  is  com¬ 
mon  to  many  Forth  implementa¬ 
tions. 

It  should  be  noted  that  the  word 
that  was  being  compiled  into  the  dic¬ 
tionary  at  the  time  is  in  the  dictionary 
in  a  smudged  state.  Normally  this  is 
alright  because  the  word  cannot  be 
found  and  accidentally  executed.  If 
FORGET  has  been  compiled,  though, 
the  partially  compiled  word  cannot 
be  forgotten  unless  SMUDGE  is  execut¬ 
ed  before  any  more  manipulation  of 
the  dictionary  occurs. 

Stack  errors  are  not  announced. 
This  is  not  as  bad  as  it  first  sounds  be¬ 
cause  both  the  return  stack  and  the 
user  stack  are  implemented  as  128- 
word  circular  queues.  Being  circular, 
a  runaway  stack  cannot  damage  any¬ 
thing  but  the  stack  itself.  With  128 
words  in  the  stack,  it's  not  likely  that 
anything  useful  in  the  stack  would  be 
corrupted  by  a  stack  error.  It  does 
mean,  though,  that  if  a  program  pops 
data  off  an  empty  stack,  it  will  contin¬ 
ue  on,  using  whatever  it  happened  to 
find  as  data,  without  ever  telling  you 
that  there  was  no  data  there  in  the 
first  place. 

Other  error  messages  are  not  im¬ 
plemented.  Specifically,  these 
include: 

1.  Incomplete  definitions — Improp¬ 
erly  paired  DO .. .  LOOP,  IF . . .  THEN, 
BEGIN .  .  .  UNTIL,  and  similar  struc¬ 
tures  are  not  detected.  Words  that  are 
compiled  with  incomplete  structures 
will  probably  compile  with  no  trou¬ 
ble,  but  trying  to  execute  such  a  word 
will  almost  certainly  crash  the 
system. 

2.  Inappropriate  execution — At¬ 
tempts  to  execute  words  that  are 
compile  only,  such  as  DO  . . .  LOOP, 
are  not  flagged.  Trying  to  execute 
such  words  will  crash  the  system. 

3.  Defining  a  word  that  already  ex¬ 
ists — In  a  normal  Forth  system,  rede¬ 
fining  a  previously  existing  word 
causes  a  nonfatal  warning  message  to 
be  issued  and  compiling  may  contin¬ 
ue.  In  this  system,  no  message  of  any 
sort  is  issued  and  the  continued  com¬ 
piling  is  allowed. 


Major  Deviations  from  the 
Standard 

In  a  few  cases,  I  deviated  from  the 
defined  79  Standard  for  special  rea¬ 
sons.  In  the  spirit  of  Mountain  View 
Press'  Forth  implementations,  one 
thing  that  I  did  was  replace  words  of 
the  form  (xxx)  with  <xxx>.  This  is 
because  the  close  parenthesis  in  (xxx) 
words  causes  trouble  with  Forth 
comments. 

<NUMBER> ,  the  word  that  tries  to 
interpret  input  as  a  number,  does  not 
recognize  double-precision  num¬ 
bers.  This  is  a  violation  from  the  stan¬ 
dard  and  was  done  in  order  to  reduce 
the  size  of  the  system.  Also,  <NUM- 
BEB>  takes  an  address  as  input  and 
returns  either  a  false  flag  (0)  if  the 
conversion  fails,  or  it  returns  a  true 
flag  (  hex  FFFF)  and  an  address  of  the 
result  if  the  conversion  succeeds.  The 
Forth  word  NUMBER  would  be  de¬ 
fined  as  the  following  (except  for  the 
matter  of  double-precision  men¬ 
tioned  above): 

:  NUMBER  < NUMBER >  NOT  IF  ABORT” 
NOT  RECOGNIZED”  THEN  ; 

The  word  NOT  is  defined  in  a  non¬ 
standard  way.  It  returns  the  one’s 
complement  of  the  value  on  the 
stack.  Normally  NOT  is  a  synonym  for 
0—,  which  returns  a  true  (hex  FFFF)  if 
a  0  is  on  the  stack  and  a  false  (0)  other¬ 
wise.  This  version  of  NOT  will  allow 
proper  execution  of  standard  Forth 
words  that  use  NOT  to  complement 
the  result  of  a  logical  test 
( . .  .  9  =  NOT  . . . ).  If,  however,  a  stan¬ 
dard  Forth  word  uses  NOT  when  0= 
is  actually  meant  (for  readability  rea¬ 
sons  perhaps),  then  the  program  will 
not  behave  properly.  This  change 
was  made  because  it  was  thought  to 
be  more  useful  for  process-control 
routines  to  have  a  one's  complement 
word  directly  available. 

The  word  BASE  is  a  1-byte  variable 
instead  of  the  usual  2-byte  form.  This 
means  that  BASE  should  be  accessed 
and  manipulated  by  using  C@  and  C! 
instead  of  @  and  /.  Similarly,  >IN  is  a 
1-byte  variable.  The  word  TIB  is  a 
constant,  not  the  usual  variable,  so 
the  location  of  the  input  buffer  can¬ 
not  be  changed. 

The  Future 

To  date  (March  1986)  none  of  the 
Forth-controlled  floats  have  actually 


gone  to  sea.  So  far  they  have  been 
used  on  the  lab  bench  to  evaluate  the 
new  sensors  that  will  be  on  board  the 
floats  that  are  to  go  into  the  water  this 
coming  fall. 

The  lab  bench  floats  are  not  in  their 
glass  tubes,  so  communicating  with 
the  CPU  is  just  a  matter  of  plugging 
into  the  I/O  port  (port  B  in  the  listings). 
With  the  seagoing  floats,  the  details  of 
the  communication  link  are  still  an 
open  issue.  The  link  will  either  in¬ 
volve  a  watertight  connector  that  goes 
through  the  glass  wall  or  orthogonal¬ 
ly  mounted  (in  order  to  avoid  interfer¬ 
ence)  optical  links. 

A  second  vital  use  that  these  floats 
are  serving  is  to  teach  the  rest  of  the 
research  group  the  Forth  language. 
Forth  has  a  long  history  in  process 
control  and  data  aquisition,  but  its  use 
in  oceanography  is  relatively  new. 
Having  RAFOS  float  CPUs  with  Forth 
ROMs  readily  available  has  proved  in¬ 
valuable  as  a  teaching  aid  for  learn¬ 
ing  Forth. 

As  a  final  footnote,  I  should  point 
out  that  the  code  in  Listings  One  and 
Two  is  the  result  of  one  person's  total 
immersion  in  the  implementation 
process.  As  such  it  could  very  well 
suffer  from  the  lack  of  multiple  criti¬ 
cal  perspectives  on  its  design.  I  would 
welcome  critiques  of  the  result. 
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ARTICLES 


Forth  Windows  for  the 

IBM  PC 


Windows  provide  a  method 
of  presenting  information 
to  computer  users  in  an 
easy-to-use,  natural  manner.  The 
window  environment  can  be 
thought  of  as  an  emulation  of  a  desk. 
The  analogy  is  that  you  are  working 
on  something  that  resides  on  the  top 
of  a  pile  of  paper.  If  you  are  inter¬ 
rupted,  new  work  is  placed  on  that 
pile,  covering  up  the  work  you  were 
doing.  When  you  finish  with  this 
new  work,  you  move  it  off  your  desk 
and  continue  where  you  left  off  on 
the  work  you  were  doing  before. 
This  interruption  and  restoration  of 
the  working  environment  is  the  con¬ 
cept  on  which  the  window  software 
metaphor  is  based. 

This  article  illustrates  the  use  of 
windows  in  the  Forth  environment. 
The  window  package  I  present  here 
uses  the  F83  dialect  of  Forth  devel¬ 
oped  by  Laxen  and  Perry.  The  pro¬ 
gram  is  based  upon  and  inspired  by 
the  article  entitled  "A  Simple  Window 
Package,”  by  Edward  Mitchell,  which 
appeared  in  the  January  1984  issue 
of  DDJ.  In  addition  to  the  primary  top¬ 
ic  of  windows,  I'll  also  discuss  some 
other  subjects,  including  MS-DOS 
memory  management,  manipulation 
of  the  IBM  PC  hardware,  interfacing 
Forth  to  the  PC’s  BIOS  and  BDOS,  and 
Forth  8088  assembly  language. 

People  with  computers  other  than 
an  IBM  PC  (or  a  true  compatible)  and 
people  using  other  dialects  of  Forth 
may  need  to  make  some  changes  to 
the  program  in  order  to  get  it  to  work 
on  their  systems.  The  concepts  pre¬ 
sented  in  this  Forth  implementation 


Craig  A.  Lindley,  6  Sutherland  Pi, 
Manitou  Springs,  CO,  80829 


by  Craig  A.  Lindley 


The  demo  program 
shows  how  to  inte¬ 
grate  the  window 
package  with  an 
application. 


of  windows,  however,  can  be  ap¬ 
plied  to  an  implementation  in  any 
other  computer  language,  including 
C  or  Pascal. 

The  program  presented  in  Listing 
One,  page  96,  is  basically  a  tool  await¬ 
ing  your  use;  it  is  meant  to  be  inte¬ 
grated  into  an  application  program. 
The  number  of  windows  you  can 
have  on  your  display  screen  at  one 
time  is  a  function  only  of  the  amount 
of  memory  you  have  in  your  com¬ 
puter — you  are  not  limited  by  the 
available  memory  in  the  64K  seg¬ 
ment  in  which  Forth  is  running.  The 
demonstration  program  provided  in 
the  listing  shows  how  to  integrate  an 
application  (the  demo  itself)  with  the 
window  routines. 

Memory  Management 

It's  important  to  understand  how  MS- 
DOS  performs  memory  management 
if  you  are  to  understand  how  the  win¬ 
dow  package  works  and  why  it  isn't 
shackled  by  the  64K  segment  con¬ 
straint  imposed  on  the  Forth  system. 
Memory  management  is  not  neces¬ 
sary  just  because  I’m  using  Forth  for 
this  program;  it’s  necessary  for  any 
program,  in  any  language,  that  uses 
more  than  64K  in  its  operation. 


Upon  receiving  control  from  MS- 
DOS,  an  executable  program  is  given 
all  the  memory  available  in  your 
computer  for  its  use,  whether  or  not 
your  program  requires  this  much 
memory.  Under  these  conditions  MS- 
DOS  cannot  manage  memory  because 
there  is  none  left  to  manage — it  all 
belongs  to  your  executable  program. 
In  order  for  MS-DOS  to  manage  the 
memory,  your  program  must  give 
back  to  the  operating  system  the 
memory  it  doesn't  need.  This  is  done 
by  using  the  setblock  function  of  MS- 
DOS.  By  informing  MS-DOS  of  the  total 
memory  requirement  of  your  pro¬ 
gram,  your  allocated  memory  block 
will  shrink  and  the  MS-DOS  pool  of 
free  memory  will  be  given  the  re¬ 
mainder  of  the  available  memory  in 
your  computer.  This  free  pool  of 
memory  can  then  be  managed  for 
your  uses  by  MS-DOS. 

Three  special  words  in  the  Forth 
window  package  deal  with  MS-DOS 
memory  management.  They  are 
setblock,  calloc,  and  free.  Setblock 
shrinks  the  memory  block  allocated 
to  the  Forth  program  of  which  it  is  a 
part.  The  setblock  word  defined  on 
screen  7  accepts  as  a  parameter  the 
number  of  bytes  required  by  the  ap¬ 
plication  (the  Forth  system).  It  returns 
a  true  flag  if  the  memory  block  size 
adjustment  was  successful,  or  it  re¬ 
turns  a  false  flag,  error  code,  and  the 
maximum  number  of  8088  para¬ 
graphs  available  if  the  adjustment 
was  unsuccessful.  The  error  codes 
correspond  to  those  listed  in  the  DOS 
manual. 

In  my  window  application,  the 
word  initialize  calls  setblock  and 
passes  it  a  —1  (FFFF  hex)  as  the  num¬ 
ber  of  bytes  to  be  set  aside  for  Forth’s 
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use.  In  other  words,  Forth  is  given  a 
full  64K  segment  in  which  to  run, 
thereby  excluding  MS-DOS  memory 
management  from  that  area.  Forth 
owns  all  of  this  64K  block. 

After  setblock  gives  MS-DOS  some 
memory  to  manage,  calls  to  the  Forth 
word  calloc  cause  MS-DOS  to  provide  a 
memory  area  for  your  use.  This 
memory  area  comes  directly  out  of 
the  free  pool  and  belongs  to  the  appli¬ 
cation  until  it  is  given  back.  The  word 
calloc  accepts  as  a  parameter  the 
number  of  bytes  required  for  a  new 
memory  block.  It  returns  a  true  flag 
and  the  8088  segment  address  if  suc¬ 
cessful,  or  it  returns  a  false  flag,  error 
code,  and  maximum  number  of  para¬ 
graphs  available  from  the  free  pool, 
if  the  allocation  fails. 

Just  as  memory  blocks  are  given 
out  by  MS-DOS,  they  can  also  be  given 
back  when  an  application  has  fin¬ 
ished  with  them.  The  Forth  word 
free  performs  that  function  in  the 
window  package.  Any  memory 
block  that  has  been  allocated  previ¬ 
ously  can  be  released.  The  word  free 
accepts  the  segment  address  of  the 
block  to  be  returned  and  returns  ei¬ 
ther  a  true  flag  if  successful  or  a  false 
flag  and  error  code  if  not. 

You  should  keep  two  things  in 
mind  when  dealing  with  MS-DOS 
memory  management  functions. 
First,  a  program  should  never  write 
into  any  memory  it  does  not  explicit¬ 
ly  own — for  example,  programs 
must  be  sure  the  stack  is  in  an  area  of 
memory  owned  by  the  application. 
Second,  never  try  to  release  memory 
that  was  not  allocated  by  MS-DOS  orig¬ 
inally.  Violating  either  of  these  rules 
can  result  in  unexplained  behavior 
on  the  part  of  your  computer. 

The  memory  management  words 
used  in  this  window  program  all 
make  calls  to  MS-DOS  int  21h  using  the 
appropriate  function  codes.  MS-DOS 
performs  the  requests,  if  possible, 
and  the  Forth  words  pass  back  flags 
on  the  stack  indicating  the  status  of 
the  requested  operation. 

Lotv-Level  Assembly- 
Language  Words 

Approximately  one  third  of  all  the 
Forth  words  in  this  window  package 
are  written  in  8088  assembly  language 
(see  Tables  1  and  2,  pages  47  and  48). 
There  are  two  reasons  for  this.  First, 
the  F83  package  used  to  develop  this 
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chra  char/attrib  count  - 

Writes  (count)  characters  with  attributes  to  the  screen  starting  at  the  current 
cursor  position.  The  cursor  position  is  left  unchanged.  This  word  calls  BIOS  int 
lOh  using  function  code  9  to  perform  its  operation. 

chra+  char/attrib  - 

Similiar  to  chra  except  only  a  single  character  with  attribute  is  written  and  the 
cursor  position  is  advanced  automatically.  BIOS  int  lOh  is  again  used  to  first 
write  the  character  and  attribute  and  then  to  read  and  advance  the  cursor 
position. 

rdchra  -  char/attrib 

Calls  bios  int  lOh  with  function  code  8  to  return  the  character  and  attribute  of 
the  character  currently  under  the  cursor. 

scrlup  xul  yul  xlr  ylr  count  attrib  - 

Scrolls  up  the  area  of  the  screen  bounded  on  the  upper  left  by  xul  and  yul  and 
on  the  lower  right  by  xlr  and  ylr.  The  window  is  scrolled  up  (count)  lines,  and  the 
blank  lines  scrolled  in  from  the  bottom  are  given  attribute  (attrib).  If  count  is 
specified  as  0,  the  whole  window  is  cleared. 

calloc  #  of  bytes  -  seg  T  -  max  paragraphs  error  code  F 
Initiates  a  memory  allocation  request  to  MS-DOS.  If  the  memory  requested  is 
available,  the  segment  address  and  a  true  flag  will  be  returned.  If  enough  mem¬ 
ory  is  not  available,  then  an  error  code  and  a  false  flag  are  returned  along  with 
the  maximum  number  of  paragraphs  available. 

free  seg  -  T  -  error  code  F 

Attempts  to  release  to  MS-DOS  a  block  of  memory  previously  allocated  via 
calloc  If  successful,  a  true  flag  is  returned.  If  unsuccessful,  an  error  code  and  a 
false  flag  are  returned. 

setblock  #  of  bytes  -  T  -  max  paragraphs  error  code  F 
Asks  MS-DOS  to  shrink  or  expand  the  unassigned  memory  until  the 
application  program  has  the  number  of  bytes  requested  for  its  use.  If  the  opera¬ 
tion  is  successful,  a  true  flag  is  returned.  If  not,  an  error  code  and  a  false  flag 
are  returned,  along  with  the  maximum  number  of  paragraphs  available. 

e@  seg  addr  -  n 

Returns  to  the  top  of  the  parameter  stack  the  data  (n)  at  address  ( addr)  in  mem¬ 
ory  segment  (seg).  I  call  this  word  extended  fetch  because  it  has  access  to  the 
complete  memory  space  and  not  just  the  64K  segment  in  which  Forth  runs. 

e!  n  seg  addr  - 

Stores  the  data  (n)  at  address  ( addr)  in  memory  segment  (seg).  I  call  this  word 
extended  store  because  it  has  access  to  the  complete  memory  space  and  not 
just  the  64K  segment  in  which  Forth  runs. 

rdcur  -  x  y 

Uses  bios  int  1 0h  function  code  3  to  return  the  x,y  location  of  the  cursor. 

save—h,  save—w,  save—ptr,  save— si,  save—ds  -  addr 

These  Forth  words  are  used  as  temporary  storage  locations  during  the 
scr—>buf  and  buf—>scn  routines.  When  executed,  they  return  the  address 
of  a  2-byte  storage  area.  The  storage  area  save—h  is  used  to  save  the  height 
parameter,  save_wthe  width  parameter,  save—ptr  the  address  in  screen  mem¬ 
ory  to  which  data  is  to  be  saved  or  restored,  save_s/'the  8088  si  register  that  is 
used  by  Forth  as  the  instruction  pointer,  and  save—ds  the  data  segment  in 
which  Forth  is  running. 

scn—>buf  x  y  width  height  seg  - 

Moves  memory  a  word  at  a  time  from  the  appropriate  position  in  the  screen 
memory  to  a  buffer  defined  by  the  seg  parameter.  Both  the  character  and  attri¬ 
bute  residing  on  the  screen  at  a  given  location  are  moved.  X  and  y  mark  the  up¬ 
per-left  corner  of  the  rectangle  to  be  moved. 

buf—  >scn  seg  x  y  width  height  - 

Moves  memory  a  word  at  a  time  from  a  buffer  in  memory  defined  by  (seg)  to  the 
appropriate  position  in  the  screen  memory.  Both  the  character  and  attribute 
stored  in  this  memory  buffer  are  moved.  X  and  y  mark  the  upper-left  comer  of 
the  rectangle  to  be  restored. 
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software  has  limited  BIOS/BDOS  sup¬ 
port  for  the  special  functions  re¬ 
quired.  Second,  assembly-language 
code  executes  faster  than  any  higher- 
level  language,  including  Forth. 

Three  different  levels  of  software 
interface  are  used  in  this  window 
package.  The  lowest  level,  which  in¬ 
volves  direct  manipulation  of  the  PC 
hardware,  includes  the  words 
buf—  >scn  and  sen  —  >buf.  Both  of 
these  Forth  words  read  and/or  write 
to  video  RAM  directly  while  saving 
and  restoring  of  the  display  is  taking 
place.  Because  of  their  direct  ma¬ 
nipulation  of  the  video  display,  these 
words  are  also  the  least  transport¬ 
able.  They  must  know  whether  they 
are  running  in  a  PC  that  has  only  a 
monochrome  monitor  or  one  with  a 
graphics  adapter.  This  is  done  by 
changing  the  value  of  the  constant 
v_seg  in  the  window  program  and 
recompiling.  The  correct  values  of 
v_seg  are  as  follows: 

color  graphic  adapter  v_seg  =  B800h 
monochrome  monitor  v_seg 

=  BOOOh 

The  constant  vseg  informs  both 
sen  —  >buf  and  buf—  >scn  of  where 
the  video  memory  begins,  and  they 
do  the  rest.  See  the  section  on  the  save 
and  restore  algorithm  for  specifics  on 
how  these  words  work. 

The  next  higher  level  of  software 
interface  to  the  PC  makes  use  of  the 
BIOS  routines.  In  this  program,  exten¬ 
sive  use  is  made  of  the  functions  pro¬ 
vided  by  the  video  BIOS  interrupt,  inf 
lOh.  The  video  functions  are  accessed 
by  placing  parameters  in  the  various 
8088  registers,  placing  a  function 
code  in  the  ah  register,  and  issuing 
the  inf  lOh  request.  Table  3,  page  SO, 
gives  a  summary  of  which  inf  lOh 
functions  are  used  and  where. 

When  using  the  BIOS  functions,  it’s 
important  to  save  any  registers  of 
special  significance  as  many  of  the 
BIOS  routines  alter  registers  during 
the  course  of  their  operation.  This 
version  of  Forth,  for  example,  uses 
the  8088  si  register  as  the  instruction 
pointer  and  the  bp  register  as  the  re¬ 
turn  stack  pointer.  These  registers, 
therefore,  must  be  saved  and  re¬ 
stored  after  any  BIOS  routines  that 


modify  them  are  used.  In  all  the  low- 
level  word  definitions  that  access  the 
BIOS  routines,  you'll  see  si  push  and  si 
pop  instructions  surrounding  the 
BIOS  interrupt  call.  You'll  also  find  a 
bp  push  and  bp  pop  in  the  scrlup 


word  definition  because  the  bp  regis¬ 
ter  is  modified  there. 

The  highest  level  of  software  inter¬ 
face  is  on  the  BDOS  level.  The  memo¬ 
ry  management  words  calloc,  free, 
and  setblock  are  examples  of  this 


case,  of,  endof,  and  endcase 

Dr.  Charles  Eaker’s  case  statement.  See  Forth  Dimensions,  vol.  II,  no.  3,  p.  37 
for  details  on  how  these  words  work. 

putch  x  y  char/attrib  - 

Writes  the  character  and  attribute  onto  the  video  display  screen  at  location  x,y. 
The  cursor  position  is  set  at  the  next  character. 

getch  x  y  -  char/attrib 

Returns  the  character  and  attribute  at  location  x,y  on  the  video  display  screen. 
The  cursor  is  moved  automatically  to  position  x,y. 

draw— row  x  y  char/attrib  count  - 

Displays  (count)  identical  characters  starting  at  the  position  on  the  video  display 
screen  defined  by  x,y. 

ulx,  uly,  width,  height,  curx,  cury, 

oldx,  oldy,  bufseg,  oldwcbseg,  attrib  -  n 

These  words  are  constants  that  define  the  positions  of  storage  locations  within 
the  current  window  control  block  (web).  When  executed,  they  return  offsets  rel¬ 
ative  to  the  start  of  the  web  storage  area.  (See  Table  7.) 

webseg!  n  addr  - 

Stores  information  into  the  active  web.  The  active  web  is  the  one  whose  seg¬ 
ment  address  is  in  the  variable  webseg.  For  example,  7  attrib  webseg!  would 
store  the  display  attribute  7  into  the  attrib  slot  in  the  active  window  control 
block.  The  attrib  word  supplies  the  address  in  which  to  store  the  display 
attribute. 

wcbseg@  addr  -  n 

Fetches  information  from  the  active  web.  For  example,  attrib  wcbseg@  would 
fetch  the  display  attribute  from  the  active  window  control  block  and  put  it  on  the 
parameter  stack. 

top,  sides,  bottom  ~ 

These  words  draw  the  actual  window  frame  on  the  display  screen.  When  exe¬ 
cuted,  they  draw  the  top,  sides,  and  bottom,  respectively,  of  the  window  speci¬ 
fied  in  the  active  web.  The  program  constant  border  shown  in  the  listing  is  used 
to  determine  the  attribute  with  which  to  draw  the  window  frame.  The  current 
version  sets  it  to  high-intensity  normal  video. 

((window)) 

This  is  the  lowest-level  window  routine.  It  automatically  fetches  from  the  current 
web  the  position  and  size  of  the  window  to  be  drawn  on  the  display,  copies  to 
the  appropriate  window  buffer  the  portion  of  the  display  screen  that  will  be 
overwritten  by  this  new  window,  and  then  draws  the  window  frame  by  invoking 
top,  sides,  and  bottom. 

dr— window 

Clears  the  current  window  by  fetching  all  the  appropriate  parameters  from  the 
web  and  invoking  scrlup  to  clear  the  entire  window.  It  then  sets  the  window  cur¬ 
sor  position  curx,  cury  to  Oto  home  the  cursor  in  the  window. 

(window)  x  y  width  height  attrib  -  f 

Builds  the  actual  window.  It  tries  to  allocate  enough  memory  to  hold  a  new  web 
(22  bytes).  If  successful,  it  links  this  new  web  into  the  web  linked  list  and  then 
tries  to  allocate  enough  memory  to  contain  the  screen  information  that  the  new 
window  will  overwrite.  If  this,  too,  is  successful,  all  the  parameters  passed  to 
this  routine  are  stored  in  the  new  web,  ((window))  is  called  to  draw  the  actual 
window,  and  a  true  flag  is  returned  to  the  calling  program  indicating  that  the 
creation  of  the  window  was  successful.  If  either  allocation  attempt  fails,  the 
memory  previously  allocated  is  freed  and  a  false  flag  is  returned  indicating  win- 


Table  2:  High-level  Forth  words 


Dr.  Dobb's  Journal,  July  1986 


48 

473 


BDOS  interface.  These  words  work  by 
loading  parameters  into  the  8088  reg¬ 
isters,  loading  a  function  code  into 
the  ah  register,  and  executing  int  21h. 
All  functions  provided  by  int  21h  save 
and  restore  all  registers  (except  those 


used  to  pass  back  parameters),  so  the 
precautions  used  for  the  BIOS  routine 
interface  aren't  required.  Table  4, 
page  50,  summarizes  memory  man¬ 
agement  functions  performed  via  the 
BDOS  interrupt. 


Forth  8088  Assembly 
Language 

Assembly  language  in  Forth  is  a  bit 
unusual.  The  first  conceptual  hurdle 
that  needs  to  be  overcome  involves 
the  reverse  Polish  or  postfix  notion 
used  throughout  the  assembly-lan¬ 
guage  definitions.  Assembly  lan¬ 
guage  written  in  this  manner  has  the 
operand(s)  preceding  the  mnemon¬ 
ics.  For  example,  the  standard  8088 
assembly-language  instruction  mov 
dh,dl,  where  dh  is  the  destination  and 
dl  is  the  source,  is  coded  in  Forth  as 
dh  dl  mov. 

Some  new  symbols  are  also  neces¬ 
sary  to  allow  the  Forth  assembler  to 
create  the  correct  instruction  se¬ 
quences.  Special  symbols  used  in  this 
program  are  #,  which  indicates  an 
immediate  operand,  and  #),  which  in¬ 
dicates  an  indirect  operand.  These 
symbols  are  sprinkled  liberally 
throughout  the  low-level  Forth  code 
words. 

A  few  other  special-purpose  Forth 
words  are  used  in  assembly-language 
definitions.  The  word  code  takes  the 
name  that  follows  it  and  creates  a 
new  dictionary  entry  for  the  code 
definition  to  follow  and  sets  up  cer¬ 
tain  pointers  for  Forth  so  that  this 
code  definition  can  be  executed  in  a 
manner  similiar  to  that  of  all  Forth 
definitions.  Code  also  tells  the  compil¬ 
er  to  reference  the  assembler  vocab¬ 
ulary  so  that  all  8088  mnemonics  that 
make  up  the  definitions  can  be  found 
in  the  dictionary  searches  and  assem¬ 
bled  into  the  code. 

The  word  next  (and  its  derivative 
lpush )  causes  a  direct  jump  back  to 
the  Forth  inner  interpreter.  This  re¬ 
stores  control  to  the  interpreter, 
which  then  passes  control  to  the  next 
Forth  word  in  the  program.  Writing 
a  code  definition  and  forgetting  to 
have  next  or  lpush  as  the  final  state¬ 
ment  (before  end-code)  will  cause 
your  computer  to  crash  right  after 
the  word  is  executed. 

The  word  lpush  performs  the 
same  function  as  next  does,  except  it 
pushes  the  contents  of  the  8088  ay 
register  onto  the  parameter  stack  be¬ 
fore  returning  to  the  inner  interpret¬ 
er.  In  this  way,  parameters  can  be 
passed  back  via  the  stack  to  subse¬ 
quent  high-level  Forth  definitions. 

The  final  word  end-code  changes 
the  vocabulary  back  to  Forth  (from 
assembler),  performs  a  limited 


dow  creation  failure.  Under  these  conditions,  an  error  message  will  be  dis¬ 
played  to  help  the  programmer  find  the  source  of  the  problem.  In  most  cases  a 
failure  indicates  lack  of  available  memory. 

open— window  x  y  width  height  attrib  -  f 

This  is  the  highest-level  window  word.  Its  function  is  to  perform  checking  on  the 
specified  window  parameters  to  verify  validity.  If  the  specified  window  wouldn’t 
fit  on  the  display  screen,  an  appropriate  error  message  will  be  displayed.  Anoth¬ 
er  error  message  will  be  displayed  if  the  proper  parameters  are  not  present  on 
the  parameter  stack.  This  word  will  not  allow  the  programmer  to  create  a  win¬ 
dow  that  cannot  be  displayed  on  the  screen  correctly. 

close— window  - 

Closes  the  current  window.  A  window  is  closed  by  moving  the  screen  data 
stored  in  the  memory  buffer  back  onto  the  display  screen,  then  freeing  the 
memory  allocated  to  both  the  web  and  the  memory  buffer.  Next,  the  cursor  is 
returned  to  where  it  was  before  this  window  was  opened,  and  then  the  web  is 
removed  from  the  web  linked  list.  If  no  windows  are  currently  open,  execution 
of  this  routine  will  result  in  an  error  message. 

wat  x  y  - 

This  routine  (pronounced  “window  at”)  places  the  cursor  in  the  window  at  the 
location  specified  by  the  x,y  coordinates.  These  coordinates  are  relative  to  the 
current  window,  not  the  whole  display  screen.  If  either  coordinate  exceeds  the 
size  of  the  current  window,  the  cursor  will  be  placed  as  close  as  possible  to  the 
position  specified  without  leaving  the  window. 

rdwcur  -  x  y 

Returns  the  cursor  position  relative  to  the  current  window. 
rdwcha  x  y  -  char/attrib 

Returns  the  character  and  attribute  found  under  the  current  window’s  cursor. 
scroll— window  - 

Scrolls  the  current  window  up  by  one  line  to  allow  new  information  to  be  dis¬ 
played.  This  word  gets  all  the  parameters  it  needs  from  the  web.  The  attributes 
used  for  the  blank  line  scrolled  onto  the  display  are  the  same  as  those  specified 
when  the  window  was  created. 

crout,  Ifout,  bsout,  bell 

These  words  perform,  in  the  current  window,  the  same  function  as  they  would 
perform  if  issued  to  the  normal  screen.  Namely,  they  return  the  cursor  to  the 
first  character  position  of  the  current  line,  move  the  cursor  down  one  line,  back 
the  cursor  up  by  one  character  position,  and  cause  the  computer  to  ring  its 
chimes,  respectively.  Special  versions  of  these  functions  are  required  to  keep 
the  cursor  within  the  window. 

wemit  char  — 

This  word  (pronounced  "window  emit”)  is  the  equivalent  of  the  Forth  word 
emit.  It  should  be  used  only  when  writing  information  to  windows.  In  addition  to 
sending  normal  characters  to  the  display  window,  it  performs  the  cr,  If,  bs,  and 
bell  functions  as  described  above.  If  a  line  feed  (If)  character  code  is  issued 
while  the  window  cursor  is  on  the  last  line  of  the  window,  wemit  will  scroll  up  all 
the  information  in  the  window  accordingly. 

initialize 

Sets  up  the  MS-DOS  memory  management  function.  It  requests  a  full  64K  seg¬ 
ment  for  the  Forth  system  currently  running.  If  this  initialization  is  successful,  an 
appropriate  message  is  displayed  and  the  webseg  variable  is  set  to  0,  indicat¬ 
ing  that  no  windows  are  currently  active.  If  there  wasn’t  enough  memory,  an  er¬ 
ror  message  is  displayed  and  the  window  program  is  completely  aborted. 
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amount  of  error  checking  on  the 
code  definition,  makes  this  new 
word  visible  in  the  dictionary,  and 
then  terminates  the  assembly-lan¬ 
guage  word  definition. 

From  the  listing  you  can  see  how 
easily  assembly-language  word  defi¬ 
nitions  can  be  integrated  into  a  high- 
level  Forth  program.  From  my  expe¬ 
rience  with  in-line  code  written  in 
any  computer  language,  the  follow¬ 
ing  rules  apply: 

•  Use  in-line  code  only  when  speed  of 
execution  is  required. 

•Keep  the  definitions  as  small  as  is 
practical.  This  will  aid  in  debugging 
and  maintenance. 

•  Code  carefully;  errors  in  in-line 
code  can  send  your  computer  on  a 
journey  from  which  it  will  never  re¬ 
turn  except  via  reboot. 

Screen  Save  and  Restore 
Algorithm 

The  screen  save  and  restore  algo¬ 
rithm  was  developed  to  keep  to  a 
minimum  the  number  of  calcula¬ 
tions  necessary  to  locate  the  correct 
screen  data  and  move  it  to/from  buff¬ 
ers  allocated  for  its  storage.  Minimal 
calculations  result  in  the  fastest  possi¬ 
ble  execution  of  the  windows. 

All  moves  of  data  to  or  from  the 
screen  and  buffers  are  word  moves 
because  the  character  and  attribute 
for  a  screen  character  are  stored  in 
sequential  bytes  of  screen  memory. 
Character  data  is  stored  at  even  ad¬ 
dresses,  and  attribute  data  is  stored  at 
odd  addresses.  When  a  word  is 
fetched  from  an  even  addess  in  screen 
memory,  the  high  byte  contains  the 
attribute  and  the  low  byte  contains 
the  actual  character.  For  the  same  rea¬ 
son,  sequential  lines  on  the  video  dis¬ 
play  are  offset  not  by  80  bytes  but 
rather  by  160  bytes.  This  fact  is  impor¬ 
tant  whenever  data  is  moved  to  or 
from  the  PC  screen  and  is  taken  into 
consideration  by  the  sen  —  >buf  and 
buf—  >scn  word  definitions. 

A  program  design  language  (PDL) 
representation  of  the  data  movement 
algorithm  is  shown  in  Table  5,  right. 
The  start  address  of  the  video  data 
needs  to  be  calculated  only  once  be¬ 
fore  the  nested  loops  actually  per¬ 
form  the  work  of  moving  the  data. 


The  8088  block-move  word  instruc¬ 
tions  make  the  data  movement  from 
screen  memory  to  buffer  and  from 
buffer  back  to  screen  memory  a  triv¬ 
ial  task.  The  incrementing  of  the 
pointers  shown  in  the  PDL  is  handled 
automatically  by  specifying  block- 
move  word  instructions.  For  both  di¬ 
rections  of  data  movement,  the  ds:si 
register  pair  points  at  the  source  of 
the  data  to  move,  and  the  es:di  regis¬ 
ter  pair  points  at  the  destination.  Both 
si  and  di  increment  automatically  by 
2  for  movement  of  word-size  data. 

Windows  in  Your  Programs 

Interfacing  windows  with  your  appli¬ 


cation  program  is  relatively  straight¬ 
forward  once  you  understand  how 
the  window  package  works.  Once 
you  have  compiled  the  package,  you 
can  create  windows  interactively  to 
see  how  they  work  before  trying  to 
use  them  in  your  program.  For  exam¬ 
ple,  typing  the  commands 

initialize  0  0  20  10  7  open_window 

at  the  keyboard  will  immediately 
create  a  window  with  its  upper-left 
corner  at  0,0;  a  width  of  20  charac¬ 
ters;  and  a  height  of  10  vertical  lines. 
(Width  and  height  are  inside  dimen¬ 
sions  of  the  windowed  area;  the  bor- 


Function 

Function  Code 

Used  in  Forth  Word(s) 

write  char  with  attribute 

9 

chra,  chra+ 

get  cursor  position 

3 

chra+,  rdcur 

set  cursor  position 

2 

chra  + 

read  char  and  attribute 

8 

rdchra 

scroll  up  video  window 

6 

scrlup 

Table  3:  Summary  of  int  lOh  functions 


Function 

Function  Code 

Used  in  Forth  Word 

allocate  memory  block 

48h 

calloc 

release  a  memory  block 

49h 

free 

resize  an  allocated  block 

4ah 

setblock 

Table  4:  Memory  management  functions  performed  via  the  BDOS  interrupt 


procedure  sen— > buf  parameters  are  x,  y,  width,  height  and  buf  seg 
begin 

set  data  movement  direction  to  forward 
get  buffer  segment  address  into  the  extra  segment  reg. 
initialize  destination  ptr  DI  to  0  which  points  at  the  first  byte  of  buffer  storage 
in  the  buffer  segment. 

save  the  height  parameter  in  temporary  storage 
save  the  width  parameter  in  temporary  storage 
get  y  coordinate  of  first  location  to  store 
multiply  by  160  to  find  line  start  address 
get  x  coordinate  of  first  location  to  store 
multiply  by  2  to  find  character  address  offset 
add  new  x  and  new  y  to  get  start  address  of  data  move 
save  result  in  a  temporary  location  called  save— ptr 
save  the  current  value  of  the  SI  register  in  a  safe  place 
save  the  current  value  of  the  DS  register  in  a  safe  place 
move  video  segment  address  vseg  into  the  DS  register 
do  height  times 
do  width  times 

move  DS:SI  to  ES:DI  (move  actual  data) 
increment  SI  and  DI  both  by  2  for  word  moves 
enddo 

save— ptr  =  save— ptr  +160  (move  down  1  vertical  line) 
enddo 

restore  previous  DS  register  value 
restore  previous  SI  register  value 
jump  to  next  (back  to  inner  interpreter) 
end 


Table  5:  PDL  representation  for  the  data  movement  algorithm 
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der  of  the  window  will  take  up  two 
more  characters  horizontally  and 
two  lines  vertically.)  The  attribute 
code  of  7  will  create  the  window  us¬ 
ing  normal,  low-intensity  video.  Re¬ 
member,  the  word  initialize  is  need¬ 
ed  to  set  up  the  MS-DOS  memory 
manager.  If  initialize  is  not  executed 
before  the  open— window  request,  the 
request  will  fail. 

Once  a  window  is  opened,  you  can 
move  the  window’s  cursor  to  any  po¬ 
sition  by  using  the  word  wat  (the  win¬ 
dow  counterpart  of  the  Forth  word 
at).  You  can  write  text  into  the  win¬ 
dow  using  wemit  and  wtype  (the  win¬ 
dow  counterparts  of  emit  and  type). 
The  special  video  control  codes 
shown  in  Table  6,  below,  are  also  sup¬ 
ported  via  wemit.  Note  that  by  rede¬ 
fining  the  F83  deferred  word  emit  to 
wemit,  you  can  get  Forth  to  run  in 
one  of  its  own  windows. 

All  words  that  write  text  into  a 
window  (such  as  wemit )  always  work 
on  the  currently  selected  window 
only  [the  window  at  the  end  of  the 
window  control  block  (web)  linked 
list  whose  web  address  is  contained 
in  the  Forth  variable  webseg]  Thus, 
continuing  with  the  example,  if  you 
were  to  open  a  second  window,  we¬ 
mit  would  then  automatically  write 
to  this  new  window.  The  previous 
window  could  not  be  written  to 
again  until  the  new  window  was 
closed.  The  Forth  word  close— win¬ 
dow  closes  the  current  window  and 


reopens  the  previous  window  if  one 
exists.  If  close— window  is  executed 
when  no  windows  are  open,  an  error 
message  is  displayed.  A  window  that 
is  closed  erases  itself  from  the  screen 
(by  restoring  the  screen  data  that  it 
covered  up),  frees  the  memory  it  had 
allocated  for  the  window  control 
block  and  the  screen  buffer,  and  fi¬ 
nally  unlinks  itself  from  the  web  list. 
Table  7,  below,  shows  the  structure 
of  an  entry  in  the  web  list. 

The  demo  program  in  the  listing  is 
an  example  of  how  an  application 
program  can  be  integrated  with  the 
basic  window  package.  It  demon¬ 
strates  opening  windows  using  vari¬ 
ous  attributes,  writing  text  to  the 
windows,  using  the  special  video 
control  codes,  listing  Forth  screens  in 
a  window,  linking  overlapping  win¬ 
dows,  clearing  windows,  and  closing 
them.  It  illustrates  how  easy  to  use 
and  how  fast  the  windows  can  be. 

DDJ 

(Listing  begins  on  page  96.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  8. 


Video  Code 

Function 

7 

Ring  the  PC’s  bell 

8 

Backspace  the  window  cursor 

10 

Linefeed  (scroll  upwards  if  necessary) 

13 

Carriage  return 

Table  G:  Video  control  codes 

Displacement 

Name 

Description 

+  0 

ulx 

X  coordinate  of  upper  left  corner 

+  2 

uly 

Y  coordinate  of  upper  left  corner 

+  4 

width 

Width  of  the  window 

+  6 

height 

Height  of  the  window 

+  8 

curx 

Window— relative  cursor  position 

+  10 

cury 

Window — relative  cursor  position 

+  12 

oldx 

Cursor  position  in  previous  window 

+  14 

oldy 

Cursor  position  in  previous  window 

+  16 

bufseg 

Points  to  window’s  text  buffer 

+  18 

oldwcb 

Points  to  previous  web  record 
(NIL  for  last  record) 

+  20 

wattrib 

Window’s  text  attribute  byte 

Table  7:  Structure  of  an  entry  in  the  window  control  block  list 
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Listing  Five  (continued  from  June) 


include 

\lc\dos.mac 

dseg 

Timer 

01d_Second 

endds 

dw  ? 

db  ? 

pseg 

public 

Start_Timer 

Start_Timer  proc 
push 
mov 

mov 

mov 

mov 

int 

mov 

pop 

ret 

Start_Timer  endp 

BP 

BP,  SP 

AX, [BP+4] 

Timer, AX 

AX, 2C00H 

21H 

Old  Second, DH 

BP 

;  Get  the  number  of  seconds 

;  Get  current  time 

public 

Timer_Expired 

Timer_Expired  proc 
mov 
int 
anp 

je 

mov 

dec 

anp 

jle 

AX, 2C00H 

21H 

DH, 01d_Second 

Timer  Expired  1 

Old  Second, DH 

Timer 

Timer,  0 

Timer  Expired_2 

;  Get  current  time 
;  Has  the  clock  ticked? 

;  No 

;  Yes,  update  01d_Second 

;  Timer  expired? 

Timer_Expired_l : 
xor 

ret 

AX,  AX 

;  No, 

return  "false" 

Timer_Expired_2 : 
mov 

AX,  1 

;  Yes, 

,  return  "true" 

ret 

Timer_Expired  endp 
endps 

end  End  Listing  Five 


Listing  Six 

# define  Loops_Per_Millisecond  9 

Delay  (N) 

/** 

*  Delay  for  N  milliseconds 
**/ 

int  N; 

{ 

long  K; 

for  (K  =  Loops_Per_Millisecond  *  (long)  N;  K  >  0;  K — ); 

)  End  Listing  Six 


Listing  Seven 


page  57,132 

title  FilelO 

++ 

FACILITY:  DTE 
ABSTRACT: 

This  module  contains  the  interface  routines  to  the  MS-DOS  file 
service.  All  disk  operations  are  done  thru  this  module. 

ENVIRONMENT:  MS-DOS,  V2.0  or  later 

AUTHOR:  Steve  Wilhite,  CREATION  DATE:  8-May-85 

REVISION  HISTORY: 


include  \lc\dos.mac 
pseg 
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@ab  =  4 

;  argument  base 

page 

public 

Create_File 

Create  File  proc  near 

;  + 

Functional  Description: 

Creates  c 

new  file  or  truncates  an  old  to  zero  length  in 

preparation  for  writing. 

Calling  Sequence 

handle  = 

Create_File (pathname,  attribute) 

Parameters: 

pathname 

ptr  to  ASCIZ  pathname 

attribute 

file  attribute (s) 

Return  Value: 

-5 

access  denied 

-4 

too  many  open  files 

-3 

path  not  found 

else 

file  handle  number 

Pathname  equ 

@ab[BP] 

Attribute  equ 

@ab+2[BP] 

push 

BP 

mov 

BP,  SP 

mov 

DX,  Pathname 

mov 

CX,  Attribute 

mov 

AH, 3CH 

int 

21H 

jnc 

Create  1 

neg 

AX 

Create  1: 

pop 

BP 

ret 

Create  File  endp 

page 

public 

Open_File 

(}pen  File  proc 

near 

■  + 

Functional  Description: 

Opens  a  file. 

Calling  Sequence: 

handle  = 

Open_File (pathname,  access) 

Parameters : 

pathname 

ptr  to  ASCIZ  pathname 

access 

access  code  (0  =  read,  1  =  write,  2  =  read  and  write) 

Return  Value: 

-12 

invalid  access 

-5 

access  denied 

-4 

too  many  open  files 

-2 

file  not  found 

>0 

file  handle  number 

Access 

equ  @abf2  [BP] 

push 

BP 

mov 

BP,  SP 

mov 

AH,3DH 

mov 

DX, Pathname 

mov 

AL, Access 

int 

21H 

jnc 

Open  1 

neg 

AX 

Open  1 :  pop 

BP 

ret 

Open  File  endp 

page 

public 

Close  File 

Close  File  proc 

near 

+ 

Functional  Description: 

Closes  the  file  associated  with  a  specified  file  handle. 

Calling  Sequence: 

status  =  Close_File (handle) 

Parameters : 

handle 

file  handle  for  file  to  close 
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UStinQ  Seven  (listing  continued) 

Return  Value: 

-6 

invalid  handle 

0 

no  error 

H 

andle 

equ  @ab[BP] 

push 

BP 

mov 

BP,  SP 

mov 

AH, 3EH 

mov 

BX, Handle 

int 

21H 

jnc 

Close  1 

neg 

AX 

jmp 

Close  2 

Close  1: 

mov 

AX,  0 

Close  2: 

pop 

BP 

ret 

Close  File  endp 

page 

public 

Read_File 

ReadJFile  proc 

near 

Functional  Description: 

Transfers 

a  specified  number  of  bytes  from  a  file  into  a  buffer 

location. 

If  the  returned  value  for  number  of  bytes  read  is 

zero,  then  the  program  tried  to  read  from  the  end  of  file. 

Calling  Sequence 

bytes  read  =  Read_File (handle,  buffer,  bytes_to_read) 

Parameters : 

handle 

file  handle  for  the  file  to  read 

buffer 

ptr  to  buffer 

bytes  to_ 

read  number  of  bytes  to  read 

Return  Value: 

-6 

invalid  handle 

-5 

access  denied 

0 

end  of  file 

>0 

number  of  bytes  actually  read 

Buffer 

equ  @ab+2[BP] 

Count 

equ  @ab+4[BP] 

push 

BP 

mov 

BP,  SP 

mov 

AH, 3FH 

mov 

BX, Handle 

mov 

CX,  Count 

mov 

DX, Buffer 

int 

21H 

jnc 

Read  1 

neg 

AX 

Read  1 :  pop 

BP 

ret 

Read  File  endp 

page 

public 

Write_File 

WriteJFile  proc 

near 

Functional  Description: 

Transfers  a  specified  number  of  bytes  from  a  buffer  into  a  file. 

If  the  number  of  bytes  written  is  not  the  same  as  the  number 

requested,  then  an  error  has  occurred. 

Calling  Sequence 

status  « 

Write_File (handle,  buffer,  bytes_to_write) 

Parameters : 

handle 

file  handle  for  file  to  write 

buffer 

ptr  to  buffer 

bytes  to 

_write  number  of  bytes  to  write 

Return  Value: 

-6 

invalid  handle 

-5 

access  denied 

else 

number  of  bytes  written 

push 

BP 

mov 

BP,  SP 
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mov 

AH, 40H 

mov 

BX, Handle 

mov 

CX, Count 

mov 

DX, Buffer 

int 

21H 

jnc 

Write  1 

neg 

AX 

Write  1: 

pop 

BP 

ret 

Write_File  endp 

public 

Move_To  EOF 

Move  To  EOF  proc 

push 

BP 

mov 

BP,  SP 

mov 

AX, 4202H 

mov 

BX,  4 [BP] 

;  file  handle 

xor 

cx,cx 

xor 

DX,  DX 

int 

21H 

pop 

BP 

ret 

Move_To_EOF  endp 

endps 

end 

End  Listing  Seven 

Listing  Eight 

Title 

Serial 

include 

pseg 

\lc\dos.mac 

•  + 

Table  of  Contents: 

oublic  Qpen  Modem 

public  Read  Modem 

public  Write_Modem 

public  Close  Modem 

public  Send_Break 

dseg 

Comm  Params  equ  this  byte 

db 

11H 

;  XON 

db 

13H 

;  XOFF 

db 

? 

;  Baud  rate  code 

db 

0 

;  Parity  =  none 

db 

1 

;  Word  length  =  8 

db 

endds 

0 

;  stop  bits  =  1 

extrn 

AS  Init:near 

;  Initialize 

extrn 

AS  Set  Mode: near 

Set  XON/XOFF  mode 

extrn 

AS  Set  Port: near 

Initialize  the  port 

extrn 

AS  Open: near 

;  Open  the  port 

extrn 

AS  I Ready: near 

;  Test  input  status 

extrn 

AS  IChar:near 

;  Input  character 

extrn 

AS  OReady:near 

;  Test  output  status 

extrn 

AS  OChar:near 

;  Output  character 

extrn 

AS  Send  Break: near 

Send  a  break  signal 

extrn 

AS  Oldie: near 

;  Test  output  idle  status 

extrn 

AS  Close: near 

;  Close  the  comm  port 

extrn 

AS_Term:near 

;  Terminate  async  I/O 

+ 

Function: 

Open  the 

comm  port. 

Calling  Sequence 

Open_Modem  (Port ,  Rate,  Auto  XOFF) 

Parameters: 

Port :  0  = 

com,  l  =  COM2 

Rate: 

0  110  baud 

1  300 

2  450 

3  1200 

4  1800 

5  2400 

6  4800 

7  9600 

Auto_XOFF 

:  if  true,  enable  auto  XOFF/XON  flow-of-control 

3pen  Modem  proc 

push 

BP 

mov 

BP,  SP 

mov 

AX, 4 [BP] 

Get  port  number 
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Listing  Eight  (listing  continued) 


AS_Init 
AX,  8  [BP] 
AX,  0 
Init_l 
AX,  3 


;  Initialize  async 
;  Get  XOFF/XON  flags 


Open_Modem  endp 


AS_Set_Mode  ;  Set  them 

AL, 6 [BP]  ;  Get  baud  rate  code 

Comm_Params[2]  ,AL  ;  and  store 
SI, offset  Conm_Params 

AS_Set_Port  ;  Initialize  the  port 

AS_Open  ;  Open  the  comm  port 

BP 


Function: 

Read  a  character  from  the  corrm  port. 
Calling  Sequence: 

ret  value  =  Read  Modem  () 


-1  if  no  character  is  available;  otherwise  the  character. 


Read_Modem  proc 

call  AS_IReady 

anp  AX, -1 

jne  Read_l 

ret 


;  Test  input  status 
;  Ready? 

;  Yes 

;  No,  return  -1 


Read_l : 

call 

mov 

ret 

Read_Modem  endp 


AS_IChar 
AH,  0 


;  Input  character 


Function: 

Write  a  character  to  the  comm  port. 
Calling  Sequence: 

status  =  Write_Modem(Char) 


0  if  could  not  send  the  character;  otherwise  -1 


Write_Modem  proc 
push 
mov 
call 
not 
cmp 

je 

mov 

call 


BP 

BP,  SP 
AS_OReady 
AX 
AX,  0 
Write_l 
AX,  [BP+4] 
AS_OChar 
AX,  -1 


;  Test  output  status 
;  Ready? 

;  No,  return  failure 
;  Get  character  to  send 
;  Send  it 

;  Success 


Write_l: 

pop 

ret 

Write_Modem  endp 


Function: 

Close  the  comm  port. 
Calling  Sequence: 

status  =  Close  Modem () 


;  Returns: 

Close_Modem  proc 
Close_l : 

call 

anp 

jne 

call 

call 

ret 

Close_Modem  endp 


AS_OIdle 
AX,  0 
Close_l 
AS_Close 
AS  Term 


;  Test  output  idle  status 
;  Done? 

;  No 


Function: 

Send  a  break  "character"  to  the  corrm  port. 
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;  Calling  Sequence 

;  Send_Break  () ; 

Send_Break  proc 
mov 
call 
ret 

Send_Break  endp 

AX, 50  ;  milliseconds 

AS_Send  Break 

endps 

end 

End  Listing  Eight 

Listing  Nine 

title 

include 

pseg 

Break 

\lc\dos.mac 

public 

Set_Break,  Get_Break 

Set_Break  proc 
push 
mov 

mov 

mov 

int 

pop 

ret 

Set_Break  endp 

BP 

BP,  SP 

DL,  4  [BP]  ;  Get  state  to  set 

AX, 3301H 

21H 

BP 

Get_Break  proc 
mov 
int 
mov 

xor 

ret 

Get_Break  endp 

AX, 3300H 

21H 

AL,  DL 

AH,  AH 

endps 

end 

End  Listings 
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Listing  One  (Text  begins  on  page  8.) 

/Listing  1  -  Square  root  algorithm  plus  code  to  benchmark  and  test  it. 
INT_ROOT  SEGMENT 

ASSUME  CS:INT  ROOT 


CAI£  ROOT  PROC  NEAR 


/  Argument  passed 

in  BX. 

/  Root  returned  in 

BX. 

/  All  registers  except  BX  preserved. 

' 

PUSH 

AX 

PUSH 

CX 

MOV 

AX,  BX 

/Hold  argument  in  AX. 

OR 

BH,  BH 

JNZ 

GE  256 

CMP 

BL,  1 

/If  arg  is  zero  or  one, 

JBE 

GOT  ROOT 

/then  root  -  argument. 

MOV 

CL,  4 

/If  2  <=  argument  o  255 

SHR 

BL,  CL 

/then  guess  =  3  +  arg/16. 

ADD 

BL,  3 

JMP  SHORT 

NEWTON 

GE  256: 

MOV 

BL,  BH 

MOV 

BH,  0 

JS 

GE  32768 

CMP 

BL,  16 

JAE 

GE  4096 

SHL 

BL,  1 

/If  256  <-  argument  o  4095 

SHL 

BL,  1 

/then  guess-13+4* (arg  hi  byte). 

ADD 

BL,  13 

JMP  SHORT 

NEWTON 

GE  4096:  ADD 

BL,  50 

;If  4096  o  argument  o  32767 

JMP  SHORT 

NEWTON 

/then  guess  -  50  +  arg  hi  byte 

GE  32768:  CMP 

BL, 255 

/If  arg 

hi  byte-255  then  root-255. 

JZ 

GOT  ROOT 

/This  prevents  ovflow  by  DIV. 

ADD 

BL,  40 

/If  32768  O  argument  <-  65279 

JNC 

NEWTON 

/then  guess  -  40  +  arg  hi  byte. 

MOV 

BL, 255 

/Guess  must  never  exceed  255. 

NEWTON: 

MOV 

CX,  AX 

/Save  argument  in  CX. 

DIV 

BL 

/Divide  by  guess. 

ADD 

BL,  AL 

/Guess  +  quotient. 

RCR 

BL,  1 

/New  guess- (old  guess+quot) /2. 

MOV 

AL,BL 

/RCR  shifts  in  carry  from  ADD./ 

MUL 

AL 

/If  the  square  of  the  new  guess 

CMP 

AX,  CX 

/is  greater  than  the  argument. 

JBE 

GOT  ROOT 

/then  we  decrement  new  guess 

DEC 

BX 

/to  get  the  correct  root. 

GOT  ROOT:  POP 

CX 

POP 

AX 

RET 

CALC_ROOT  ENDP 
/Listing  1  -  Continued. 

/  Code  to  time  and  test  CALC_ROOT  is  designed  to  be  run  under 
/  DEBUG  and  does  not  do  a  normal  return  to  DOS  but  instead 
;  does  an  INT  3  at  the  end  of  each  routine. 


TIME  PROC  FAR 


TIME_ROOT  computes  the  root  of  each  of  65536  possible 
arguments  15  times  for  a  total  of  983,040  roots. 
TIME_OVER  represents  the  looping  overhead  in  TIME_ROOT. 
The  difference  between  the  two  times  is  the  time  to  call 
and  execute  CALC  ROOT. 


' 

MOV 

BP, 15 

TIME  OVER: 

MOV 

SI,0 

/Initial  value. 

INNER_OVR: 

MOV 

BX,  SI 

INC 

SI 

JNZ 

INNER  OVR 

DEC 

BP 

JNZ 

TIMEJ0VER 

END_OVER:  MOV 

AH,  2 

MOV 

DL,  7 

/Beep  speaker. 

INT 

21H 

INT 

3 

’ 

MOV 

BP,  15 

TIME  ROOT: 

MOV 

SI,0 

/Initial  value. 

INNR_R0OT: 

MOV 

BX,  SI 

CALL 

CALC  ROOT 

INC 

SI 

JNZ 

INNR. ROOT 

DEC 

BP 

JNZ 

TIME_ROOT 

END_TIME :  MOV 

AH.  2 

MOV 

DL,  7 

/Beep  speaker. 

INT 

21H 

INT 

3 

TIME 

ENDP 

(continued  on  page  62) 
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Listing  One  (Listing  continued,  text  begins  on  page  8.) 


/Listing  1  -  Continued. 

TEST  PROC  FAR 


;  If  CHKROOT  detects  a  bad  root#  it  displays  a  message  and 
;  leaves  the  NG  root  in  BX  and  the  argument  in  SI. 

;  If  all  roots  are  OK,  a  message  to  this  effect  is  displayed. 


• 

MOV 

SI,0 

/Initial  value. 

CHK  ROOT:  MOV 

BX,  SI 

CALL 

CA1£  ROOT 

MOV 

AX,  BX 

MUL 

AX 

/DX,AX  contains  rootA2. 

JO 

NG  ROOT 

/NG  if  root  A2  >  65535. 

CMP 

AX,  SI 

JA 

NG  ROOT 

/NG  if  root A 2  >  argument. 

MOV 

AX,  BX 

INC 

AX 

MUL 

AX 

/ DX, AX  contains  (root+l)A2. 

JO 

NEXT  ARG  /If  ovf low  then  OK. 

CMP 

AX,  SI 

JBE 

NG  ROOT 

/NG  if  (root+l)A2  <~argument. 

NEXT  ARG:  INC 

SI 

JNZ 

CHK  ROOT 

JMP  SHORT 

OK_ROOTS 

OK  MSG  DB  0DH,0AH, 'All  roots  tested  OK.' 

,  0DH,  0AH,  '$' 

NG_MSG  DB  0DH, 

0AH,  'Bad  root  in  BX.  Arg  in 

SI . ' , 0DH, 0AH, 

OK  ROOTS/  MOV 

DX,  OFFSET 

OK  MSG+100H 

/DS  points  to  Pgm  Seg 

JMP  SHORT 

DO  MSG 

/Pref  which  is  100H 

NG_ROOT :  MOV 

DX, OFFSET 

NG_MSG+100H 

/lower  than  code  seg. 

DO  MSG: 

MOV 

AH,  9 

/Print  string. 

INT 

INT  3 

21H 

/Back  to  DEBUG. 

TEST 

ENDP 

INT_ROOT  ENDS 

END 

TEST 

End  Listing  One 

Listing  Two 


/Listing  2  -  BASIC  program  to  test  if  a  formula  makes  good  square  root  guesses. 

10  FOR  I  -  2  TO  256 
20  Q  -  1*1  -  1 
30  ' 

40  'Trial  Formula  to  Calculate  P0. 

50  ' 

60  QHI  -  INT  (Q/256)  :  QLO  -  Q-QHI*256 

70  IF  QHI  -  0  THEN  P0  -  INT(QLO/32)  +  3:  GOTO  160 

80  IF  QHI  <  16  THEN  P0  -  13  +  4*QHI:  GOTO  160 

90  IF  QHI  <  128  THEN  P0  “  QHI  +  50/  GOTO  160 

100  IF  QHI  -  255  THEN  PI  -  255:  GOTO  210 

110  P0  -  QHI  +  40 

120  IF  P0  >  255  THEN  P0  -  255 

130  ' 

140  '  Newtons  Method 
150  ' 

160  Pl-INT  ( (P0  +  INT  (Q  /  P0)  )  /  2) 

170  IF  PI  >  255  THEN  PRINT  "PI  >  255  when  Q  =  " / Q : END 
180  ' 

190  'Test  result 
200  * 

210  P  -  INT(SQR  (Q) ) 

220  IF  PI  <-  P+1  GOTO  240 

230  PRINT  "For  Q  -  "/Q/“  PI  is  greater  than  P+1.  " : END 

240  NEXT  I  j  .  . 

250  PRINT  "Formula  works  for  all  worst  cases."  End  Listing  Two 

Listing  Three 

Listing  Three 


INCLUDE  MACLIB.ASM 
LIST  ON 
MAC  LI  ST  OFF 

/SQR.ASM 


/by  Neil  R.  Koozer 
/  Kellogg  Star  Rt .  Box  125 

/  Oakland,  OR  97462 
(503) -459-3709 


/Note  that  words  like  BR1  and  BFS1  are  macros  to  emulate  BR:B  and  BFS:B 


GLOBAL  SQR 


SQR 

RESTORE  [R0] 
MOVD  0 ( R0 ) , R1 
MOVD  0 (Rl) ,R6 
MOVD  4  (Rl)  ,R7 
SBITB  31,  R7 


/square  root  function  for  32000  floating  point 
/use  ret.  addr  as  a  pointer 
/get  operand  address 
/get  part  of  operand 
/get  other  part  of  operand 

/make  the  implicit  l  explicit  (continued  on  page  66) 
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LETTERS 

LiStinQ  Thre©  (Listing  continued,  text  begins  on  page  8.) 

MOVD  R6,  R1 

/get  exponent 

ANDW  7FFH, R1 

/clean  exponent 

ADDW  3FFH,R1 

/fix  offset 

ROTW  -1 ,  RI 

;div  exp  by  2 

CBITB  15,  Rl 

/test  4  clear  wrap-around  bit,  l=odd  0-even 

SAVE  [R0,R1] 

/save  exp  4  ret  addr 

MOVB  R7,R6 

/prepare  for  right  shift 

BFS1  SQR1 

/  junp  if  exponent  was  odd 

LSHD  -4, R7 

/shift  -3  for  safety  4  -1  to  get  lialfx 

ROTD  -4,  R6 

ANDW  FF80H, R6 

/remove  non-mantissa  bits 

MOVD  4C1BF820H,  R3 

/y  seed  -  1.189 _ /2 

BR1  SQR2 

SQR1 

LSHD  -3,  R7 

/shift  -3  for  safety,  -1  to  get  halfx,  +1  because 

ROTD  -3, R6 

;  orig  exp  was  odd 

ANDW  FFOOH, R6 

/remove  non-mantissa  bits 

MOVD  6A227E65H, R3 

/y  seed  -  1.68.../2 

SQR2 

/We  will  do  3  iterations  with  32-bit  precision 

MOVD  R7,R5 

/get  halfx  into  R5 

DEID  R3,R4 

/R5  -  halfx/yO  (the  junk  in  R4  doesn't  matter) 

LSHD  -1,  R3 

/R3  -  yO/2 

ADD D  R5,R3 

/  R3  -  new  yO 

MOVD  R7,R5 

/second  iteration 

DEID  R3,R4 

LSHD  -1, R3 

ADDD  R5,R3 

MOVD  R7,R5 

/third  iteration 

DEID  R3,R4 

LSHD  -1#R3 

ADDD  R5,R3 

MOVD  R6,R4 

/Now  the  final  iteration  at  full  precision 

MOVD  R7,R5 

/get  R4R5  -  halfx  frcm  R6R7 

DEID  R3,R4 

/now  divide  halfx  (R4R5)  by  y  (R2R3) 

MOVD  R2,R0 

MEID  R5,R0 

NEGD  RO,  RO 

SUBCD  Rl ,  R4 

MOVD  R4,  Rl 

BCC1  DIV1 

DTV2 

ADDQD  -1 , R5 

ADDD  R2, RO 

ADDCD  R3,  Rl 

BCC  DIV2 

DIV1 

DEID  R3,  RO 

MOVD  Rl,  R4 

/R4R5  now  -  halfx  /  y 

MOVB  R3,R2 

LSHD  -1,  R3 

ROTD  -1,  R2 

/R2R3  -  y/2 

ADDD  R4,R2 

ADDCD  R5,R3 

/  R2R3  -  y/2  +  halfx/y 

/4th  iteration  complete 

RESTORE  [RO, Rl] 

/get  exponent  4  ret.  addr 

ADDD  R2,R2 

/shift  mantissa  back  where  it  belongs 

ADDCD  R3,R3 

BCC1  SQR4 

/there  should  almost  never  be  a  carry 

MOVB  R3,R2 

LSHD  -1 ,  R3 

/undo  that  last  shift  4  zero  the  MSbit 

ROTD  -1,  R2 

ADDQW  1, Rl 

/adjust  exponent 

BR1  SQR5 

/  done 

SQR4 

CBITB  31,  R3 

/test  &  clear  MSbit  (make  it  a  +  sign) 

BFS1  SQR5 

/it  would  virtually  always  be  a  1 

ADDD  R2, R2 

/if  not,  shift  left  again 

ADDCD  R3,R3 

ADDQW  -1,  Rl 

/adjust  exponent 

CBITB  31,  R3 

/make  it  + 

SQR5 

ANDW  F800H,  R2 

/clean  the  mantissa 

ORW  Rl,  R2 

/append  the  exponent 

MOVD  4  (RO)  ,  Rl 

/get  addr  of  destination  variable 

MOVD  R2, 0  (Rl) 

/store  result  in  dest.  variable 

MOVD  R3 , 4  (Rl) 

JUMP  8 (RO) 

/return  to  caller 

END 

End  Listings 
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C  CHEST 


Listing  One  (Text  begins  on  page  18.) 


Listing  1  —  tree.c 


# include  <stdio.h> 


TREE.C:  Various  binary  tree  routines: 


(C)  1986,  Allen  I.  Holub.  All  rights  reserved. 


typedef  struct  _n 


struct  _n  *left; 

struct  _n  * right; 


char 

extern  char 


*Map; 

*makebitmap  ()  ; 


*  These  defines  are  used  by  the  lr_trav()  routine: 
*/ 


#def ine  mark (p) 
#define  marked (p) 
#define  unmark (p) 
#define  visit (root) 


(  *(  (p) ->key  )  |=  0x80  ) 

(  *  (  (p)  ->key  )  &  0x80  ) 

(  * (  (P) ->key  )  &=  -0x80  ) 

printf("%s  ",  root->key  ); 


tree(  key,  rootp  ) 
char  *key; 

LEAF  **rootp; 


/*  POINTER  to  (not  the  contents  of)  the  root 


/*  Non-recursive  binary  tree  search  and  insert  function.  If  key 

*  is  in  the  tree  a  message  to  that  effect  is  printed,  otherwise 

*  a  node  containing  key  is  inserted  into  the  tree  at  the 

*  proper  place. 

*/ 

LEAF  *root  =  *rootp  ; 

LEAF  **insert_here  =  rootp  ; 

LEAF  *malloc(); 

int  rel; 

while (  root  ) 

{ 

if(  (rel  =  strcmp(key,  root->key))  =  0  ) 

{ 

printf("key  <%s>  in  tree\n",  key  ); 
return; 


insert_here  =  (rel  <  0)  ?  &root->left  :  &root->right 
root  =  * insert  here  ; 


if (  *insert_here  =  root  =  malloc  (sizeof  (LEAF) )  ) 

{ 

root->right  =  root->left  =  NULL; 
root->key  =  key; 

} 

else 

printf("Out  of  memory  An") ; 


sinorder(  root  ) 

LEAF  *root; 

{ 

/*  A  simple  recursive  in-order  traversal,  each  node  is  printed 

*  with  as  many  tabs  to  it's  left  as  it  is  deep  in  the  tree. 

*  (if  a  node  is  at  depth  4  then  4  tabs  are  printed) . 


static  int  depth  =  -1; 

register  int  i; 

if(  root  ) 

{ 

depth++; 

inorder (  root->left  )  ; 

for(i  =  depth;  — i  >=  0  ;  putchar ( 1 \t ' )  ) 


printf(  "%s\n",  root->key  ); 
inorder (  root->right  ); 
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91 

92 

depth — ; 

93 

j 

94 

95 

97 

*  inorder (): 

98 

* 

99 

*  Does  an  recursive  in-order  traversal  of  a  binary  tree,  printing 

100 

*  it 

in  graphic  form  (showing  the  various  pointers) .  Note  that 

101 

*  the  traverse  order  is  reversed  (go  right,  print  root,  go  left) 

102 

*  so 

that  a  mirror  image  of  the  tree  won't  be  printed  (normal 

103 

*  traversal  would  result  in  the  leftmost  node  of  the  left  subtree 

104 

*  being  printed  first) . 

105 

* 

106 

* 

|  is  associated  with  this  depth  in  the  bitmap: 

107 

* 

12  3 

108 

* 

i  i  i 

109 

* 

V  V  | 

110 

* 

V 

111 

* 

+ — 1 — + 

112 

* 

1  1  + - 2 

113 

* 

|  H - 2 - 1- 

114 

* 

0 - h  Node  number  ==  depth  in  tree. 

115 

* 

1  + - 2 

116 

* 

+ - 1 - + 

117 

★ 

+ - 2 

118 

*/ 

119 

120 

inorder (  root,  amleft  ) 

121 

LEAF 

‘root;  /*  Root  of  current  subtree 

*/ 

122 

int 

amleft;  /*  Root  is  a  left  decendant  of  the  parent 

*/ 

123 

( 

124 

125 

static  int  depth  =  -1;  /*  Current  depth  in  the  tree 

*/ 

126 

int  i; 

127 

128 

iff  root  ) 

129 

{ 

130 

++depth; 

131 

132 

if (  root->right  ) 

133 

inorder  (  root->right,  0  ); 

134 

else 

135 

setbit (  depth+1.  Map,  1  ) ; 

136 

137 

for(i  =  1;  i  <=  depth  ;  i++  ) 

138 

( 

139 

printf(  i  =  depth  ?  "  + - "  : 

140 

testbit  (i,Map)  ?  "  |  "  : 

141 

”  “  ) ; 

142 

) 

143 

144 

printf(  "%s%s\n",  root->key. 

145 

root->left  | |  root->right  ?  " - +"  :  "" 

); 

146 

147 

setbit (  depth.  Map,  amleft  ?  0  :  1  ) ; 

148 

149 

if (  root->left  ) 

150 

inorder (  root->left,  1  ); 

151 

else 

152 

setbit (  depth+1.  Map,  0  ) ; 

153 

154 

— depth; 

155 

i 

156 

i 

157 

158 

159 

160 

161 

162 

163  pline(  depth  ) 

164 

165 

int  i; 

166 

for  (i  -  0;  i  <  depth-1  ;  i++  ) 

167 

printf (  testbit (i, Map)  ?  "|  “  ;  “  “  ); 

168 

i 

169 

170 

/*-  - 

*/ 

171 

172  preorder (  root,  amright  ) 

173 

LEAF 

*root; 

174 

i 

175 

/*  Does  a  recursive  pre-order  traversal  of  a  binary  tree  printing 

176 

*  the  tree  in  graphic  form.  Though  this  routine  is  interesting 

177 

*  it  is  more  useful  when  adapted  to  multi-way  tree  traversal 

178 

*  for  use  in  such  aplications  a  printing  directory  trees. 

179 

*/ 

180 

181 

static  int  depth  =  -1; 

182 

183 

if (  root  ) 

184 

< 

185 

pline (  ++depth  ) ; 

186 

printf (  "%s%s\n",  depth  ?  "+ - "  :  ""  ,  root->key  ) 

187 

188 

iff  root->right  )  (continued  on  next  page) 
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C  CHEST 

Listing  On@  (Listing  continued,  text  begins  on  page  18.) 

189 

setbit (  depth,  Map,  1  ) ; 

190 

191 

preorder (  root->left,  0  ); 

192 

setbit  (  depth.  Map,  0  ) ; 

193 

preorder (  root->right,  1  ); 

194 

195 

if (  amright  &&  ! (root->right  ||  root->left)  ) 

196 

{ 

197 

pline(  depth  ); 

198 

printf  ("\n") ; 

199 

i 

200 

201 

depth — ; 

202 

i 

203 

204 

205 

206 

* 

lr  trav()  (below)  does  a  non-recursive  link-reversal  traversal  of  a 

207 

* 

binary  tree.  The  algorithm  used  is: 

208 

* 

209 

* 

do  forever 

210 

* 

if (  marked (  pres  )  ) 

211 

* 

clear  mark 

212 

k 

else 

213 

k 

while (  there's  a  left  child  ) 

214 

* 

preorder  visit 

215 

* 

go  left 

216 

k 

217 

k 

inorder  &  preorder  visit 

218 

k 

219 

k 

postorder  visit 

220 

k 

221 

k 

if (  no  previous  node  ) 

222 

k 

break 

223 

k 

224 

k 

if (  marked (  prev  )  ) 

225 

k 

go  up  from  a  right  child 

226 

k 

else 

227 

* 

go  up  from  a  left  child 

228 

* 

inorder  visit 

229 

* 

set  mark 

230 

* 

go  right 

231 

* 

232 

* 

"Go"  means  to  decend  one  node  in  the  tree,  reversing  the  pointer 

233 

* 

to  that  node  so  that  it  points  back  up  where  we  came  from. 

234 

* 

If  we  "go  left"  then  we  reverse  the  the  left  pointer; 

235 

* 

if  we  "go  right"  then  right  pointer  is  reversed.  "Go  up"  means 

236 

* 

return  to  the  previous  node  and  make  the  pointer  point  back  to 

237 

* 

its  original  location.  A  node  is  marked  after  we  have 

238 

* 

traversed  its  left  sub-tree.  The  mark  is  cleared  after  we've 

239 

* 

traversed  both  the  left  and  right  sub-trees.  The  high  bit  of 

240 

* 

the  "key"  field  is  used  to  mark  the  node,  you  could  also  add 

241 

* 

another  field  to  the  structure  if  you  have  a  numeric  key.  Only 

242 

* 

one  bit  is  needed  for  the  mark. 

243 

V 

244 

245 

lr  trav(  pres  ) 

246 

LEAF  *pres; 

247 

{ 

248 

LEAF  *prev  =  NULL,  *  next ; 

249 

250 

while (  1  ) 

251 

( 

252 

if (  marked (pres)  ) 

253 

unmark (  pres  ) ; 

254 

else 

255 

i 

256 

while (  next  =  pres->left  ) 

257 

( 

258 

/*  preorder  visit  */ 

259 

/*  goes  here  */ 

260 

261 

pres->left  =  prev;  /*  go  left  */ 

262 

prev  =  pres; 

263 

pres  =  next; 

264 

} 

265 

visit  (  pres  ) ;  /*  inorder  &  pre-  */ 

266 

/*  order  visit  */ 

267 

i 

268 

269 

/*  postorder  visit  goes  here  */ 

270 

271 

if (  Iprev  ) 

272 

break; 

273 

274 

if(  marked (prev)  ) 

275 

f 

276 

next  =  prev-> right;  /*  go  up  from  a  */ 

277 

prev->right  =  pres;  /*  right  child  */ 

278 

pres  =  prev; 

279 

prev  =  next ; 

70 

488 


Dr.  Dobb's  Journal,  July  1986 


280 

} 

281 

else 

282 

{ 

283 

next  =  prev->left; 

284 

prev->left  =  pres; 

285 

pres  =  prev; 

286 

prev  =  next; 

287 

288 

visit  (  pres  ) ; 

289 

290 

mark (  pres  ) ; 

291 

if (  next  =  pres->right  ) 

292 

{ 

293 

pres->right  =  prev; 

294 

prev  =  pres; 

295 

pres  =  next ; 

296 

} 

297 

} 

298 

} 

299 

300 

print f ("\n") ; 

301  } 

302 

303  /* _ 

304 

305  main (argc,  argv) 

306  char 

**argv; 

307  ( 

308 

static  LEAF  *root  =  NULL  ; 

309 

char  buf [128] ; 

310 

311 

Map  =  makebitmap (  128  ) ; 

312 

313  llfdef  M0DE1 

314 

for(  printf("?  ");  gets (buf) ;  printf("?  ") 

315 

{ 

316 

tree  (  strsave (buf) ,  &root  ) ; 

317 

lr_trav  (  root  ) ; 

318 

inorder  (  root  ,  0  ) ; 

319 

preorder (  root  ,  0  ) ; 

320 

} 

321  #endif 

322 

323 

while (  — argc  >  0  ) 

324 

tree (  *++argv,  &root  ) ; 

325 

326 

inorder  (  root  ,  0  ) ; 

327  } 

/*  go  up  from  a  */ 
/*  left  child  */ 


/*  inorder  visit  */ 

/*  mark  the  node  */ 
/*  go  right  */ 


End  Listing  One 


Listing  Two 


Listing  2  —  bitmap,  c 


1  /*  BITMAP. C  makebitmap,  setbit,  testbit:  bit  map  manipulation 

2  *  routines. 

3  * 

4  *  Copyright  (c)  1985,1986  Allen  I.  Holub,  all  rights  reserved. 

5  * 

6  *  These  routines  originally  appeared  in  the  June,  1985,  C  Chest  (DDJ 

7  *  #104) .  They  are  reproduced  here  in  a  stripped-down  version. 

8  *  Please  see  that  column  for  more  information  about  how  they  work. 

9  */ 

10 

11  extern  char  *calloc  (  unsigned,  unsigned  ) ; 

12 

13  typedef  char  BITMAP; 


14 

15  /* - */ 

16 

17  BITMAP  *makebitmap(  size  ) 

18  unsigned  size; 

19  { 

20  /*  Make  a  bit  map  for  "size"  bits.  */ 

21  /*  Return  a  pointer  to  the  map  or  NULL  if  we  couldn't  make  it.  */ 

22 

23  unsigned  *map,  numbytes; 

24 

25  numbytes  =  (size  »  3)  +  ((size  &  0x07)  ?  1  :  0  )  ; 

26 

27  if(  map  =  (unsigned  *)  calloc(  numbytes  +  si zeof (unsigned)  ,1  )  ) 

28  *map  =  size; 

29 

30  return  (BITMAP  *)  map; 

31  } 

32 

34 

35  setbit (  c,  map,  val  ) 

36  unsigned  c,  val; 

37  char  *map; 

38  { 

39  /*  Set  bit  c  in  the  map  to  val.  */ 

40  /*  If  c  >  map  size,  0  is  returned,  else  1  is  returned.  */ 


(continued  on  next  page) 
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_ FORTH  STANDARDS 

Listing  One  (Text  begins  on  page  30.) 


B: PAPERS. BLK 
Screen  12* 

0  \  FORTH-83  Standard  type  control  structures  GWS  86Mar31 

1  \  note:  !0  is  0  SWAP  !  AD DR,  is  ,  (S  is  ( 

2 

3  :  >MARK  HERE  2  ALLOT  ;  (S  -  a  ) (  mark  forward  branch  ) 

4  :  >RESOLVE  HERE  SWAP  !  ;  (S  a  -  )  (  patch  forward  branch  ) 

5  :  <MARK  HERE  ;  (S  -  a  ) (  destination  for  back  branch  ) 

6  :  <RESOLVE  AD DR,  ;  (S  a  -  ) (  compile  reference  to  a  ) 

7 

8  VARIABLE  LEAVE-LIST 

9  :  >MARKLIST  (S  a  -  ) (  extend  list  at  a,  link  in  dictionary  ) 

10  HERE  SWAP  DUP  0  ADDR,  (  link)  !  (  new  head)  ; 

11  :  >RESOLVESLIST  (S  a  -  ) (  resolve  all  nodes  in  a  to  here  ) 

12  DUP  0  BEGIN  DUP  WHILE  DUP  0  SWAP  >RESOLVE  REPEAT 

13  DROP  !0  ;  12  +THRU 


Screen  13 

0  \  conditional  compilers  -  if /else/then  begin/while  GWS  86Mar31 
1 

2  :  IF  (S  -  a  /  f  -  ) (  compile  to  branch  if  f  is  false  ) 

3  COMPILE  ? BRANCH  >MARK  ;  IMMEDIATE 

4  :  ELSE  (S  al  -  a2  /  -  ) (  compile  alternate  to  IF  clause  ) 

5  COMPILE  BRANCH  >MARK  SWAP  > RE SOLVE  ;  IMMEDIATE 

6  :  THEN  (S  a  -  /  -  ) (  resolve  latest  forward  reference  ) 

7  >RESOLVE  ;  IMMEDIATE 

8 

9  :  BEGIN  <MARK  ;  IMMEDIATE  (S  -  a  /  -  ) (  mark  loop  start  ) 

10  :  WHILE  [COMPILE]  IF  ;  IMMEDIATE  (S  -  a  /  f  -  ) (  loop  exit  ) 

11  :  REPEAT  (S  al  a2  -  /  -  ) (  branch  to  beginning  of  loop  ) 

12  COMPILE  BRANCH  SWAP  < RE SOLVE  >RESOLVE  ;  IMMEDIATE 

13  :  UNTIL  (S  a  -  /  f  -  ) (  branch  to  beginning  of  loop  until  true  ) 

14  COMPILE  ? BRANCH  <RESOLVE  ;  IMMEDIATE 


(S  -  /  -  ) (  compile  exit  from  structure  ) 
LEAVE-LIST  >MARKLIST  ;  IMMEDIATE 

(S  -  n  a  /  nl  n2  -  )(  initiate  counted  loop  ) 
LEAVE-LIST  0  LEAVE-LIST  SO  <MARK 

(S  n  a  -  /  -  ) (  compile  increment  loop  end  ) 
< RESOLVE  LEAVE-LIST  >RESOLVESLIST 

;  IMMEDIATE 


Screen  14 

0  \ 

do  loops 

1 

2  : 

LEAVE 

3 

COMPILE 

(LEAVE) 

4 

5  : 

DO 

6 

COMPILE 

(DO)  ] 

7 

IMMEDIATE 

8  : 

LOOP 

9 

COMPILE 

(LOOP) 

10 

LEAVE-LIST  ! 

11  : 

+LOOP 

(S  n 

12 

COMPILE 

(+LOOP ) 

13 

LEAVE-LIST  ! 

14 

15 

<RESOLVE 
;  IMMEDIATE 


LEAVE-LIST  >RESOLVESLIST 


Listing  Two 


12  :  >RESOLVES LIST  (S  a  -  ) (  resolve  all  nodes  in  a  to  here  ) 

13  DUP  0  BEGIN  DUP  WHILE  DUP  0  SWAP  >RESOLVE  REPEAT 

14  DROP  SO  ;  16  +THRU 

15 


Screen  4 

0  \  compilation  list  initialization 

1  ORPHAN 

2  VARIABLE  IF-LIST  VARIABLE  LEAVES-LIST 

3  VARIABLE  LEAVE -CF 


GWS  86Mar31 
(  make  headless  words  ) 
VARIABLE  LEAVE-LIST 


INIT-LISTS 
IF-LIST  SO 


LEAVE-LIST  SO 


(S  -  )  (  reset  all  list  pointers  ) 
LEAVES-LIST  10 


9  IN 

10  :  RES' 

11  (  Cl 

12  LEi 

13 

14  ADOPT 

15 


SAVE-LISTS  (S  -  x  x  x  x  ) (  save  current  list  pointers  ) 

LEAVE-CF  0  IF-LIST  0  LEAVE-LIST  0  LEAVES-LIST  0 
INIT-LISTS 

RESTORE-LISTS  (S  -  x  x  x  x  ) (  restore  current  list  pointers  ) 
(  could  check  here  for  unresolved  structures) 

LEAVES-LIST  !  LEAVE-LIST  !  IF-LIST  !  LEAVE-CF  1 


(  make  headed  words  ) 


Screen  5 

0  \  Conditional  compilers  -  if/else/then  &  case 
1 

2  :  IF  (S  -  /  f  -  ) (  compile  to  branch  if  f  is  false  ) 

3  COMPILE  ?BRANCH  IF-LIST  >MARKLIST  ;  IMMEDIATE 

4  :  ELSE  (S  -  /  -  ) (  compile  alternate  to  IF  clause  ) 

5  COMPILE  BRANCH  IF-LIST  >MARKLIST  IF-LIST  0  (  if  branch) 

6  >RESOLVELIST  ;  IMMEDIATE 

7  :  THEN  (S  -  /  -  ) (  resolve  latest  forward  reference  ) 

IF-LIST  >RESOLVELIST  ;  IMMEDIATE 


End  Listing  One 


CASE  (S-xxxx/?-?)(  setup  for  case  statement  ) 

SAVE-LISTS  [']  BRANCH  LEAVE-CF  1  ;  IMMEDIATE 

ENDCASE  (S— /xxxx— )(  restore  lists,  resolve  leaves  ) 
LEAVES-LIST  >RESOLVESLIST  RESTORE-LISTS  ;  IMMEDIATE 


B: PAPERS. BLK 
Screen  6* 

0  \  common  loop  end  and  exit  GWS  86Mar31 

1 

2  ORPHAN  (  make  headless  words  ) 

3  :  LOOPEND  (S  x  x  x  x  al  a2  -  ) (  resolve  list  a2  &  branch  ) 

4  (  al,  restore  values  x,  transfer  leaves-list  to  if-list  ) 

5  SWAP  <RESOLVE  (  back  branch)  >RESOLVESLIST  (  forward  branch) 

6  LEAVES-LIST  0  ?DUP  IF  >R  RESTORE-LISTS  IF-LIST  0  Rg 

7  BEGIN  DUP  0  WHILE  0  REPEAT  (  find  leaves  list  end)  ! 

8  (  link  to  if  list)  R>  IF-LIST  !  ELSE  RESTORE-LISTS 

9  THEN 

10  ADOPT  (  make  headed  words  ) 

11  :  OUTSIDE  (S  -  /  -  ) (  allow  LEAVES  outside  current  loop  level) 

12  IF-LIST  0  DUP  0  IF-LIST  !  (  unlink)  LEAVES-LIST  0  OVER  ! 

13  COMPILE-UNNEST  LEAVES-LIST  !  (  relink)  ;  IMMEDIATE 


B: PAPERS. BLK 


Screen  15* 

0  \  typical  BEGIN  loop  extensions  GWS  86Mar31 

1 

2  :  RESOLVES  (S  0. .a  -  ) (  resolve  forward  branches  a  until  0  ) 

3  BEGIN  ?DUP  WHILE  >RESOLVE  REPEAT 


;  IMMEDIATE  (S  0  a  -  ) (  mark  loop  start  ) 

(S  al  -  a2  al  /  f  -  ) (  conditional  loop  exit  ) 
SWAP  ;  IMMEDIATE 


WHILE  (S  al  -  a2  al  /  f  -  ) (  conditional  loop  exit  ) 

[COMPILE]  IF  SWAP  ;  IMMEDIATE 

REPEAT  (S  0..an  a  -  /  -  ) (  terminate  repeating  loop  ) 

COMPILE  BRANCH  < RESOLVE  RESOLVES  ;  IMMEDIATE 
UNTIL  (S  0 . . an  a  -  /  f  -  ) (  terminate  conditional  loop  ) 

COMPILE  ?BRANCH  <RESOLVE  RESOLVES  ;  IMMEDIATE 


Screen  7 
0  \  do  loops 
1 


GWS  86Mar31 


End  Listing  Two 


LEAVE  (S  -  /  -  ) (  compile  exit  from  structure  ) 

LEAVE-CF  0  ADDR,  LEAVE-LIST  >MARKLIST  ;  IMMEDIATE 
LEAVES  (S  -  /  -  )  (  compile  exit  to  outside  structure  ) 

LEAVE-CF  0  ADDR,  LEAVES-LIST  >MARKLIST  [COMPILE]  THEN  ; 
IMMEDIATE 

DO  (S-xxxxa/uu-)(  initiate  counted  loop  ) 

SAVE-LISTS  [•]  (LEAVE)  LEAVE-CF  !  COMPILE  (DO) 

<MARK  ;  IMMEDIATE 

LOOP  (Sxxxxa-/-)(  compile  increment  loop  end  ) 

COMPILE  (LOOP)  LEAVE- LIST  LOOPEND  ;  IMMEDIATE 
+LOOP  (Sxxxxxa-/u-)(  compile  u+  loop  end  ) 

COMPILE  (+LOOP)  LEAVE-LIST  LOOPEND  ;  IMMEDIATE 


Listing  Three 


B: PAPERS. BLK 
Screen  3* 

0  \  Proposed  Standard  Control  Structures 

1  \  note:  !0  is  0  SWAP  !  ADDR,  is  ,  (S  is  ( 

2 

3  :  >MARK  HERE  2  ALLOT  ;  (S  -  a  ) (  ma 

4  :  >RESOLVE  HERE  SWAP  !  ;  (S  a  -  ) (  pat 

5  :  <MARK  HERE  ;  (S  -  a  )  (  destinatio: 

6  :  <RESOLVE  ADDR,  ;  (S  a  -  ) (  compi 


GWS  86Mar31 


>MARK  HERE  2  ALLOT  ;  (S  -  a  ) (  mark  forward  branch  ) 

>RESOLVE  HERE  SWAP  !  ;  (S  a  -  ) (  patch  forward  branch  ) 

<MARK  HERE  ;  (S  -  a  ) (  destination  for  back  branch  ) 

<RESOLVE  ADDR,  ;  (S  a  -  ) (  compile  reference  to  a  ) 

>MARKLIST  (S  a  -  ) (  extend  list  at  a,  link  in  dictionary  ) 

HERE  SWAP  DUP  0  ADDR,  (  link)  !  (  new  head)  ; 

>RESOLVELIST  (S  a  -  ) (  resolve  top  node  in  a  to  here  ) 

DUP  0  DUP  @  ROT  !  (  unlink  top  node)  >RESOLVE 


Screen  8 
0  \  more  loops 
1 

2  :  BEGIN 

3  [COMPILE]  CASE 


GWS  86Mar31 


(S-xxxxa/-)(  mark  start  of  a  loop  ) 
<MARK  ;  IMMEDIATE 


REPEAT  (Sxxxxa-/-)(  terminate  repeating  loop  ) 

COMPILE  BRANCH  IF-LIST  LOOPEND 
LEAVE-LIST  >RESOLVESLIST  ;  IMMEDIATE 
UNTIL  (Sxxxxa-/-)(  terminate  repeating  loop  ) 

COMPILE  ? BRANCH  IF-LIST  LOOPEND 

LEAVE-LIST  >RESOLVESLIST  ;  IMMEDIATE 


[COMPILE]  IF 


(S  -  ) (  for  compatibility) 


End  Listing  Three 


Dr.  Dobb's  Journal,  July  1986 


82 

491 


Listing  Four 

THEN 

none 

BEGIN  .  .  . 

B:PAPERS.BLK 

BEGIN  . . . 

IF  LEAVES 

Screen  9* 

0  \  suggested  extensions 

GWS  86Mar31 

REPEAT  OUTSIDE 

1 

2  :  ? LEAVE 

(S  - 

/  f  -  ) (  leave  do  loop  if  tf  ) 

REPEAT 

3  COMPILE  ( ?  LEAVE ) 

LEAVE-LIST 

>MARKLIST  ;  IMMEDIATE 

THEN 

4  :  ? LEAVES 

(S  - 

/  f  -  ) (  leave  do  loop  if  tf  ) 

5  COMPILE  ( ?  LEAVE ) 

6 

LEAVES- LI ST 

>MARKLIST  ;  IMMEDIATE 

<STEPS  . .  . 

CASE 

7  :  THENS 

(S  -  /  -  )  | 

resolve  all  outstanding  IFs  ) 

&IF  .  .  . 

IF  .  .  . 

8  IF-LIST  >RESOLVESLIST  ;  IMMEDIATE 

&IF  .  .  . 

9  :  ELSES  (S  -  /  -  ) ( 

resolve  all 

outstanding  IFs  w/common  ELSE  ) 

STEPS> 

THENS 

10  [COMPILE]  ELSE 

IF-LIST  @  > RESOLVES  LI  ST  ;  IMMEDIATE 

ENDCASE 

11 

12 

13 

IF  .  .  .  ELSE  .  .  . 

IF  . . .  ELSE  . . . 

14 

15 

End  Listing  Four 

THENIF  . . .  ELSE 

THENIF  . . .  ELSE 

IF  . . .  ELSE  . . . 

IF  . . .  ELSE  . . . 

THEN 

THENS  or 

CASE 

Listing  Five 

IF  . . .  LEAVES 

IF  . . .  LEAVES 

Previously  Proposed  Solutions 

Proposed  Solution 

ENDCASE 

IF  .  .  . 

IF  .  .  . 

BEGIN  . . . 

same 

ANDIF  .  .  . 

IF  .  .  . 

WHILE  . . . 

ANDIF  . .  . 

IF  .  .  . 

WHILE  .  .  . 

(  ELSE) 

(  ELSES) 

REPEAT 

THEN 

THENS  (  THEN) 

BEGIN  . . . 

same 

CASE  . .  . 

CASE  . . . 

WHILE  .  .  . 

OF  . . .  ENDOF 

OVER  -  IF  ...  LEAVES 

WHILE  . . . 

OF  . . .  ENDOF 

OVER  -  IF  ...  LEAVES 

UNTIL 

END CASE 

DROP  ENDCASE 

BEGIN  . . . 

BEGIN  . . . 

WHILE  . . . 

WHILE 

ANDWHILE  . . . 

ANDWHILE  . . . 

WHILE 

WHILE 

End  Listings 

REPEAT 

REPEAT 

BEGIN  . . . 

BEGIN  . . . 

WHILE  aa 

NOT  IF  ff  LEAVES  aa 

WHILE  bb 

NOT  IF  ee  LEAVES  bb 

WHILE  cc 

WHILE  cc 

REPEAT  dd 

REPEAT  dd 

<WHILE  ee 

<WHILE  ff 

<END 

THEN  THEN 

BEGIN  . . . 

see  below 

IF  ...  LEAVE  THEN 

IF  . . .  LEAVE  THEN 

REPEAT 

BEGIN  . . . 

BEGIN  . . . 

UNLESS  . . .  FINISH 

IF  . . .  LEAVES 

UNLESS  . . .  FINISH 

IF  . . .  LEAVES 

AGAIN 

REPEAT  THEN  THEN 

DO  .  .  . 

DO  .  .  . 

PERHAPS  . . .  ESCAPE 

IF  . . .  LEAVES 

PERHAPS  . . .  ESCAPE 

IF  . . .  LEAVES 

LOOP  . . . 

LOOP  . .  . 

ESCAPED  . . . 

THEN  THEN  ...  (or  ELSE  . . . 

THEN) 

DO  .  .  . 

DO  .  .  . 

IF  . . .  LEAVE  THEN 

aa 

IF  . . .  LEAVES  aa 

LOOP— FALLTHRU:  bb 

LOOP  bb 

THEN  CC 

THEN  CC 

DO  .  .  . 

DO  .  .  . 

WHEN  . . . 

NOT  IF  LEAVE  THEN  . . . 

LOOP 

LOOP 

DO  .  .  . 

DO  .  .  . 

NOTWHEN  .  .  . 

IF  LEAVE  THEN  . . . 

LOOP 

LOOP 

DO  .  .  . 

DO  .  .  . 

IF  LEAVE  THEN  . . . 

IF  LEAVES 

EXITING  LOOP 

LOOP 

THEN 

THEN 

none 

DO  .  .  . 

DO  .  .  . 

IF  LEAVES 

LOOP  OUTSIDE 

LOOP 
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FORTH  AT  SEA 

Listing  One 

(Text  begins  on  page  40.) 

***************************************************************** 

ORG  $0029 

*  RAFOS  FORTH  VI. 0 

26  March  1986  * 

* 

*  _ 

RCM  #1  of  2 

* 

IN 

FCB  #0 

Where  FORTH  will  look  for  input 

* 

* 

OUT 

FCB  »0 

*  (C) 

Copyright  1986, 

Everett  Carter.  All  rights  reserved.  * 

COUNTR 

FCB  #0 

* 

* 

DP 

FDB  #$01DC 

The  initial  Dictionary  pointer 

*  This 

FORT! 

is  a  subset  of  the  FORTH-79  standard.  * 

START 

FDB  #0 

The  start  up  vector 

*  Some 

changes  have  been  made  in  order  to  save  on  * 

* 

*  space  in  the  limited  memory  of  the  float.  * 

* 

* 

* 

IP 

FDB  fO 

THE  FORTH  INSTRUCTION  POINTER 

***************************************************************** 

RP 

FCB  #0 

THE  RETURN  POINTER  OFFSET 

* 

SP 

FCB  #0 

THE  STACK  POINTER  OFFSET 

*  EQUATES 

FOR  RCM 

2 

BASE 

FCB  #$10 

QUES 

EQU 

$1000 

* 

* 

USER 

EQU  * 

The  space  for  USER  variables 

TOG  6 

EQU 

$105F 

TOGGLE 

FENCE 

EQU  0 

USER  +  0 

IhW9 

EQU 

$1089 

IMMEDIATE 

FDB  #0 

INITIALIZE  USER  VARS 

DFND 

EQU 

$109B 

-FIND 

STATE 

EQU  2 

USER  +  2 

COU5 

EQU 

$10B1 

COUNT 

FDB  #0 

ZERO 

EQU 

$10C3 

0 

FORTH 

EQU  4 

USER  +  4 

ONE 

EQU 

$10D8 

1 

FDB  #0 

TWO 

EQU 

$10EF 

2 

CONTEXT 

EQU  6 

USER  +  6 

TWOP 

EQU 

$1106 

2+ 

FDB  USER+FORTH 

LBRAK 

EQU 

$1121 

i 

CURRENT 

EQU  8 

USER  +  8 

RBRAK 

EQU 

$1131 

i 

FDB  USER+FORTH 

DEFS 

EQU 

$1143 

DEFINITIONS 

HID 

EQU  $0A 

USER  +  $0A 

PUJS 

EQU 

$1155 

+ 

FDB  #0 

MINUS 

EQU 

$117C 

- 

* 

UMULT 

EQU 

$11A7 

U* 

ORG  $0080 

PAD 

EQU 

$1289 

PAD 

* 

The  start  of  the 

INNER  interpreter 

LSHP 

EQU 

$129B 

<# 

* 

OVER 

EQU 

$12AB 

OVER 

DOCOL 

LDX  RP 

*  Push  IP  to  RS 

SPGR 

EQU 

$12CE 

«> 

* 

TOR 

EQU 

$12E6 

>R 

DOCOL1 

EQU  DOCOL 

RTO 

EQU 

$130A 

R> 

* 

RFTCH 

EQU 

$132E 

R@ 

DECX 

ROT 

EQU 

$134F 

ROT 

LDA  IP+1 

HOLD 

EQU 

$1361 

HOLD 

STA  RPO, X 

* 

DECX 

CCMP 

EQU 

$1557 

COMPILE 

LDA  IP 

SEMI 

EQU 

$156D 

t 

STA  RPO, X 

COLON 

EQU 

$157F 

STX  RP 

TICK 

EQU 

$159B 

i 

IDA  NEXT1+2 

VAR8 

EQU 

$15C5 

VARIABLE 

ADD  #2 

* 

STA  IP+1 

11 

EQU 

$17EE 

I 

LDA  NEXT1+1 

* 

ADC  #0 

LATEST 

EQU  11 

-6 

Last  Dictionary  entry 

STA  IP 

RCM 

EQU 

$1800 

RCM  #1  start  address 

* 

fall  thru  to  NEXT 

CR 

EQU 

$0D 

CARRIAGE  RETURN 

NEXT 

LDA  IP+1 

NEXT  The  Inner  Interpreter 

LF 

EQU 

$0A 

LINE  FEED 

STA  CA+2 

SELF-MODIFYING 

BL 

EQU 

$20 

BLANK 

LDA  IP 

BS 

EQU 

$08 

Back  Space 

STA  CA+1 

DEL 

EQU 

$7F 

Delete 

CA 

LDA  SPO 

—  SPO  is  a  dummy 

* 

STA  NEXT1+1 

DDR 

EQU 

4 

DATA  DIRECTION  REGISTER  OFFSET 

LDA  IP+1 

* 

ADD  #1 

PORTA 

EQU 

0 

I/O  PORT  0 

STA  CA2+2 

PORTB 

EQU 

1 

I/O  PORT  1 

LDA  IP 

PUT 

EQU 

PORTB 

SERIAL  I/O  PORT 

ADC  #0 

* 

STA  CA2+1 

INITSP 

EQU 

$7F 

INITIAL  STACK  POINTER  VALUE 

CA2 

LDA  SPO 

—  SPO  is  a  durrmy 

STACK 

EQU 

INITSP 

-5  TOP  OF  STACK 

STA  NEXT1+2 

MEMSIZ 

EQU 

$2000 

MEMORY  ADDRESS  SPACE  SIZE 

LDA  IP+1 

* 

ADD  #2 

SPO 

EQU 

$0F00 

STA  IP+1 

RPO 

EQU 

$0E00 

LDA  IP 

TIB 

EQU 

$0D80 

ADC  #0 

* 

STA  IP 

* 

NEXT1 

JMP  COLD 

—  COLD  is  a  dummy 

*  RAM  VARIABLES 

SELF  MODIFYING  CODE 

FIRST 

* 

ORG 

$10 

ON-CHIP  RAM  (112  BYTES) 

LOAD 

STA  SP0,X 

STA  (HERE)  ,X 

* 

RTS 

move  A  to  HERE+X 

ATEMP 

EQU 

$10 

TEMP  USED  IN  PUTDEC 

* 

XTEMP 

EQU 

$11 

INDEX  TEMPORARY 

GET 

LDA  SP0,X 

LDA  (HERE) ,X 

GETR 

EQU 

$12 

PICK  &  DROP  TEMPORARY 

RTS 

get  HERE+X  into  A 

COUNT 

EQU 

$16 

NUMBER  OF  BITS  LEFT  TO  get/send 

* 

CHAR 

EQU 

$17 

Current  input/output  character 

FCB  4 

TYPE  —  SELF  MODIFYING 

* 

FCC  'TYP' 

BYTCNT 

EQU 

$1E 

bytcnt . 

FDB  #0 

end  link 

WTIME 

EQU 

$20 

TIMER  INTERRUPT  FROM  WAIT  STATE 

TYPE 

LDX  SP 

* 

INCX 

Drop  high  byte 

* 

LDA  SP0,X 

PH 

EQU 

$21 

MI SC  SCRATCH  AREAS 

INCX 

PL 

EQU 

$22 

STA  COUNTR 

COUNTR  =  byte  count 

TEMPA 

EQU 

$23 

LDA  SP0,X 

TEMPB 

EQU 

$24 

INCX 

QH 

EQU 

$25 

STA  TYSCR+1 

QL 

EQU 

$26 

LDA  SP0,X 

TEMP 

EQU 

$27 

INCX 

TERM 

EQU 

$28 

STA  TYSCR+2 

* 

STX  SP 

CLR  OUT 
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TST  COUNTR 

BEQ  TXIT 

TLOOP 

LDX  OUT 

TYSCR 

LDA  SP0,X 

JSR  OUTCHAR 

INC  OUT 

IDA  OUT 

SUB  COUNTR 

BMI  TLOOP 

—  SPO  is  a  dummy 

TXIT 

JMP  NEXT 

FOB  6 

FCC  • <FI 1 

<FIND>  —  SELF  MODIFYING 

FDB  TYPE-6 

link  to  TYPE 

FIN6 

LDX  SP 

IDA  SP0,X 

INCX 

STA  GET+1 

get  addrl  high 

LDA  SP0,X 

INCX 

STA  GET+2 

addrl  low 

IDA  SP0,X 

INCX 

STA  FINSCR+1 

STA  FINCNT+1 

IDA  SP0,X 

INCX 

STA  FINSCR+2 

STA  FINCNT+2 

STX  SP 

get  addr2  high 

FINCNT 

LDA  SPO 

—  SPO  is  a  dummy 

STA  COUNTR 

save  byte  count 

TSTA 

BEQ  NONE 

count  -  0  ? 

FINLP1 

CLRX 

FINLP2 

JSR  GET 

AND  #$7F 

ignore  bit  7 

FINSCR 

CMP  SP0,X 

BNE  NFND 

—  SPO  is  a  dummy 

CPX  #3 

BEQ  FOUND 

X  =  3  ?  if  so  quit  as  FOUND 

CPX  COUNTR 

BEQ  FOUND 

INCX 

BRA  FINLP2 

X  =  count  ? 

NFND 

LDX  #4 

JSR  GET 

STA  ATEMP 

INCX 

JSR  GET 

Not  found,  go  to  next  element 

ORA  ATEMP 

=0  ? 

BEQ  NONE 

if  yes,  end  of  list 

JSR  GET 

STA  GET+2 

LDA  ATEMP 

STA  GET+1 

else  move  new  pointer  to  get 

BRA  FINLP1 

and  try  again 

NONE 

LDX  SP 

CLRA 

BRA  FQUIT 

nothing,  push  a  FALSE  to  stack 

FOUND 

LDX  SP 

LDA  GET+2 

ADD  16 

DECX 

STA  SP0,X 

LDA  GET+1 

ADC  #0 

DECX 

STA  SP0,X 

STX  SP 

CLRX 

push  CA  of  found  word 

JSR  GET 

LDX  SP 

DECX 

STA  SP0,X 

CLRA 

DECX 

STA  SP0,X 

get  the  byte  count  and  push  it 

LDA  #$FF 

push  a  TRUE  flag 

FQUIT 

DECX 

STA  SPOfX 

DECX 

STA  SP0,X 

STX  SP 

JMP  NEXT 

FCB  4 

FCC  'BRA' 

BRAN  —  SELF  MODIFYING 

FDB  FIN6-6 

link  to  <FIND> 

BRAN 

IDA  IP 

STA  BRSCl+1 

STA  BRSC2+1 

LDA  IP+1 

STA  BRSC1+2 

STA  BRSC2+2 

LDX  #1 

BRSC1 

LDA  SP0,X 

ADD  IP+1 

STA  IP+1 

CLRX 

BRSC2 

LDA  SP0,X 

ADC  IP 
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FORTH  AT  SEA 

Listing  One 

(Listing  continued,  text  begins  on  page  40.) 

STA  IP 

* 

JMP  NEXT 

FCB  4 

EMIT 

******* 

**************** 

****************************************** 

FCC  'EMI' 

* 

FDB  EXE7-6 

link  to  EXECUTE 

*  NO  SELF  MODIFYING 

CODE  BEYOND  THIS  POINT 

EMIT 

LDX  SP 

* 

INCX 

drop  high  byte 

OFFSET 

EQU  * 

LDA  SP0,X 

ORG  ROM+OFFSET 

*  RCM  12  ORIGIN 

INCX 

* 

STX  SP 

* 

JSR  OUTCHAR 

FCB  7 

0 BRANCH 

JMP  NEXT 

FCC  'OBR1 

* 

FDB  BRAN- 5 

link  to  BRAN 

FCB  2 

BL 

ZBRAN 

LDX  SP 

FCC  'BL  ' 

LDA  SP0,X 

FDB  EMIT- 6 

link  to  EMIT 

INCX 

BL2 

LDX  SP 

ORA  SPO,X 

LDA  IBL 

INCX 

DECX 

STX  SP 

STA  SP0,X 

TSTA 

CLRA 

BNE  ZBREX 

DECX 

JMP  BRAN 

STA  SP0,X 

ZBREX 

LDA  I P+1 

bump  IP  past  offset 

STX  SP 

ADD  #2 

JMP  NEXT 

STA  I P+1 

* 

LDA  IP 

FCB  4 

WORD 

ADC  10 

FCC  'WOR' 

STA  IP 

FDB  BL2-6 

link  to  BL 

JMP  NEXT 

WORD 

LDA  DP 

start  by  setting  up  LOAD 

* 

STA  LOAD+1 

FCB  4 

EXIT 

IDA  DP+1 

FCC  1 EXI ' 

STA  LOAD +2 

FDB  ZBRAN- 6 

link  to  OBRANCH 

CLR  COUNTR 

EXIT 

LDX  RP 

Pop  RS  into  IP 

CLRA 

LDA  RP0,X 

High  byte 

CLRX 

INCX 

JSR  LOAD 

clear  DP 

STA  IP 

LDX  SP 

get  terminator 

LDA  RPO, X 

then  low  byte 

INCX 

drop  high  byte 

INCX 

LDA  SP0,X 

STA  I P+1 

STA  TERM 

STX  RP 

INCX 

JMP  NEXT 

STX  SP 

* 

LDX  IN 

get  INput  pointer 

FCB  7 

EXECUTE 

CMP  IBL 

seperator  -  space  ? 

FCC  'EXE' 

BNE  TOK 

FDB  EXIT-6 

link  to  EXIT 

IGNBL 

LDA  TIB, X 

ignore  blank 

EXE7 

LDX  SP 

Pop  SP  into  W  (NEXT1+1) 

CMP  IBL 

LDA  SP0,X 

First  high  byte 

BNE  TOK 

INCX 

INCX 

STA  NEXT1+1 

BRA  IGNBL 

LDA  SP0,X 

Then  low  byte 

TOK 

INC  COUNTR 

INCX 

LDA  TIB,X 

STA  NEXT1+2 

STX  XTEMP 

save  X 

STX  SP 

LDX  COUNTR 

JMP  NEXT1 

JSR  LOAD 

move  char  to  DP  +  COUNTR 

* 

LDX  XTEMP 

get  X  back 

INLINE 

JSR  CRLF 

INCX 

LDA  IBL 

CMP  l$80 

character  =  buffer  end  ? 

CLR  COUNTR 

BEQ  WORXIT 

CLRX 

Clear  line  buffer 

CMP  TERM 

INLP1 

STA  TIB,  X 

BNE  TOK 

continue  unless  terminator 

INCX 

WORXIT 

STX  IN 

save  new  value  of  IN 

CPX  l$7E 

Buffer  end  ? 

LDA  COUNTR 

move  count -1  to  DP 

BNE  INLP1 

DECA 

CLR  IN 

CLRX 

CLRX 

Clear  buffer  pointer 

JSR  LOAD 

I  NLP  2 

JSR  GETCHAR 

(  x  -  IN  ) 

LDA  DP+1 

Push  DP  addr  to  stack 

CMP  #DEL 

=  DELETE  ? 

LDX  SP 

BNE  INTST2 

branch  if  not 

DECX 

INDEL 

CPX  «0 

STA  SP0,X 

BEQ  INLP2 

Skip  if  IN  (LBP)  =  0  already 

LDA  DP 

DECX 

DECX 

LDA  IBL 

DELETE  CHAR 

STA  SP0,X 

STA  TIB, X 

STX  SP 

LDA  IBS 

JMP  NEXT 

JSR  OUTCHAR 

* 

LDA  IBL 

MPY16 

LDX  l$10 

16  bit  X  16  bit  multiply  32  bit  result 

JSR  OUTCHAR 

CLR  TEMPA 

LDA  IBS 

CLR  TEMPB 

JSR  OUTCHAR 

ROR  QH 

BRA  I NLP 2 

ROR  QL 

I  NT  ST  2 

CMP  IBS 

maybe  its  a  backspace 

MPYNXT 

BCC  ROTAT 

BEQ  INDEL 

LDA  TEMPB 

CMP  ICR 

or  a  CR 

ADD  PL 

BEQ  INEX 

STA  TEMPB 

STA  TIB, X 

LDA  TEMPA 

CPX  I $7D 

ADC  PH 

BHS  INSKP 

STA  TEMPA 

INCX 

ROTAT 

ROR  TEMPA 

INSKP 

JSR  OUTCHAR 

ROR  TEMPB 

BRA  INLP2 

Back  to  main  loop 

ROR  QH 

INEX 

LDA  IBL 

ROR  QL 

JSR  OUTCHAR 

DECX 

JMP  NEXT 

BNE  MPYNXT 

* 

RTS 
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FCB  8 

FCC  ' <NU* 

<NUMBER> 

FDB  WORD- 6 

link  to  WORD 

NUM8 

LDX  SP 

LDA  SP0,X 

INCX 

STA  GET+1 

LDA  SP0,X 

pop  stack  into  GET 

INCX 

STA  GET+2 

STX  SP 

CLRX 

JSR  GET 

STA  COUNTR 

Put  char  count  into  COUNTR 

TSTA 

count  *  0  ? 

BEQ  NOTNO 

INCX 

CLR  TEMP 

TEMP  is  the  sign  flag 

CLR  QH 

CLR  QL 
cm  PH 

IDA  BASE 

STA  PL 

Set  P  -  BASE 

JSR  GET 

Get  first  char 

CMP  #$2D 

BNE  NUMSKP 

.  »_•  o 

DEC  TEMP 

Minus  flag  -  TRUE 

INCX 

bump  X 

CPX  COUNTR 

BHI  NOTNO 

JSR  GET 

X  >  COUNTR  ? 

NUMSKP 

INCX 

SUB  f $30 

at  this  point  X  points  1  past 

char  in  A 

BMI  NOTNO 

if  negative,  not  a  number 

CMP  #$0A 

341  NUMB 

less  than  10  ? 

CMP  #$11 

BMI  NOTNO 

SUB  #7 

valid  char? 

NUMB 

CMP  BASE 

BLO  ANUMB 

valid  for  this  base  ? 

NOTNO 

CLRA 

NOPE,  push  a  FALSE 

NUMXT 

IDX  SP 

DECX 

STA  SP0,X 

DECX 

STA  SP0,X 

STX  SP 

JMP  NEXT 

ANUMB 

STX  XTEMP 

save  X  in  XTEMP 

STA  ATEMP 

and  A  in  ATEMP 

JSR  MPY16 

Q  =  Q  *  BASE 

LDA  ATEMP 

get  A  back 

ADD  QL 

STA  QL 

LDA  QH 

ADC  #0 

Q  -  Q  +  A 

STA  QH 

LDX  XTEMP 

get  X  back 

CPX  COUNTR 

BHI  NUMOK 

JSR  GET 

BRA  NUMSKP 

X  >  COUNTR  ? 

NUMOK 

IDA  TEMP 

TSTA 

BEQ  NUMPOS 
CLRA 

NEG  QL 

SBC  QH 

STA  QH 

number  OK,  now  check  sign 

NUMPOS 

LDX  SP 

push  number  at  Q  and  flag 

IDA  QL 

DECX 

STA  SP0,X 

IDA  QH 

DECX 

STA  SP0,X 

LDA  #$FF 

TRUE  flag 

BRA  NUMXT +2 

FCB  4 

DROP 

FCC  'DRO' 

FDB  NUM8-6 

link  to  <NUMBER> 

DROP 

IDX  SP 

INCX 

INCX 

STX  SP 

JMP  NEXT 

FCB  2 

c@ 

FCC  *C@  ' 

FDB  DROP- 6 

link  to  DROP 

CFCH 

IDX  SP 

LDA  SP0,X 

INCX 

STA  GET+1 

LDA  SP0,X 

STA  GET+2 

STX  SP 

CLRX 

JSR  GET 

get  the  byte 

IDX  SP 

(continued  on 

next  page) 
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STA  SP0,X 

CLRA 

DECX 

STA  SPO,X 
STX  SP 
JMP  NEXT 


zero  high  byte 


FCB  1 
FCC  ' @  ' 

FDB  CFCH-6 
FTCH  IDX  SP 

LDA  SPO,X 
INCX 

STA  GET+1 
LDA  SPO,X 
STA  GET+2 
STX  SP 
LDX  #1 
JSR  GET 
LDX  SP 
STA  SPO,X 
CLRX 
JSR  GET 
IDX  SP 
DECX 

STA  SP0,X 
STX  SP 
JMP  NEXT 


0 

link  to  C@ 


get  low  byte 


get  high  byte 


FCB  2 
FCC  'DP  ' 
FDB  FTCH- 6 


LDX 

SP 

LDA 

#DP 

DECX 

STA 

SPO,X 

CLRA 

DECX 

STA 

SPO,X 

STX 

SP 

JMP 

NEXT 

FCB 

4 

FCC 

•HER' 

FDB 

DP2-6 

JMP 

DOCOL 

FDB 

DP  2 

FDB 

FTCH 

FDB 

EXIT 

FCB 

3 

FCC 

•NOT' 

DP 

link  to  @ 

push  address  of  DP  to  stack 
this  routine  knows  that  DP  is  on 
page  zero 


HERE 

Link  to  DP 


NOT 


End  Listing  One 


Listing  Two 


*  RAFOS  FORTH  VI. 0  26  March  1986  * 

*  * 

*  - ROM  #2  of  2  * 

*  * 

*  (C)  Copyright  1986,  Everett  Carter.  All  rights  reserved.  * 

*  This  FORTH  is  a  subset  of  the  FORTH-79  standard.  * 

*  Some  changes  have  been  made  in  order  to  save  on  * 

*  space  in  the  limited  memory  of  the  float.  * 

*  * 
***************************************************************** 


RCM 

EQU 

$1000 

RCM1 

EQU 

$1800 

ORG 

RCM 

CR 

EQU 

$0D 

LF 

EQU 

$0A 

BL 

EQU 

$20 

BS 

EQU 

$08 

DEL 

EQU 

$7F 

DDR 

EQU 

4 

PORTA 

EQU 

0 

PORTB 

EQU 

1 

PUT 

EQU 

PORTB 

INITSP 

EQU 

$7F 

STACK 

EQU 

INITSP-5 

MEMSIZ 

EQU 

$2000 

SPO 

EQU 

$0F00 

RPO 

EQU 

$0E00 

TIB 

EQU 

$0D80 

RCM  #2  start  address 
RCM  #1  start  address 


CARRIAGE  RETURN 
LINE  FEED 
BLANK 
Back  Space 
Delete 

DATA  DIRECTION  REGISTER  OFFSET 

I/O  PORT  0 
I/O  PORT  1 
SERIAL  I/O  PORT 

INITIAL  STACK  POINTER  VALUE 
TOP  OF  STACK 

MEMORY  ADDRESS  SPACE  SIZE 


*  RAM  VARIABLES 

* 

* 

ATEMP 

EQU 

$10 

TEMP  USED  IN  PUTDEC 

XTEMP 

EQU 

$11 

INDEX  TEMPORARY 

GETR 

EQU 

$12 

PICK  &  DROP  TEMPORARY 

COUNT 

EQU 

$16 

NUMBER  OF  BITS  LEFT  TO  get/send 

CHAR 

* 

EQU 

$17 

Current  input/output  character 

BYTCNT 

EQU 

$1E 

bytcnt . 

WTIME 

* 

EQU 

$20 

TIMER  INTERRUPT  FROM  WAIT  STATE 

PH 

EQU 

$21 

MI SC  SCRATCH  AREAS 

PL 

EQU 

$22 

TEMPA 

EQU 

$23 

TEMPB 

EQU 

$24 

QH 

EQU 

$25 

QL 

EQU 

$26 

TEMP 

EQU 

$27 

TERM 

* 

EQU 

$28 

* 

IN 

EQU 

$29 

Where  FORTH  will  look  for  input 

OUT 

EQU 

$2A 

COUNTR 

EQU 

$2B 

DP 

EQU 

$2C 

The  initial  Dictionary  pointer 

START 

* 

EQU 

$2E 

The  start  up  vector 

* 

IP 

EQU 

$30 

THE  FORTH  INSTRUCTION  POINTER 

RP 

EQU 

$32 

THE  RETURN  POINTER  OFFSET 

SP 

EQU 

$33 

THE  STACK  POINTER  OFFSET 

BASE 

EQU 

$34 

USER 

EQU 

$35 

The  space  for  USER  variables 

FENCE 

EQU 

0 

USER  +  0 

STATE 

EQU 

2 

USER  +  2 

FORTH 

EQU 

4 

USER  +  4 

CONTEXT 

EQU 

6 

USER  +  6 

CURRENT 

EQU 

8 

USER  +  8 

HID 

EQU 

$0A 

USER  +  $0A 

*  List  of 

previous  FORTH 

words  (ROM  1) 

DOCOL 

EQU 

$80 

DOCOL 

DOCOL1 

EQU 

DOCOL 

NEXT 

EQU 

$00  9E 

NEXT 

NEXT1 

EQU 

$00CE 

LOAD 

EQU 

$00D1 

GET 

EQU 

$00D5 

TYPE 

EQU 

$00DF 

TYPE 

FIN6 

EQU 

$0116 

<FIND> 

BRAN 

EQU 

$01A9 

BRAN 

ZBRAN 

EQU 

$19D2 

ZBRANCH 

ZBREX 

EQU 

ZBRAN+S12 

EXIT 

EQU 

$19F8 

EXIT 

EXE7 

EQU 

$1A10 

EXECUTE 

INLINE 

EQU 

$1A22 

EMIT 

EQU 

$1A79 

EMIT 

BL2 

EQU 

$1A8D 

BL 

WORD 

EQU 

$1AA4 

WORD 

MPY16 

EQU 

$1AFD 

NUM8 

EQU 

$1B27 

<NUMBER> 

DROP 

EQU 

$1BBE 

DROP 

CFCH 

EQU 

$1BCC 

c@ 

FTCH 

EQU 

$1BF2 

0 

DP2 

EQU 

$1C1D 

DP 

HERE 

EQU 

$1C34 

HERE 

NOT3 

EQU 

$1C42 

NOT 

ONEP 

EQU 

$1C5B 

1+ 

HID3 

EQU 

$1C78 

HID 

DOUSE 

EQU 

$1C7A 

DOUSE 

STA5 

EQU 

$1C91 

STATE 

CON7 

EQU 

$1C9B 

CONTEXT 

CUR7 

EQU 

$1CA5 

CURRENT 

FOR5 

EQU 

$1CAF 

FORTH 

STO 

EQU 

$1CB9 

t 

CSTO 

EQU 

$1CE4 

C! 

CCMA 

EQU 

$1D04 

, 

CCOMA 

EQU 

$1D37 

c. 

DUP3 

EQU 

$1D55 

DUP 

PLSTO 

EQU 

$1D75 

+  ! 

LAT6 

EQU 

$1DAE 

LATEST 

ALL  5 

EQU 

$1DBE 

ALLOT 

LIT3 

EQU 

$1DCC 

LIT 

SWAP 

EQU 

$1F07 

SWAP 

CRE6 

EQU 

$1FDE 

CREATE 

LOK  EQU  $1E53 
OK  EQU  LOK+1 
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OUTER  EQU  $1E57 


COLD  EQU  $1EA5 
WARM  EQU  S1EE6 
GETC  EQU  $1F43 
GETCHAR  EQU  GETC 
PUTC  EQU  $1F7A 

OUTCHAR  EQU  PUTC 
WAIT  EQU  $1FA8 

DELAY  EQU  WAIT 

CRLF  EQU  $1FC3 


RESET  EQU  COLD 
* 


QUES  LDA  DP  checks  for  errors  at  end  of  OUTER 

STA  GET+1 
LDA  DP+1 
STA  GET+2 
LDX  #1 
JSR  GET 

CMP  #$80  =  buffer  end  ? 

BNE  QERR 
QEXIT  IDX  SP 

* 

HI  EQU  LOK/$100*$100 

L  EQU  LOK-H1 

H  EQU  LOK/SIOO 

* 


IDA  #L 
DECX 

STA  SP0,X 
LDA  #H 
DECX 

STA  SP0,X 
STX  SP 
LDA  START 
STA  IP 
IDA  START+1 
STA  IP+1 
JMP  NEXT 
QERR  IDA  DP 

STA  LQAD+1 
IDA  DP+1 
STA  LOAD+2 
CLRX 
JSR  GET 
INCA 
INCA 

JSR  LOAD 
TAX 

LDA  #$3F 
JSR  LOAD 
IDX  SP 
IDA  DP+1 
DECX 

STA  SP0,X 
IDA  DP 
DECX 

STA  SP0,X 
STX  SP 
JMP  WARM 

* 

FCB  4 
FCC  ' QUI 1 
FDB  CRE6-6 
QUIT  BRA  QEXIT 
* 


QUIT 

link  to  CREATE 


FCB  6 
FCC  'TOG* 
FDB  QUIT- 6 
TOG 6  IDX  SP 

INCX 

IDA  SP0,X 
INCX 

STA  ATEMP 
LDA  SP0,X 
INCX 

STA  IDAD+l 
STA  GET+1 
LDA  SP0,X 
INCX 
STX  SP 
STA  LOAD+2 
STA  GET+2 
CLRX 
JSR  GET 
EOR  ATEMP 
JSR  LOAD 
JMP  NEXT 


TOGGLE 

link  to  QUIT 

drop  high  byte 

get  addr 


FCB  9 
FCC  1 IMM* 
FDB  TOG 6-6 
INM9  JMP  DOCOL 
FDB  LAT6 
FDB  LIT3 
FDB  $80 
FDB  TOG 6 
FDB  EXIT 


IMMEDIATE 
link  to  TOGGLE 
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FCB  5 

FCC  '-FI1 

-FIND 

FDB  11*19-6 

link  to  IMMEDIATE 

DFND 

JMP  DOCOL 

FDB  BL2 

FDB  WORD 

FDB  CON 7 

FDB  FTCH 

FDB  FTCH 

FDB  FIN6 

FDB  EXIT 

FCB  5 

FCC  'COU' 

COUNT 

FDB  DFND- 6 

link  to  -FIND 

CCU  5 

JMP  DOCOL 

FDB  DUP3 

FDB  ONEP 

FDB  SWAP 

FDB  CFCH 

FDB  EXIT 

FCB  1 

FCC  ' 0  ' 

0 

FDB  COU 5- 6 

link  to  COUNT 

ZERO 

LDX  SP 

CLRA 

DECX 

STA  SP0,X 

DECX 

STA  SPO,X 

STX  SP 

JMP  NEXT 

FCB  1 

FCC  ' 1  ' 

1 

FDB  ZERO- 6 

link  to  0 

ONE 

IDX  SP 

IDA  11 

DECX 

STA  SPO,X 

DECX 

CLRA 

STA  SP0,X 

STX  SP 

JMP  NEXT 

FCB  1 

FCC  ' 2  ' 

2 

FDB  ONE -6 

link  to  1 

TOO 

IDX  SP 

IDA  12 

DECX 

STA  SPO,X 

CLRA 

DECX 

STA  SPO,X 

STX  SP 

JMP  NEXT 

FCB  2 

FCC  '2+  1 

24- 

FDB  TOO- 6 

link  to  2 

TOOP 

LDX  SP 

INCX 

IDA  #2 

ADD  SPO,X 

STA  SPO,X 

point  to  low 

DECX 

point  to  high 

CLRA 

A=0  note  carry 

ADC  SPO,X 

STA  SPO,X 

is  not  affected 

JMP  NEXT 

FCB  $81 

FCC  ' [  ' 

[  (IMMEDIATE) 

FDB  TOOP -6 

link  to  2+ 

LBRAK 

JMP  DOCOL 

FDB  ZERO 

FDB  STA5 

FDB  STO 

FDB  EXIT 

FCB  1 

FCC  ' ]  ' 

] 

FDB  LBRAK- 6 

link  to  [ 

RBRAK 

JMP  DOCOL 

FDB  LIT3 

FDB  SCO 

FDB  STA 5 

FDB  STO 

FDB  EXIT 

FCB  11 

FCC  'DEF' 

DEFINITIONS 

FDB  RBRAK- 6 

link  to  ] 

DEFS 

JMP  DOCOL 

FDB  C0N7 

FDB  FTCH 

FDB  CUR7 

FDB  STO 

FDB  EXIT 

FCB  1 

FCC  ' +  ' 

+ 

FDB  DEFS-6 

link  to  DEFINITIONS 

PLUS 

IDX  SP 

LDA  SPO,X 

INCX 

STA  PH 

LDA  SPO,X 

INCX 

STX  SP 

INCX 

ADD  SPO#X 

STA  SPO,X 

IDX  SP 

IDA  PH 

ADC  SPO,X 

STA  SPO,X 

point  to  low  on  stack 

JMP  NEXT 

FCB  1 

FCC  ' 

- 

FDB  PLUS-6 

link  to  + 

MINUS 

LDX  SP 

LDA  SPO,X 

INCX 

STA  PH 

LDA  SPO,X 

INCX 

STA  PL 

STX  SP 

INCX 

LDA  SPO,X 

SUB  PL 

STA  SPO,X 

IDX  SP 

LDA  SPO,X 

SBC  PH 

STA  SPO,X 

point  to  low  on  stack 

JMP  NEXT 

FCB  2 

FCC  'U*  ' 

U* 

FDB  MINUS- 6 

link  to  - 

UMULT 

LDX  SP 

LDA  SPO,X 

INCX 

STA  PH 

LDA  SPO,X 

INCX 

STA  PL 

IDA  SPO,X 

INCX 

STA  QH 

LDA  SPO,X 

STA  QL 

STX  XTEMP 

JSR  MPY16 

LDX  XTEMP 

LDA  QL 

STA  SPO,X 

IDA  QH 

DECX 

STA  SPO,X 

push  low  word 

LDA  TEMPB 

DECX 

STA  SPO,X 

LDA  TEMPA 

DECX 

STA  SPO,X 

STX  SP 

push  high  word 

JMP  NEXT 

SEC 

EQU  PH 

DIV16 

LDA  SEC+2 

Dividend:  (H  to  L) 

LDX  SEC 

PL, PH, TEMPB,  TEMPA 

STX  SEC+2 

LSLA 

STA  SEC 

(SEC  +l,+0,+3,  +2) 

LDA  SEC+3 

LDX  SEC+1 

STX  SEC+3 

ROLA 

STA  SEC+1 

IDA  #$10 

STA  TEMP 

Divisor  is  QH,  QL 

DBEG 

ROL  SEC+2 

ROL  SEC+3 

LDA  SEC+2 

SUB  QL 

TAX 

LDA  SEC+3 

SBC  QH 

BCS  DSKIP 

STX  SEC+2 

STA  SEC+3 

SEC 

BRA  DSKIP+1 

DSKIP 

CLC 

ROL  SEC 

Quotient  (H,L)  is 

ROL  SEC+1 

SEC+1, SEC 

DEC  TEMP 

Remainder  (H, L)  is 

* 

BNE  DBEG 

RTS 

SEC+3, SEC+2 

FCB  5 

FCC  'U/M' 

U/MOD 

FDB  UMULT- 6 

link  to  U* 

UDMD 

IDX  SP 

LDA  SP0,X 

INCX 

STA  QH 

IDA  SP0,X 

INCX 

STA  QL 

LDA  SP0,X 

INCX 

divisor  to  Q 

STA  SEC+1 

high  word  to  P 

LDA  SP0,X 

INCX 

STA  SEC 

LDA  SP0,X 

INCX 

(SEC  +1,  +0) 

STA  SEC+3 

low  word  to  TEMPA/B 

LDA  SP0,X 

STA  SEC+2 

STX  SP 

BSR  DIV16 

IDX  SP 

(SEC  +3,  +2) 

LDA  SEC+2 

push  remainder 

STA  SP0,X 

LDA  SEC+3 

DECX 

STA  SP0,X 

(HL:  SEC+3,  +2) 

LDA  SEC 

push  quotient 

DECX 

STA  SPO,X 

LDA  SEC+1 

DECX 

STA  SPO,X 

STX  SP 

(HL:  SEC+1,  +0) 

JMP  NEXT 

FCB  4 

FCC  'S->' 

S->D 

FDB  UEMD-6 

link  to  U/MOD 

STOD 

IDX  SP 

LDA  SPO,X 
TSTA 

BPL  SPOS 

LDA  #$FF 

BRA  SEXIT 

SPOS 

CLRA 

SEXIT 

DECX 

STA  SPO,X 
DECX 

STA  SPO,X 

STX  SP 

JMP  NEXT 

FCB  3 

FCC  'PAD* 

PAD 

FDB  STOD- 6 

link  to  S->D 

PAD 

JMP  DOCOL 

FDB  HERE 

FDB  LIT3 

FDB  $0044 

FDB  PLUS 

FDB  EXIT 

FCB  2 

FCC  '<#  ' 

<# 

FDB  PAD-6 

link  to  PAD 

LSHP 

JMP  DOCOL 

FDB  PAD 

FDB  HID3 

FDB  STO 

FDB  EXIT 

FCB  4 

FCC  'OVE* 

OVER 

FDB  LSHP-6 

link  to  <# 

OVER 

IDX  SP 

INCX 

INCX 

IDA  SP0,X 
INCX 
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STA  ATEMP 
LDA  SPO,X 
LDX  SP 
DECX 

STA  SPO,X 
LDA  ATEMP 
DECX 

STA  SPO,X 
STX  SP 
JMP  NEXT 


FCB  2 
FCC  '#>  • 
FDB  OVER- 6 
SPGR  JMP  DOCOL 
FDB  DROP 
FDB  DROP 
FDB  HLD3 
FDB  FTCH 
FDB  PAD 
FDB  OVER 
FDB  MINI  IS 
FDB  EXIT 


#> 

link  to  OVER 


FCB  2  >R 

FCC  1 >R  ' 

FDB  SPGR-6  link  to  f> 

TOR  LDX  SP 

LDA  SP0,X 
INCX 

STA  ATEMP 
LDA  SP0,X 
INCX 
STX  SP 
LDX  RP 
DECX 

STA  RP0,X 
LDA  ATEMP 
DECX 

STA  RP0,X 
STX  RP 
JMP  NEXT 


FCB  2  R> 

FCC  1 R>  ' 

FDB  TOR-6  link  to  >R 

RTO  LDX  RP 

LDA  RPO,  X 
INCX 

STA  ATEMP 
LDA  RPO, X 
INCX 
STX  RP 
LDX  SP 
DECX 

STA  SP0,X 
LDA  ATEMP 
DECX 

STA  SP0,X 
STX  SP 
JMP  NEXT 


FCB  2 
FCC  1 R@  ' 
FDB  RTO- 6 
RFTCH  IDX  RP 

LDA  RPO,  X 
INCX 

STA  ATEMP 
IDA  RPO, X 
IDX  SP 
DECX 

STA  SP0,X 
LDA  ATEMP 
DECX 

STA  SP0,X 
STX  SP 
JMP  NEXT 


R0 

link  to  R> 
pop  high 

pop  low 

push  low 

push  high 


FCB  3 
FCC  'ROT* 
FDB  RFTCH- 6 
ROT  JMP  DOCOL 
FDB  TOR 
FDB  SWAP 
FDB  RTO 
FDB  SWAP 
FDB  EXIT 


ROT 

link  to  R@ 


FCB  4 
FCC  ' HOL' 
FDB  ROT- 6 
HOLD  JMP  DOCOL 
FDB  LIT3 
FDB  SFFFF 
FDB  HID3 
FDB  PLSTO 
FDB  HID3 
FDB  FTCH 
FDB  CSTO 
FDB  EXIT 


HOLD 

link  to  ROT 


(  -1  ) 


FCB  5  M/MOD 


MDM5 


BAS4 


SMUDG 


ABS 


ZLESS 


ZLPOS 

ZLXIT 


ZEQ 


ZEN 

ZEXIT 


LESS 


GREAT 


EQUAL 


FCC 

•M/M* 

FDB 

HOLD-6 

JMP 

DOCOL 

FDB 

TOR 

FDB 

ZERO 

FDB 

RFTCH 

FDB 

UDMD 

FDB 

RTO 

FDB 

SWAP 

FDB 

TOR 

FDB 

UDMD 

FDB 

RTO 

FDB 

EXIT 

FCB 

4 

FCC 

■BAS' 

FDB 

MDM5-6 

JMP 

DOCOL 

FDB 

LIT3 

FDB 

BASE 

FDB 

EXIT 

FCB 

6 

FCC 

•SMU* 

FDB 

BAS4-6 

JMP 

DOCOL 

FDB 

LAT6 

FDB 

LIT3 

FDB 

$0020 

FDB 

TOG6 

FDB 

EXIT 

FCB 

3 

FCC 

•ABS' 

FDB 

SMUDG -6 

IDX 

SP 

LDA 

SP0,X 

TSTA 

BPL  ABXIT 
COMA 

STA 

SP0,X 

INCX 

LDA 

SP0,X 

NEGA 

STA 

SP0,X 

JMP 

NEXT 

FCB 

2 

FCC 

•0<  ' 

FDB 

ABS -6 

LDX 

SP 

IDA 

SP0,X 

TSTA 

BPL 

ZLPOS 

IDA 

#$FF 

BRA 

ZLXIT 

CLRA 

STA 

SP0.X 

INCX 

STA 

SP0,X 

JMP 

NEXT 

FCB 

2 

FCC 

*0“  ' 

FDB 

ZLESS- 6 

LDX 

SP 

LDA 

SP0,X 

INCX 

ORA 

SP0,X 

BNE 

ZEN 

LDA 

#$FF 

BRA 

ZEXIT 

CLRA 

STA 

SP0,X 

DECX 

STA 

SP0,X 

JMP 

NEXT 

FCB 

1 

FCC 

'<  ' 

FDB 

ZEQ- 6 

JMP 

DOCOL 

FDB 

MINUS 

FDB 

ZLESS 

FDB 

EXIT 

FCB 

1 

FCC 

•>  ' 

FDB 

LESS- 6 

JMP 

DOCOL 

FDB 

SWAP 

FDB 

LESS 

FDB 

EXIT 

FCB 

1 

FCC 

•  =  • 

FDB 

GREAT- 6 

JMP 

DOCOL 

FDB 

MINUS 

FDB 

ZEQ 

FDB 

EXIT 

link  to  HOLD 


BASE 

link  to  M/MOD 


SMUDGE 

link  to  BASE 


ABS 

link  to  SMUDGE 


0< 

link  to  ABS 


0= 

link  to  0< 


link  to  0= 


> 

link  to  < 


link  to  > 
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FORTH  AT  SEA 

Listing  Two 

(Listing  continued,  text  begins  on 

page  40.) 

* 

FCB  3 

XOR 

FCC  '  ' 

FCB  4 

SIGN 

FCC  1 XOR' 

FDB  COLON- 6 

link  to  : 

FCC  ' SIG' 

FDB  AND3-6 

link  to  AND 

TICK 

JMP  DOCOL 

FDB  EQUAL-6 

link  to  * 

X0R3  LDX  SP 

FDB  DFND 

SIGN 

JMP  DOCOL 

LDA  SP0,X 

FDB  ZBRAN 

FDB  ZLESS 

INCX 

FDB  $0006 

FDB  ZBRAN 

INCX 

FDB  DROP 

FDB  $0008 

EOR  SP0,X 

FDB  EXIT 

FDB  LIT3 

STA  SP0,X 

FDB  QUES 

FDB  $002D 

DECX 

* 

FDB  HOLD 

LDA  SP0,X 

DOVAR 

LDX  SP 

FDB  EXIT 

INCX 

IDA  NEXT1+2 

low  byte  of  W 

* 

INCX 

ADD  13 

FCB  6 

NEGATE 

EOR  SP0,X 

DECX 

FCC  'NEG' 

STA  SP0,X 

STA  SP0,X 

FDB  SIGN- 6 

link  to  SIGN 

DECX 

LDA  NEXT1+1 

high  byte  of  W 

NEG6 

LDX  SP 

STX  SP 

ADC  10 

LDA  SP0,X 

JMP  NEXT 

DECX 

COMA 

* 

STA  SP0,X 

STA  SP0,X 

FCB  4 

DDUP 

STX  SP 

INCX 

FCC  ' DDU* 

JMP  NEXT 

LDA  SP0,X 

FDB  XOR3-6 

link  to  XOR 

* 

NEGA 

DDUP  JMP  DOCOL 

FCB  8 

VARIABLE 

STA  SP0,X 

FDB  OVER 

FCC  'VAR' 

JMP  NEXT 

FDB  OVER 

FDB  TICK- 6 

link  to  ' 

* 

FDB  EXIT 

VAR8 

JMP  DOCOL 

FCB  2 

+- 

* 

FDB  CRE6 

FCC  '+-  ' 

FCB  2 

IS 

FDB  LIT3 

compile  a  jump 

FDB  NEG  6- 6 

link  to  NEGATE 

FCC  '#S  ' 

FDB  $00CC 

to  DOVAR 

PLMI 

JMP  DOCOL 

FDB  DDUP -6 

link  to  DDUP 

FDB  CCCMA 

FDB  ZLESS 

SHRPS  JMP  DOCOL 

FDB  CCMP 

FDB  ZBRAN 

FDB  SHARP 

FDB  DOTAR 

FDB  $0004 

FDB  DDUP 

FDB  TWO 

FDB  NEG6 

FDB  OR2 

FDB  ALL5 

FDB  EXIT 

FDB  ZEQ 

FDB  EXIT 

* 

FDB  ZBRAN 

* 

FCB  1 

* 

FDB  $FFF6 

DOCON 

LDA  NEXT1+2 

put  W+2  into  GET 

FCC  ' #  ' 

FDB  EXIT 

ADD  #3 

FDB  PLMI -6 

link  to  +- 

* 

STA  GET+2 

SHARP 

JMP  DOCOL 

FCB  1 

IDA  NEXT1+1 

FDB  BAS4 

FCC  ' 

ADC  10 

FDB  CFCH 

FDB  SHRPS- 6 

link  to  IS 

STA  GET+1 

FDB  MDM5 

DOT  JMP  DOCOL 

LDX  11 

FDB  ROT 

FDB  DUP3 

JSR  GET 

get  low  byte  of 

FDB  LIT3 

FDB  DUP3 

constant 

FDB  $0009 

FDB  ABS 

LDX  SP 

FDB  OVER 

FDB  STOD 

DECX 

FDB  LESS 

FDB  LSHP 

STA  SP0,X 

FDB  ZBRAN 

FDB  SHRPS 

STX  SP 

FDB  $0008 

FDB  ROT 

CLRX 

FDB  LIT3 

FDB  SIGN 

JSR  GET 

then  the  high  byte 

FDB  $0007 

FDB  SPGR 

LDX  SP 

FDB  PLUS 

FDB  TYPE 

DECX 

FDB  LIT3 

FDB  DROP 

STA  SP0,X 

FDB  $0030 

FDB  BL2 

STX  SP 

FDB  PLUS 

FDB  EMIT 

JMP  NEXT 

FDB  HOLD 

FDB  EXIT 

* 

FDB  EXIT 

* 

FCB  8 

CONSTANT 

★ 

FCB  7 

COMPILE 

FCC  'CON' 

FCB  2 

OR 

FCC  'COM' 

FDB  VAR8-6 

link  to  VARIABLE 

FCC  'OR  ' 

FDB  DOT- 6 

link  to  . 

CON  8 

JMP  DOCOL 

FDB  SHARP-6 

link  to  1 

CCMP  JMP  DOCOL 

FDB  CRE6 

OR2 

LDX  SP 

FDB  RTO 

FDB  LIT3 

compile  a  jump 

LDA  SP0,X 

FDB  DUP3 

to  DOCON 

INCX 

FDB  TWOP 

FDB  $00CC 

INCX 

FDB  TOR 

FDB  CCCMA 

ORA  SP0,X 

FDB  FTCH 

FDB  CCMP 

STA  SP0,X 

FDB  CCMA 

FDB  DOCON 

DECX 

FDB  EXIT 

FDB  CCMA 

LDA  SP0,X 

* 

FDB  EXIT 

INCX 

FCB  $81 

;  (IMMEDIATE) 

* 

INCX 

FCC  ' ;  ' 

FCB  1 

* 

ORA  SP0,X 

FDB  CCMP -6 

link  to  COMPILE 

FCC  ' *  ' 

STA  SP0,X 

SEMI  JMP  DOCOL 

FDB  CON8-6 

link  to  CONSTANT 

DECX 

FDB  CCMP 

MULT 

JMP  DOCOL 

STX  SP 

FDB  EXIT 

FDB  UMULT 

JMP  NEXT 

FDB  SMUDG 

FDB  DROP 

* 

FDB  LBRAK 

FDB  EXIT 

FCB  3 

AND 

FDB  EXIT 

* 

FCC  'AND' 

* 

FCB  $85 

[COMPILE]  IMMEDIATE 

FDB  OR2-6 

link  to  OR 

FCB  1 

FCC  ' [CO' 

AND3 

LDX  SP 

FCC  •:  • 

FDB  MULT-6 

link  to  * 

LDA  SP0,X 

FDB  SEMI-6 

link  to  ; 

BCOM9 

JMP  DOCOL 

INCX 

COLON  JMP  DOCOL 

FDB  TICK 

INCX 

FDB  CUR7 

FDB  CCMA 

AND  SP0,X 

FDB  FTCH 

FDB  EXIT 

STA  SP0,X 

FDB  CON 7 

* 

DECX 

FDB  STO 

FCB  $85 

BEGIN  IMMEDIATE 

LDA  SP0,X 

FDB  CRE6 

FCC  'BEG' 

INCX 

FDB  SMUDG 

FDB  BCOM9-6 

link  to  [COMPILE] 

INCX 

FDB  CCMP 

BEGN 

JMP  DOCOL 

AND  SP0,X 

JMP  DOCOL 

FDB  HERE 

STA  SP0,X 

FDB  RBRAK 

FDB  EXIT 

DECX 

FDB  EXIT 

* 

STX  SP 

* 

FCB  $85 

AGAIN  IMMEDIATE 

JMP  NEXT 

FCB  $81 

'  (IMMEDIATE) 

FCC  'AGA' 

* 

FCB  $27 

FDB  BEGN-6 

link  to  BEGIN 
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AGAIN 


UNTIL 


IF2 


THEN 


ELSE 


WHILE 


REPET 


BDOTQ 


TIB3 


FRIN 


JMP 

DOCOL 

FDB 

CCMP 

FDB 

BRAN 

FDB 

HERE 

FDB 

MINUS 

FDB 

CCMA 

FDB 

EXIT 

FCB 

$85 

UNTIL  IMMEDIATE 

FCC 

'UNT' 

FDB 

AGAIN- 6 

link  to  AGAIN 

JMP 

DOCOL 

FDB 

CCMP 

FDB 

ZBRAN 

FDB 

HERE 

FDB 

MINUS 

FDB 

CCMA 

FDB 

EXIT 

FCB 

$82 

IF  IMMEDIATE 

FCC 

•IF  ' 

FDB 

UNTIL- 6 

link  to  UNTIL 

JMP 

DOCOL 

FDB 

CCMP 

FDB 

ZBRAN 

FDB 

HERE 

FDB 

ZERO 

FDB 

CCMA 

FDB 

EXIT 

FCB 

$84 

THEN  IMMEDIATE 

FCC 

•THE' 

FDB 

IF2-6 

link  to  IF 

JMP 

DOCOL 

FDB 

HERE 

FDB 

OVER 

FDB 

MINUS 

FDB 

SWAP 

FDB 

STO 

FDB 

EXIT 

FCB 

$84 

ELSE  IMMEDIATE 

FCC 

•ELS' 

FDB 

THEN- 6 

link  to  THEN 

JMP 

DOCOL 

FDB 

CCMP 

FDB 

BRAN 

FDB 

HERE 

FDB 

ZERO 

FDB 

CCMA 

FDB 

SWAP 

FDB 

THEN 

FDB 

EXIT 

FCB 

$85 

WHILE  IMMEDIATE 

FCC 

•WHI* 

FDB 

ELSE- 6 

link  to  ELSE 

JMP 

DOCOL 

FDB 

IF2 

FDB 

EXIT 

FCB 

$86 

REPEAT  IMMEDIATE 

FCC 

'REP' 

FDB 

WHILE-6 

link  to  WHILE 

JMP 

DOCOL 

FDB 

TOR 

FDB 

AGAIN 

FDB 

RTO 

FDB 

THEN 

FDB 

EXIT 

FCB 

4 

<."> 

FCC 

FDB 

REPET-6 

link  to  REPEAT 

JMP 

DOCOL 

FDB 

RFTCH 

FDB 

CCU  5 

FDB 

DUP3 

FDB 

ONEP 

FDB 

RTO 

FDB 

PLUS 

FDB 

TOR 

FDB 

TYPE 

FDB 

EXIT 

FCB 

3 

TIB 

FCC 

'TIB* 

FDB 

BDOTQ- 6 

link  to  <."> 

JMP 

DOCOL 

FDB 

LIT3 

FDB 

TIB 

FDB 

EXIT 

FCB 

3 

>IN 

FCC 

•>IN* 

FDB 

TIB3-6 

link  to  TIB 

JMP 

DOCOL 

FDB 

LIT3 

FDB 

IN 

FDB 

EXIT 

FCB 

7 

•STREAM 

FCB 

$27 

FORTH  AT  SEA 

Listing  Two 

(Listing  continued, 

text  begins  on  page  40.) 

FCC  'ST' 

FDB  FRIN- 6 

link  to  >IN 

TSTRM 

JMP  DOCOL 

FDB  TIB3 

FDB  FRIN 

FDB  CFCH 

FDB  PLUS 

FDB  EXIT 

FCB  4 

FCC  ' <D0‘ 

<D0> 

FDB  TSTRM- 6 

link  to  'STREAM 

BDO 

IDA  #4 

STA  COUNTR 

ADD  SP 

STA  SP 

make  2  artificial  pops 

DOAGIN 

LDX  SP 

move  limit 

DECX 

then  index 

LDA  SP0,X 

from  SP 

STX  SP 

LDX  RP 

DECX 

STA  RP0,X 

STX  RP 

DEC  COUNTR 

BNE  DOAGIN 

to  RP 

LDA  #4 

ADD  SP 

STA  SP 

adjust  SP 

JMP  NEXT 

FCB  6 

FCC  ' <LO' 

<L00P> 

FDB  BDO- 6 

link  to  <D0> 

BLOP 

CLR  PH 

IDA  #1 

STA  PL 

set  increment  to  1 

LOOPS 

LDX  RP 

increment  index 

INCX 

by  value 

LDA  PL 

ADD  RPO, X 

STA  RP0,X 

DECX 

IDA  PH 

ADC  RPO, X 

in  P  H/L 

STA  RP0,X 

INCX 

LDA  RPO,  X 

INCX 

INCX 

SUB  RP0,X 

LDX  RP 

LDA  RP0,X 

test  index- limit 

INCX 

INCX 

SBC  RP0,X 

EOR  PH 

also  check  increment  sign 

BMI  LAGIN 

INCX 

INCX 

STX  RP 

JMP  ZBREX 

loop  again  if  negative 

LAG  IN 

JMP  BRAN 

FCB  7 

<+LOOP> 

FCC  ' <+L* 

FDB  BLOP -6 

link  to  <LOOP> 

BP  LOP 

LDX  SP 

LDA  SP0,X 

INCX 

STA  PH 

set  increment 

LDA  SP0,X 

INCX 

STA  PL 

STX  SP 

from  the  stack 

BRA  LOOPS 

FCB  $82 

FCC  'DO  ' 

DO  IMMEDIATE 

FDB  BPLOP-6 

link  to  <+LOOP> 

DO 

JMP  DOCOL 

FDB  CCMP 

FDB  BDO 

FDB  HERE 

FDB  EXIT 

FCB  $84 

FCC  'LOO' 

LOOP  IMMEDIATE 

FDB  DO- 6 

link  to  DO 

LOOP 

JMP  DOCOL 

FDB  CCMP 

FDB  BLOP 

FDB  HERE 

FDB  MINUS 
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FDB  CCMA 

FDB  EXIT 

FCB  $85 

+IOOP  IMMEDIATE 

FCC  ' +LO' 

FDB  LOOP- 6 

link  to  LOOP 

PLOOP 

JMP  DOCOL 

FDB  CCMP 

FDB  BP LOP 

FDB  HERE 

FDB  MINUS 

FDB  CCMA 

FDB  EXIT 

FCB  7 

DNEGATE 

FCC  'DNE* 

FDB  P LOOP-6 

link  to  +LOOP 

DNEG7 

LDA  #3 

DNLP 

STA  COUNTR 

LDX  SP 

LDA  SP0,X 

ones  complement 

CCMA 

three  bytes 

STA  SP0,X 

INCX 

DEC  COUNTR 

BNE  DNLP 

LDA  SP0,X 

twos  complement 

NEGA 

the  fourth 

STA  SP0,X 

JMP  NEXT 

FCB  $81 

I  IMMEDIATE 

FCC  ' I  ' 

FDB  DNEG7-6 

link  to  DNEGATE 

11 

JMP  DOCOL 

• 

FDB  CCMP 

FDB  RFTCH 

FDB  EXIT 

* 

END 

$ 

End  Listings 
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FORTH  WINDOWS 


Listing  One  (Text  begins  on  page  46.) 


file:  WINDOW. BLK  Block:  0 


window  program 


cl  11/10/85 


1  #  cx  mov  9  #  ah  mov 


»i  push  16  int 


\  char  in  al,  func.  code  in  ah 
\  count-1,  write  char/attrib 


3  4  ah  mov  16  int  dl  inc  2  #  ah  mov  16  int 


si  pop  next 


\  inc  cursor  position 


Craig  A.  Lindley 
Manitou  Springs 


file:  WINDOW. BLK 


November  1985 


file:  WINDOW. BLK 


\  window  routines 
\  window  load  screen 


cl  11/10/85 


\  window  routines  cl 

\  read  char  and  attrib  at  cursor  position 
code  rdchra  \  —  char/attrib 

0  I  bh  mov  8  ♦  ah  mov  \  pg  -0  func.  code  -  8 

si  push  16  int  si  pop  \  do  video  interrupt 

lpush  \  char/attrib  to  stk 


cl  11/10/85 


warning  off 


. (  Compiling  window  package  and  demo  program  ) 


\  put  char  with  attrib  at  x,y 


>r  at  r>  1  chra  ; 


\  x  y  char/attrib  — 


warning  on 


file:  WINDOW. BLK  Block:  2 


\  get  char  with  attrib  at  x,y 


\  x  y  —  char/attrib 


file:  WINDOW. BLK  Block:  5 


\  case  statement 

\  Dr.  Charles  Eakers  Forth  Dimensions  Vol  2,  Num  3 
:  ?comp  state  0  not  abort"  Compilation  only"  ; 

:  ?pairs  <>  abort"  Bad  CASE  statement" 


cl  11/10/85 


\  window  routines 


\  draw  count  #  of  chars/attrib  starting  at  x,y 


cl  11/10/85 


\  x  y  char/attrib  count  — 


>r  >r  at  r>  r>  chra  ; 


case  ?comp  csp  0  !csp  4  ;  immediate 


compile  over  compile  -  compile  ?branch 
here  0  ,  compile  drop  5  ;  immediate 
:  endof  5  ?pairs  compile  branch  here  0  , 
swap  >resolve  4  ;  immediate 
:  endcase  4  ?pairs  compile  drop 
begin  sp0  csp  0  <> 
while  >resolve  repeat 
csp  !  ;  immediate 


\  scroll  specified  window  up  n  lines 

code  Bcrlup  \  xul  yul  xlr  ylr  cnt  attrib  ■ 

bx  pop  bl  bh  mov  di  pop  \  bh  attrib  si  *  of  lines 

dx  pop  dl  dh  mov  ax  pop  al  dl  mov  \  dx  has  lr  x  y 

cx  pop  cl  ch  mov  ax  pop  al  cl  mov  \  cx  has  ul  x  y 

di  ax  mov  si  push  bp  push  \  save  regs 


6  #  ah  mov  16  int 
bp  pop  si  pop  next 


\  ax  *  of  lines  func.  code  ah 
\  restore  forth' s  regs 


file:  WINDOW. BLK 


\  window  routines 


cl  11/10/85 


\  write  count  #  of  chars  with  attrib  at  cursor  position 
code  chra  \  char/attrib  count  — 


cx  pop  ax  pop  ah  bl  mov 
bh  bh  xor  9  #  ah  mov 


si  push  16  int  si  pop 


\  get  count  in  cx,  attrib  in  bl 
\  char  in  al,  func.  code  in  ah 


\  do  video  interrupt 


file:  WINDOW. BLK 


\  window  routines 
\  memory  management  support 


\  tell  DOS  to  allociate  memory  bytes 


cl  11/10/85 


\  #  bytes  —  seg  T 


bx  pop  4  ♦  cl  mov  bx  cl  shr  \ 


—  raaxp  error  code  F 


bx  inc  72  #  ah  mov  33  int  \  int  21h  func.  code  48h 

u<  if  bx  push  ax  push  ax  ax  xor  \  if  C  then  error 
else  ax  push  -1  #  ax  mov  then  lpush 


\  write  1  char  with  attrib  at  cursor  -  update  cursor  position 


ax  pop  ah  bl  mov  bh  bh  xor 


\  char/attrib  — 

\  char  in  al,  attrib  in  bl 


\  tell  DOS  to  free  memory  segment 


(continued  on  page  98) 
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_ FORTH  WINDOWS 

Listing  One  (Listing  continued,  text  begins  on  page  46.) 


ax  pop  ax  ea  raov  \  —  error  code  F 

73  #  ah  mov  33  int  \  int  21h  func.  code  49h 

u<  if  ax  push  ax  ax  xor  \  if  C  then  error 

else  -1  #  ax  mov  then  lpush 
end-code 


file:  WINDOW. BLK  Block:  7 

\  window  routines  cl  11/10/85 

\  memory  management  support 

\  tell  DOS  to  shrink  or  expand  allociated  memory  segment 

code  setblock  \  #  bytes  —  T 

cs  ax  mov  ax  es  raov  \  —  maxp  error  code  F 

bx  pop  4  #  cl  mov  bx  cl  shr  \  bx  has  #  of  paragraphs 

bx  inc  74  #  ah  raov  33  int  \  int  21h  func.  code  4 Ah 

u<  if  bx  push  ax  push  ax  ax  xor  \  if  C  then  error 
else  -1  #  ax  mov 
then  lpush 
end-code 


file:  WINDOW. BLK  Block:  8 

\  window  routines  cl  11/10/85 

\  extended  word  fetch  and  store  words 
\  fetch  word  from  extended  memory 
code  eg  \  seg  addr  —  n 

bx  pop  es  pop  \  seg  in  es  addr  in  bx 

es :  0  [bx)  ax  mov  \  get  the  data  on  stk 

lpush 
end-code 

\  store  word  in  extended  memory 

code  e!  \  n  seg  addr  — 

bx  pop  es  pop  ax  pop 

ax  es:  0  [bx]  mov  \  store  the  data 

next 

end-code 


file:  WINDOW. BLK  Block:  9 

\  window  routines  cl  11/10/85 

\  read  current  cursor  location 

code  rdcur  \  —  x  y 

si  push  0  #  bh  raov  3  #  ah  mov  \  int  lOh  func.  code  3 
16  int  si  pop  ah  ah  xor 
dl  al  mov  ax  push  dh  al  mov 
lpush 
end-code 


file:  WINDOW. BLK  Block:  10 

\  window  routines  cl  11/10/85 


\  window  control  block  (web)  record  layout 


0 

constant 

ulx 

2 

constant 

uly 

\ 

upper  left  corner 

4 

constant 

width 

6 

constant 

height 

\ 

width  and  height 

8 

constant 

curx 

10 

constant 

cury 

\ 

current  cursor  pos 

12 

constant 

oldx 

14 

constant 

oldy 

\ 

old  cursor  pos. 

16 

constant 

buf seg 

18 

constant 

oldwcbseg 

\ 

seg  storage 

20 

constant 

attrib 

\ 

window  attrib. 

22 

constant 

record 

size 

\ 

size  of  record 

15 

constant 

boarder 

\ 

boarder  attribute 

hex 

b800  constant  v_seg  \  video  memory  start 

variable  webseg  \  current  web  seg 

decimal  \  storage 

file:  WINDOW. BLK  Block:  11 

\  window  routines  cl  11/10/85 

\  extended  memory  fetch  and  store  words 

\  store  word  n  at  addr  in  current  web 
:  webseg!  \  n  addr  — 

webseg  0  swap  e!  ;  \  store  at  addr  in  web  seg 

\  fetch  word  from  addr  in  current  web 
:  websegg  \  addr  —  n 

webseg  0  swap  eg  ;  \  fetch  from  addr  in  web  seg 


file:  WINDOW. BLK  Block:  12 

\  window  routines  cl  11/10/85 

\  window  frame  drawing  routines 
:  top 

ulx  websegg  uly  websegg  [  201  boarder  256  *  +  ]  literal  putch 
ulx  websegg  1+  uly  websegg  [  205  boarder  256  *  +  ]  literal 
width  websegg  draw_row 

ulx  websegg  width  websegg  +  1+  uly  websegg 
[  187  boarder  256  *  +  )  literal  putch  ; 

:  bot  t  ora 

ulx  websegg  uly  websegg  height  websegg  +  1+ 

[  200  boarder  256  *  +  ]  literal  putch 

ulx  websegg  1+  uly  websegg  height  websegg  +  1+ 

[  205  boarder  256  *  +  )  literal  width  websegg  draw_row 

ulx  websegg  width  websegg  +  1+  uly  websegg  height  websegg  +  1+ 

[  188  boarder  256  *  +  ]  literal  putch  ; 


file:  WINDOW. BLK  Block:  13 

\  window  routines  cl  11/10/85 

\  window  frame  drawing  routines 
:  sides 

uly  websegg  height  websegg  +  1+  uly  websegg  1+ 
do  ulx  websegg  i  [  186  boarder  256  *  +  ]  literal  putch 
ulx  websegg  width  websegg  +  1+  i 
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[  186  boarder  256  *  +  ]  literal  putch 
loop  ; 


file:  WINDOW. BLK  Block:  14 

\  window  routines 

\  temporary  data  storage  areas 
\  used  by  scn->buf  and  buf->scn 


label  8ave_h  nop  nop  \ 
label  save_w  nop  nop  \ 
label  8ave_ptr  nop  nop  \ 
label  save_8i  nop  nop  \ 
label  save_ds  nop  nop  \ 


cl  11/10/85 


storage  for  height  parameter 
storage  for  width  parameter 
storage  for  start  pointer 
storage  for  forths  IP  reg 
storage  for  current  da  reg 


file:  WINDOW. BLK  Block:  15 

\  window  routines  cl  11/10/85 

\  move  data  from  screen  to  memory  buffer 

hex 

code  scn->buf  \  x  y  width  height  seg  — 

cld  es  pop  0  #  di  mov  save_h  #)  pop  save_w  #)  pop  ax  pop 
aO  #  bl  mov  bl  mul  bx  pop  bx  shl  bx  ax  add  ax  save_ptr  #)  mov 
si  save_si  #)  mov  ds  ax  mov  ax  save_ds  #)  mov  v_seg  #  ax  mov 
ax  ds  mov  cs:  save_ptr  #)  si  mov  cs :  save_h  #)  cx  mov 
here  cx  push  cs:  save_w  #)  cx  mov  rep  movs 

cs:  save_ptr  #)  si  mov  aO  ♦  si  add  si  cs:  save_ptr  ♦)  mov 
cx  pop 

loop 

cs :  save_ds  ♦  )  ax  mov  ax  ds  mov 

save_si  #)  si  mov 

next 

end-code 


file:  WINDOW. BLK  Block:  16 

\  window  routines  cl  11/10/85 

\  move  data  from  memory  buffer  to  screen 

code  buf->scn  \  seg  x  y  width  height  — 

cld  save_h  *)  pop  save_w  #)  pop  ax  pop  aO  i  bl  mov 
bl  mul  bx  pop  bx  shl  bx  ax  add  ax  save_ptr  #)  mov 
si  save_si  #)  mov  ds  ax  mov  ax  save_ds  #)  mov  ax  pop  ax  ds  mov 
v_seg  #  ax  mov  ax  es  mov  0  #  si  mov  cs:  save_ptr  #)  di  mov 
cs:  save_h  #)  cx  mov 

here  cx  push  cs:  save_w  #)  cx  mov  rep  movs 

cs:  8ave_ptr  #)  di  mov  aO  #  di  add  di  cs:  save_ptr  #)  mov 
cx  pop 

loop 

cs:  save_ds  #)  ax  mov  ax  ds  mov  save_si  #)  si  mov 
next 

end-code 

decimal 


file:  WINDOW. BLK  Block:  17 

\  window  routines  cl  11/10/85 

\  lowest  level  window  routine 


99 

506 


Dr.  Dobb's  Journal,  July  1986 


FORTH  WINDOWS 


Listing  One  (Listing  continued,  text  begins  on  page  46.) 


\  moves  screen  data  to  memory  buffer 
\  and  then  draws  the  actual  window  frame 


else  cr  . "  ULX  and/or  WIDTH  incorrect"  wfit 


( (window) )  \  move  data  scn->buf 

ulx  wcbsegg  uly  wcbsegg  \  x  y  coordinates 

width  wcbsegg  2+  height  wcbsegg  2+  \  width  height 
bufseg  wcbsegg  scn->buf  \  get  buf  seg  addr 

top  sides  bottom  ; 


else  cr  . "  ULY  and/or  HEIGHT  incorrect"  wfit 


else  cr  ."  Incorrect  #  of  parameters  specified"  quit 


file:  WINDOW. BLK 


file:  WINDOW. BLK 


\  window  routines 


\  clear  window  routine 
:  clr  window 


cl  11/10/8S 


ulx  wcbsegg  1+  \  upper  left  corner  x 
uly  wcbsegg  1+  \  upper  right  corner  y 
ulx  wcbsegg  width  wcbsegg  +  \  lower  left  corner  x 
uly  wcbsegg  height  wcbsegg  +  \  lower  right  corner  y 
0  attrib  wcbsegg  scrlup  \  scroll  entire  window 


0  curx  wcbseg! 
0  cury  wcbseg! 


file:  WINDOW. BLK 


\  home  window  cursor 


\  window  routines 

\  close  the  current  window  (defined  by  wcbseg  data) 
\  free  web  and  buffer  memory  then  unlink  window 
:  close  window  \  — 


wcbseg  g  0  <> 
if  bufseg  wcbsegg 


cl  11/10/85 


\  if  window  exists 
\  get  buffer  seg  addr 


ulx  wcbsegg  uly  wcbsegg  \  get  x,y  corner 
width  wcbsegg  2+  height  wcbsegg  2+ 


\  mov  data  back  to  screen 


oldx  wcbsegg  oldy  wcbsegg  at 

bufseg  wcbsegg  free  drop  \  free  buffer  seg  memory 


wcbseg  g  free  drop 


\  free  web  seg  memory 


oldwcbseg  wcbsegg  wcbseg  !  \  unlink  this  window 


\  if  no  current  window 


cr  ."  No  open  windows  !"  cr 


\  window  routines 


record  size  calloc 


cl  11/10/85 

\  x  y  width  height  attrib  —  f 
\  try  to  allociate  space  for  web 


if  wcbseg  g  >r  wcbseg  !  r>  \  if  successful  store  seg  var 
oldwcbseg  wcbseg!  attrib  wcbseg!  \  save  attrib  in  web 
2dup  2+  swap  2+  *  2*  calloc  \  alloc  space  for  screen  buf 


if  bufseg  wcbseg! 


\  save  buffer  seg 


height  wcbseg!  width  wcbseg!  \  save  parameters  in 

uly  wcbseg!  ulx  wcbseg!  \  new  web 

rdcur  oldy  wcbseg!  oldx  wcbseg!  \  get  old  cursor  pos. 
((window))  clr_window  true  \  move  data  draw  frame 

else  ."  buffer  alloc,  failure"  cr  \  if  no  memory 
wcbseg  g  free  drop  drop  0  \  free  web  memory 


else  ."  web  alloc,  failure"  drop  drop  0 


\  return  flag 


file:  WINDOW. BLK  Block:  20 


file:  WINDOW. BLK 


\  window  routines 
\  position  cursor  in  window 


cl  11/10/85 


\  if  parameters  out  of  range  do  the  best  we  can  and  still 
\  stay  in  the  window 


swap  dup  abs  width  wcbsegg  \  req.  x  in  window  ? 

1-  >  \  if  not  then 

if  drop  width  wcbsegg  1-  then  \  set  x  to  max  in  window 


curx  wcbseg! 

dup  abs  height  wcbsegg 


\  save  new  cursor  x  position 
\  req  y  in  window  ? 

\  if  not  then 


if  drop  height  wcbsegg  1-  then  \  set  y  to  max  in  window 


cury  wcbseg! 


\  save  new  cursor  y  position 


curx  wcbsegg  ulx  wcbsegg  +1+  \  actual  cursor  position 
cury  wcbsegg  uly  wcbsegg  +1+  \  calculation 


\  window  routines 
\  window  parameter  checking 


cl  11/10/85 


file:  WINDOW. BLK  Block:  23 


abort"  Window  won't  fit  on  ert"  ; 


:  open_window 


\  x  y  width  height  attrib  —  f 


\  window  routines 
\  read  window  cursor  position 


cl  11/10/85 


if  >r  4dup  rot  +  2+  24  <- 
if  +  2+  79  <- 


curx  wcbsegg  cury  wcbsegg 


if  r>  (window) 


\  read  char/attrib  of  character  at  cursor  in  window 
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:  rdwcha  \  x  y  —  char/attrib 

wat  rdchra  ; 

\  scroll  window  up  for  blank  line  at  bottom 

:  scroll_window  \  — 

ulx  wcbsegg  1+  uly  wcbsegg  1+  \  upper  left  corner  to  scroll 

ulx  wcbsegg  width  wcbsegg  +  \  lower  right  x  coordinate 

uly  wcbsegg  height  wcbsegg  +  \  lower  right  y  coordinate 

1  attrib  wcbsegg  scrlup  ;  \  up  1  line 


file:  WINDOW. BLK  Block: 

24 

\  window  routines 

cl  11/10/85 

\  do  carrage  return  in  the  current  window 

:  crout  rdwcur  nip  0  swap  wat 

•• 

\  carrage  ret  in  window 

\  do  a  line  feed  in  the  current 

window 

:  If out  rdwcur  1+  dup 

height  wcbsegg  1-  > 

\  cursor  out  of  window 

if  1-  scroll  window  then 

\  if  so  scroll  the  window  up 

wat  ; 

\  place  the  cursor  in  window 

\  do  a  back  space  in  the  current 

window 

:  bsout  rdwcur  over  0<> 

\  backspace  cursor  in  window 

if  swap  1-  swap  wat  then  ; 

\  ring  the  bell 

:  bell  7  (emit)  ; 

\  sound  the  horn 

file:  WINDOW. BLK  Block: 

25 

\  window  routines 

cl  11/10/85 

:  wemit  dup  32  < 

\ 

char  — 

if  case 

\ 

if  control  char  process  it 

7  of  bell  endof 

\ 

if  bell  then 

8  of  bsout  endof 

\ 

if  backspace  then 

10  of  lfout  endof 

\ 

if  linefeed  then 

13  of  crout  endof 

\ 

if  carrage  ret  then 

endcase 

else 

\ 

else  its  a  display  char 

attrib  wcbsegg  256  *  + 

\ 

char  now  char/attrib 

rdwcur  rot  chra+ 

\ 

output  char  adv.  cursor 

drop  dup  width  wcbsegg  1- 

- 

\  if  at  end  of  window  line 

if  drop  lfout  crout 

\ 

do  lfcr  to  next  line 

else  1+  curx  wcbseg! 

\ 

store  new  x  coordinate 

then 

then  ; 

file:  WINDOW. BLK  Block: 

26 

\  window  routines 

cl  11/10/81 

:  wcr  13  wemit  10  wemit  ; 

\ 

window  carrage  return 

:  wtype  0 

\ 

window  equiv.  of  type 

?do  count  wemit  loop  drop  ; 


\  use  memory  manager  to  give  forth  a  full  64k  segment 

(continued  on  next  page) 


FORTH  WINDOWS 

Listing  One 

(Listing  continued,  text  begins  on  page  46.) 


:  initialize 

cr  . "  Memory  management 
-1  setblock 
if 

. "  initialized" 

0  wcbseg  J 
else 

"  error"  quit 
then  cr  ; 


\  — 

\  output  1/2  msg 
\  request  FFFF  bytes 
\  if  successful 
\  output  message  and 
\  initialize  link  variable 

\  abort  program 


file:  WINDOW. BLK  Block:  27 


\  window  demo  cl  11/10/85 

\  window  equivalents  of  standard  Forth  words 


wlist  block  16  0 
do  dup  i  c/1  *  +  c/1 
-trailing  wtype  wcr 
loop  drop  ; 

wtriad  3/3*3  bounds 
do  i  wlist 
wcr  wcr 
loop  ; 


\  window  equiv.  of  list 


\  window  equiv.  of  triad 
\  list  screen  in  window 
\  add  a  couple  of  cr's 


file:  WINDOW. BLK  Block:  28 

\  window  demo  cl  11/10/85 

\  window  canned  messages 
:  msgl 

"  This  could  be  your  application  program  I  "  wtype  ; 

:  msg2  "  Ain't  this  window  package  something!  "  wtype  ; 

:  msg3  "  **  Window  4  **  "  wtype  ; 

:  msglout  0  0  wat  \  output  msgl  20  times 

20  0  do  msgl  loop  ; 

:  rasg2out  0  0  wat  \  output  msg2  10  times 

10  0  do  rasg2  loop  ; 

:  msg3out  0  0  wat  \  output  msg3  80  times 

80  0  do  msg3  loop  ; 


file:  WINDOW. BLK  Block:  29 

\  window  demo  cl  11/10/85 

\  video  attribute  constants 

7  constant  normal  15  constant  high_int 

112  constant  reverse  128  constant  blink 

:  fill_crt  00  \  fill  crt  with  rev  video  A's 

[  ascii  A  reverse  256  *  +  ]  \  calculate  char/attrib  code 
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literal  2048  draw_row  ; 

:  wait  10000  0  do  noop  loop  ;  \  timing  loop 


file:  WINDOW. BLK  Block:  30 

\  window  demo  cl  11/10/85 

\  define  the  four  windows  used  in  the  demo  program 

:  windowl  \  define  window  #1 

0  0  20  10  reverse  open_window  ; 

:  window2  \  define  window  #2 

2  1  70  8  normal  open_window  ; 

:  window3  \  define  window  #3 

7  6  69  10  reverse  open_window  ; 

:  window4  \  define  window  #4 

10  9  59  4  high_int  open_window  ; 


file:  WINDOW. BLK  Block:  31 

\  window  demo  cl  11/10/85 

:  demo 

fill_crt  windowl 

if  0  0  wat  msg2  wait  wcr  wait  7  emit  wcr 

wait  "  It  sure  is"  wtype  wait  8  wemit  8  werait 
wait  10  5  wat  wait  window2 
if  rasglout  wait  window3 

if  0  10  wat  24  wtriad  wait  window4 

if  msg3out  wait  close_window  wait  close_window 
wait  clr_window  msg2out  wait  close_window 
0  wlist  wait  wait  wait  wait  close_window 
then 
then 
then 
then 
wait  ; 


file:  WINDOW. BLK  Block:  32 


\  window  demo 

only  forth  also  dos  also  \ 

:  test  empty-buffers  \ 

initialize  \ 

"  window. blk"  fcbl  (!fcb)  \ 
fcbl  ! files  open-file  \ 

2  0 

do  \ 


demo  wait  wait  wait  dark  wait 
loop 

. M  What  did  you  think  of  that  H 


cl  11/10/85 
search  dos  and  forth 
dummy  program  name 
initialize  memory  manager 
parse  filename  to  fcb 
open  the  file  to  list 

run  the  demo  2  times 

ah?"  cr  bye  ; 


only  forth  also 


\  power  up  search  order 


'  test  is  boot 
save-system  window.com 


\  make  demo  run  automatically 
\  create  . COM  demo 

End  Listing 
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_ STRUCTURED  PROGRAMMING 

Listing  One  (Text  begins  on  page  112.) 


Listing  One:  tiny  tools 


:  NIP  (  n  m  -  ra  )  SWAP  DROP  ;  (  drops  second  on  stack  ) 

:  TUCK  (  n  m  -  m  n  m  )  SWAP  OVER  ;  {  tucks  top  under  second  ) 

:  -ROT  (  a  b  c  -  c  a  b  )  ROT  ROT  ;  (  opposite  of  ROT  ) 

:  INCR  (  a  -  )  1  SWAP  +1  ;  (  increments  a  variable  ) 

:  DECR  (  a  -  )  -1  SWAP  +!  ;  (  decrements  a  varaible  ) 

(  ERRCNT  INCR  increments  the  variable  ERRCNT  ) 

(  #LINES  DECR  decrements  the  variable  #LINES  ) 

:  ON  (  a  -  )  -1  SWAP  !  ;  (  forces  variable  to  true  value  ) 

:  OFF  (  a  -  )  0  SWAP  !  ;  (  forces  variable  to  false  value  ) 

27  CONSTANT  ESC 

:  NUF?  (  -  f  )  ?TERMINAL  DUP  IF  KEY  2 DROP  KEY  ESC  -  THEN  ; 


(  NUF?  is  used  inside  a  DO  LOOP  structure;  when  a  key  is  ) 

(  pressed,  NUF?  stops  to  wait  for  a  second  keypress.  ) 

(  If  no  key  was  struck  or  the  second  key  is  not  the  Escape  ) 

(  key,  the  flag  is  false;  otherwise,  the  flag  is  true.  ) 

(  The  word  ?TERMINAL  is  vendor-specific.  Your  Forth  might  ) 


(  use  ?KEY  or  some  other  word  instead.  It  is  the  word  that  ) 
(  returns  a  true  flag  if  a  key  has  been  pressed  and  a  false  ) 
(  flag  otherwise;  the  key's  value  is  then  retrieved  with  the) 
(  standard  word  KEY.  ) 


:  LISTIT  *LINES  0  DO  I  LIST-LINE  NUF?  IF  LEAVE  THEN  LOOP  ; 

(  Example- of  NUF?:  LISTIT  will  pause  after  listing  a  line  ) 

(  when  a  key  is  pressed.  Pressing  Escape  will  then  leave  ) 

(  the  loop,  interrupting  the  task;  any  key  except  Escape  ) 

(  does  not  interrupt  but  resumes  the  task.  ) 

0  CONSTANT  F 
-1  CONSTANT  T 

:  ESC-HIT?  (  -  f  )  (  leaves  T  if  Escape  key  pressed  ) 

F  ?TERMINAL  IF  BEGIN  KEY  ESC  -  OR  ? TERMINAL  NOT  UNTIL  THEN  ; 

(  ESC-HIT?  is  like  NUF?  without  the  pause.  It  is  used  much  ) 

(  like  NUF?  and  would  also  work  in  the  above  example.  Note  ) 

(  that  ESC-HIT?  discards  the  contents  of  the  key  buffer  as  ) 

(  it  rummages  through  looking  for  an  Escape  keypress.  ) 

:  BYTE-SWAP  (  x  -  x'  )  256  UM*  OR  ; 

(  This  word  swaps  the  two  bytes  in  a  cell.  Bill  Muench  of  ) 

(  Santa  Cruz  thought  of  this  little  gem.  ) 

End  Listing  One 


Listing  Two 

Listing  Two:  array-defining  word  1 


:  ARRAY  CREATE  (  #  -  )  2*  ALLOT  (  reserves  #  cells  in  memory  ) 

DOES>  (  n  <adr>  -  adr  )  SWAP  2*  +  ;  (  adr  of  nth  cell  ) 

(  This  array  allocates  the  number  of  cells  specified,  but  does  ) 

(  not  initialize  them  to  zero.  ) 

8  ARRAY  TOM  (  defines  TOM  as  having  8  cells  -  16  bytes  ) 

125  5  TOM  !  (  stores  125  in  cell  5  of  TOM  ) 

0  TOM  @  (  retrieves  the  contents  of  cell  0  of  TOM  ) 

End  Listing  Two 


Listing  Three 

Listing  Three:  array-defining  word  2 


1  CONSTANT  BYTES 

2  CONSTANT  CELLS 

4  CONSTANT  DOUBLES 

:  FOR  CREATE  (  #slOts  type  -  )  DUP  C,  *  HERE  OVER  ERASE  ALLOT 
DOES>  (  index  <adr>  -  adr  )  COUNT  ROT  *  +  ; 

11  BYTES  FOR  FRED 
35  CELLS  FOR  JOAN 
17  DOUBLES  FOR  JOHN 

(  These  arrays  will  deliver  the  address  of  the  slot  based  ) 

(  on  the  type  of  the  entry.  The  array  is  initialized  to  ) 

(  zeroes  at  creation  time.  It  is  the  programmer's  job  to  ) 

(  use  C!,  !,  21,  C@,  @,  and  20  as  appropriate.  Note  that  ) 

(  FRED's  11  slots  are  numbered  0  through  10,  JOAN's  35  are  ) 

(  numbered  0  through  34,  and  JOHN'S  17  are  0  through  16.  ) 

213  3  FRED  C!  (  stores  213  into  byte  3  of  FRED  ) 

31  JOAN  0  (  fetches  contents  of  cell  31  of  JOAN  ) 

3142352.  15  JOHN  2!  (  stores  3142352.  into  slot  15  of  JOHN  ) 

End  Listing  Three 


Listing  Four 


Listing  Four:  array-defining  word  3 


I  CONSTANT  PUT  (  flags  for  the  IF  statement  ) 

0  CONSTANT  GET  (  in  the  DOES>  part  of  FOR  ) 

CREATE  STORES  ]  CJ  1  NOOP  2!  [  (  NOOP  stored  to  put  2\  ) 
CREATE  FETCHES  ]  C0  0  NOOP  20  [  (  and  20  in  right  spot  ) 

:  FOR  CREATE  (  * slots  type  -  )  DUP  C,  *  HERE  OVER  ERASE  ALLOT 
DOES>  (  datum  1  ndx  <adr>  —  I  0  ndx  <adr>  —  datum  ) 
COUNT  DUP  >R  (  save  type  )  ROT  *  +  R>  1-  2*  ROT 
IF  STORES  ELSE  FETCHES  THEN  +  0  EXECUTE  ; 

(  This  version  of  FOR  takes  care  of  the  fetching  and  storing  ) 
(  given  the  appropriate  flag;  the  programmer  does  not  have  to  ) 
(  remember  whether  it  is  a  byte,  cell,  or  double-precision  ) 
(  array.  This  could  easily  be  extended  for  floating-point  ) 
(  numbers  as  well.  In  the  stack  comment,  "|"  is  read  as  "or."  ) 

II  BYTES  FOR  FRED 
35  CELLS  FOR  JOAN 
17  DOUBLES  FOR  JOHN 


213  PUT  3  FRED  (  stores  213  in  byte  3  of  FRED  ) 

GET  31  JOAN  (  retrieves  contents  of  cell  31  of  JOAN  ) 

3142352.  PUT  15  JOHN  (  stores  3142352.  in  slot  15  of  JOHN  ) 

End  Listing  Four 


Listing  Five 


Listing  Five:  bit  tools 


CREATE  BITBYTES  1  C,  2  C,  4  C,  8  C,  16  C,  32  C,  64  C,  128  C, 

FLAG  (  ?  -  f  )  0-  NOT  ;  (  forces  to  a  Boolean  flag:  -1  or  0  ) 

AIM  (  *  adr  -  bit*  adr'  )  SWAP  8  /MOD  ROT  +  ; 

+BIT  (  #  adr  -  )  AIM  SWAP  MASK  OVER  C0  OR  SWAP  C!  ; 

-BIT  (  *  adr  -  )  AIM  SWAP  MASK  NOT  OVER  C@  AND  SWAP  Cl  ; 

0BIT  (  *  adr  -  f  )  AIM  C@  SWAP  MASK  AND  FLAG  ; 

-BIT  (  *  adr  -  f  )  AIM  2DUP  0BIT  IF  -BIT  ELSE  +BIT  THEN  ; 

End  Listing  Five 


Listing  Six 

Listing  Six:  array-defining  word  4 


0  CONSTANT  BITS  (  for  bit  arrays  ) 

:  BITS>BYTES  (  #bits  -  #bytes  )  8  /MOD  SWAP  IF  1+  THEN  ; 

:  FOR  CREATE  (  # slots  type  -  )  DUP  C,  ?DUP 
IF  *  ELSE  BITS>BYTES  THEN 
HERE  OVER  ERASE  ALLOT 

DOES>  (  datum  1  ndx  <adr>  —  I  0  ndx  <adr>  —  datum  ) 
COUNT  ?DUP  (  nonzero  -  numbers;  0  -  bits  ) 

IF  DUP  >R  {  save  type  )  ROT  *  +  R>  1-  2*  ROT 
IF  STORES  ELSE  FETCHES  THEN  +  0  EXECUTE 
ELSE  ROT  (  action  flag:  1  -  store,  0  -  fetch  ) 
IF  ROT  ?DUP  (  nonzero  means  1  bit  or  toggle  ) 
IF  0<  IF  -BIT  ELSE  +BIT  THEN 
ELSE  -BIT  THEN 
ELSE  0BIT  THEN  THEN  ; 


1  1  2CONSTANT  SET  (  By  placing  two  values  on  ) 

0  1  2 CONSTANT  ZAP  (  the  stack,  these  words  in  ) 

-1  1  2 CONSTANT  FLIP  (  effect  include  the  PUT.  ) 

23  BITS  FOR  BIT  (  reserves  4  bytes  for  bit  array  ) 

SET  16  BIT  (  turns  bit  16  on  ) 

ZAP  5  BIT  (  turns  bit  5  off  ) 

FLIP  0  BIT  (  toggles  bit  0  ) 

GET  3  BIT  (  retrieve  bit  3  as  boolean  flag  ) 

(  Examples  shown  in  Listing  4  will  also  work  with  this  word.) 


End  Listing  Six 
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Listing  Seven 


Listing  Seven:  array-defining  word  5 


:  >TYPE  {  adr  -  adr'  ;  from  *slots-adr  to  type-adr  )  2+  ; 

:  >DATA  {  adr  -  adr'  ;  from  #slots-adr  to  data-adr  )  3  +  ; 

:  FOR  CREATE  (  # slots  type  -  ) 

OVER  ,  (  4  slot s  )  DUP  C,  (  type  )  ?DUP 
IF  *  ELSE  BITS>BYTES  THEN 
HERE  OVER  ERASE  ALLOT 

DOES>  {  datum  1  ndx  <adr>  —  I  0  ndx  <adr>  —  datura  ) 

>TYPE  COUNT  ?DUP  (  nonzero  -  numbers;  0  -  bits  ) 

IF  DUP  >R  (  save  size  )  ROT  *  +  R>  1-2*  ROT 
IF  STORES  ELSE  FETCHES  THEN  +  0  EXECUTE 
ELSE  ROT  {  action  flag:  1  -  store,  0  -  fetch  ) 

IF  ROT  ?DUP  (  nonzero  means  1  bit  or  toggle  ) 

IF  0<  IF  -BIT  ELSE  +BIT  THEN 
ELSE  -BIT  THEN 
ELSE  0BIT  THEN  THEN  ; 

End  Listing  Seven 


Listing  Eight 

Listing  Eight:  array  display  word 


:  "TYPES  bit  byte  cell  double"  ; 

:  .TYPE  (  type  -  )  6  *  [']  "TYPES  >BODY  3  +  +  6  -TRAILING  TYPE  ; 

:  DOUBLE?  (  type  -  f  )  4  -  ; 

:  } LINE  (  type  n  -  type  )  OVER  DOUBLE?  IF  DUP  5  ELSE  DUP  10 

THEN  MOD  IF  DROP  ELSE  CR  4  . R  . "  I  "  THEN  ; 

:  VITALS  (  array-adr  -  data-adr  #slots  type  )  DUP  >TYPE 

OVER  >DATA  ROT  0  (  #slots  )  ROT  C0  (  type  )  ; 

:  TITLE  (  fslots  type  -  )  CR  CR  SWAP  .  .TYPE  ."  s:"  ; 

:  DISPLAY  (  adr  --  )  VITALS  2 DUP  TITLE  ?DUP 

IF  (  numbers  )  SWAP  0  DO  I  }LINE  2DUP  I  *  +  (  adr  ) 

OVER  DUP  >R  (  save  type  )  1-  2*  FETCHES  +  0  EXECUTE 
R>  DOUBLE?  IF  12  D.R  ELSE  7  .R  THEN 
NUF?  IF  LEAVE  THEN  LOOP  2DROP 
ELSE  (  bits  )  0  DO  I  DUP  } LINE  OVER  0BIT 

2  SPACES  IF  ASCII  1  ELSE  ASCII  -  THEN  EMIT 
NUF?  IF  LEAVE  THEN  LOOP  DROP 
THEN  CR  ; 

:  SPILL  (  -  ;  name  )  BL  WORD  FIND 
IF  >BODY  DISPLAY 

ELSE  DROP  CR  ."  No  such  array  "  THEN  ; 


16  DOUBLES  FOR  MIKE 
1892735.  PUT  0  MIKE 
7802472.  PUT  15  MIKE 
1263.  PUT  8  MIKE 
SPILL  MIKE 


16  doubles: 

0  |  1892735 

0 

0 

0 

5  1  0 

0 

0 

1263 

10  |  0 

15  |  7802472 

0 

0 

0 

16  BITS  FOR  STEVE 
SET  0  STEVE 

SET  15  STEVE 

FLIP  11  STEVE 
SPILL  STEVE 

16  bits: 

0|  1  -  -  -  -  - 

10  |  -  1  -  -  -  1 


End  Listings 
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COLUMNS 


16-BIT  SOFTWARE  TOOLBOX 


Forth  and  the  EIMS 

he  Lotus/Intel/Microsoft  Ex¬ 
panded  Memory  Specification 
(EMS)  allows  application  programs  to 
access  as  much  as  8  megabytes  of 
bank-switched  memory  in  a  portable 
manner.  The  original  specification 
(Version  3.0)  was  released  jointly  by 
Intel  and  Lotus  around  the  time  of 
the  spring  Comdex  in  1985.  Subse¬ 
quently,  Microsoft  endorsed  the  EMS 
and  suggested  some  additions  for  the 
sake  of  multitasking  operating  sys¬ 
tems  that  resulted  in  the  release  of 
EMS,  Version  3.2.  Version  4  of  the  EMS 
is  said  to  be  under  development,  but 
we  will  not  concern  ourselves  with 
that  here. 

An  expanded  memory  subsystem 
is  actually  the  combination  of  a  bank- 
switched  memory  board  and  a  resi¬ 
dent  system  driver.  Taken  together, 
these  present  a  uniform  interface 
that  can  be  called  by  programs  via  a 
software  interrupt  ( 67H ).  The  driver 
supports  such  functions  as  allocation, 
deallocation,  and  mapping  of  the  ex¬ 
panded  memory  pages.  The  Above 
Board  from  Intel  was  the  first  com¬ 
mercially  available  implementation 
of  the  EMS,  but  EMS  boards  are  now 
available  from  a  broad  variety  of  ven¬ 
dors,  including  AST,  Quadram,  and 
Tall  Tree  Systems.  Expanded  memo¬ 
ry  should  not  be  confused  with  ex¬ 
tended  memory,  which  is  IBM’s  term 
for  the  physical  memory  above  1  me¬ 
gabyte  that  is  addressable  by  an  80286 
CPU  running  in  protected  mode. 

In  harmony  with  this  DDJ  issue’s 
emphasis  on  Forth,  I  have  included 
the  source  code  for  a  simple  PC/Forth 
interface  to  an  expanded  memory 
subsystem,  allowing  the  declaration 
and  use  of  huge  arrays  (Listing  One, 


by  Ray  Duncan 

next  month).  I  have  kept  the  code 
simple  for  clarity  and  have  made  no 
attempt  to  optimize  it  for  speed.  Also, 
for  the  purposes  of  this  example,  I 


have  not  taken  advantage  of  the  EMS 
driver’s  ability  to  map  four  separate 
logical  pages  onto  physical  memory 
at  a  time,  and  I  have  not  included 
code  to  eliminate  redundant  map¬ 
ping  calls.  As  they  say  in  the  calculus 
books,  these  enhancements  are  left  as 
an  exercise  for  the  reader,  though 
they  are  easy  to  add  once  the  basic 
EMS  scheme  is  understood. 

Readers  wishing  for  more  details 
about  EMS  programming  can  find 
them  in  the  chapter  on  memory 
management  in  my  book  Advanced 
MS-DOS  (Bellevue,  W A:  Microsoft 
Press,  1986).  You  can  also  obtain  the 
original  EMS  document  (part  number 
300275-003,  dated  September  1985) 
from  Intel  Corp.,  3065  Bowers  Ave., 
Santa  Clara,  CA  95051. 

The  TEE  Filter  Again 

Herb  Shear,  of  Los  Altos,  California, 
wrote:  "Just  a  couple  of  comments 
regarding  the  TEE  filter  (published  in 
the  April  1985  DDJ).  In  the  August  is¬ 
sue  you  mention  a  bug  reported  by 
Dr.  Fred  Sinai,  who  indicated  that  the 
problem  occurred  with  files  that  did 
not  end  in  a  CR/LF.  The  actual  prob¬ 
lem  is  with  files  ending  with  the  infa¬ 
mous  Control-Z  being  output  to  the 
console  in  cooked  mode.  The  resul¬ 
tant  stripping  of  the  ~Z  leaves  the 
count  one  short,  implying  a  ‘disk  full’ 
to  the  calling  program. 

"My  first  fix  was  to  use  the  re¬ 
turned  count  as  an  offset  pointer  into 
the  buffer  and  to  test  the  character 
for  ~Z.  If  the  compare  was  true,  it 
was  considered  a  good  excuse  for  the 
failed  write  and  the  jump  to  the  error 
message  was  not  executed.  This  was 
OK,  except  that  with  midfile  ~Zs,  the 


106 

512 


latter  part  of  the  file  never  got  to  the 
console,  though  a  file  large  enough  to 
reload  the  buffer  would  cause  con¬ 
sole  output  to  resume.  The  disk  file 
output  would  be  complete.  Accept¬ 
able  but  rather  ungainly  behavior. 

"My  second  fix  was  to  test  the  de¬ 
vice  attribute  word  for  the  output  de¬ 
vice  with  the  IOCTL  function  and  to 
set  the  output  device  to  raw  mode  if  it 
was  found  to  be  the  console.  Because 
the  console's  mode  is  remembered 
program  to  program,  it  must  be  re¬ 
stored  before  TEE  exits." 

Gary  Woodman,  of  Darwin,  Aus¬ 
tralia,  wrote:  "Using  PC-DOS,  I  normal¬ 
ly  redirect  the  output  from  BACKUP 
into  a  file  to  keep  a  log  of  what  was 
backed  up  and  when.  BACKUP  is  even 
duller  than  usual  when  there's  no 
output  on  the  screen,  however. 

"I  gleefully  recalled  the  TEE  filter 
you  published  in  the  April  1985  issue 
and  chuckled  to  myself:  'Ah  ha,  I'll 
TEE  the  output  of  BACKUP  both  to  a 
file  and  to  the  screen!’  But  when  I  dug 
out  the  issue,  it  seemed  like  too  much 
trouble  to  type  in  a  couple  of  pages  of 
8086  assembler  (it  usually  does),  so  I 
scratched  my  head  for  a  few  mo¬ 
ments  and  came  up  with  a  short  C 
program  [Table  1,  below]. 

"Now  I  know  this  is  not  quite  the 
same  as  that  Mr.  Head  provided,  and  I 
don't  want  to  make  a  big  thing  of  this, 
but  it  seems  that  the  contrast  be¬ 
tween  Mr.  Head's  MASM  program 
and  this  C  program  represents,  in  a 
nutshell,  the  dichotomy  of  program¬ 
ming  today.  As  well  as  contrasting 


^include  <stdio.h> 
main( ) 

{  int  c; 

while  ( (c  =  fgetc(stdin) )  !  = 
EOF){ 

fputc(c,  stdout); 
fputc(c,  stderr); 

} 

_> _ 

Table  1:  C  version  of  TEE  filter 
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the  source  code,  contrast  Mr.  Head's 
hours  (possibly  days)  of  development 
plus  an  hour  of  my  time  to  type  in 
and  debug  TEE. ASM  (that  is,  debug  my 
typing!)  with  the  few  minutes  it  took 
me  to  write  the  C  program.  .  .  .  Could 
it  be  that  we  have  here  a  case  of  the 
tail  wagging  the  dog? 

“Just  in  passing,  in  case  anyone  still 
feels  that  high-level  language  compil¬ 
ers  add  flab  to  our  programs  but  little 
else,  I  report  the  code  sizes  of  TEE.EXE 
as  generated  by  my  three  MS-DOS 
compilers: 

Computer  Innovations,  V.  1.31 

7,936  bytes 

DeSmet,  V.  2.41  8,192  bytes 

Hi-Tech,  V.  2.0  1,611  bytes 

"Incidentally,  this  version  of  the  Cl 
compiler  is  now  in  the  public  do¬ 
main,  a  brilliant  marketing  ploy  and 
a  “best  buy.' 

"I  haven't  done  any  benchmarks  as 
it  really  isn't  a  very  important  issue. 
Everyone  knows  the  assembler  pro¬ 
gram  leads  by  at  least  an  order  of  mag¬ 
nitude.  For  the  number  of  times  I  TEE 
things,  I’m  quite  happy  to  accept  the 
run-time  inefficiencies  in  exchange 
for  the  saving  in  development  using  C 
for  what  is  almost  a  disposable  pro¬ 
gram.  And  as  for  TEEing  the  output  of 
BACKUP,  well,  MS-DOS  is  of  course  sin¬ 
gle-tasking  and,  as  it  turns  out,  the  out¬ 
put  of  BACKUP  is  not  available  to  TEE 
until  BACKUP  finishes.’’ 

Mr.  Woodman's  points  on  coding 
time  vs.  execution  time  are  certainly 
worth  discussing  further  in  this  col¬ 
umn.  It  doesn't  take  me  more  than  an 
hour  or  two  to  write  a  program  the 
size  of  TEE  from  scratch  in  assembly  | 
language  and  feel  confident  that  it  is 
adequately  debugged.  And  the  vast 
majority  of  assembly  code  is  reus¬ 
able,  just  as  is  C  or  any  other  lan¬ 
guage.  Once  an  assembly-language 
functioning  filter  such  as  TEE  is  in 
hand,  for  example,  it  is  only  a  few 
minutes’  work  to  modify  it  to  per¬ 
form  any  reasonable  transformation 
on  a  character  stream.  For  me,  the 
benefits  of  the  superior  performance 
and  compactness  of  an  assembly-lan¬ 
guage  program  almost  always  out¬ 
weigh  all  other  considerations  for 
utility  programs  that  I  am  going  to 
run  more  than  once.  Let’s  hear  from 
DDJ  readers  on  this  subject! 

Incidentally,  I  suspect  that  if  Unix 
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were  written  in  assembly  language 
instead  of  in  C,  it  would  have  an  over¬ 
head  of  64K  instead  of  256K,  would 
run  ten  times  faster,  and  wouldn't  be 
so  overburdened  with  barely  useful 
features  that  have  been  grafted  on  by 
generations  of  graduate-student  pro¬ 
grammers  at  UC  Berkeley. 

Defenders  of  Concurrent  DOS 

My  (perhaps  somewhat  overdrawn) 
editorializations  about  Concurrent 
DOS  and  Digital  Research  in  the  Feb¬ 
ruary  1986  issue  of  DDJ  drew  plenty 
of  responses  from  readers.  This 
month  I'd  like  to  give  some  space  to 
other  viewpoints  on  this  product. 

Steve  Elias,  of  Wellesley  Hills,  Mas¬ 
sachusetts,  wrote  heatedly:  "Look  be¬ 
fore  you  write  that  Concurrent  DOS 
only  supports  DOS  1  functionality. 
You  were  using  an  old  version.  Con¬ 
current  DOS  supports  all  2.1  calls. 

“Concurrent  DOS  is  the  most  sophis¬ 
ticated  and  DOS-compatible  multi¬ 
tasking  operating  system  available. 
The  fact  that  it  is  based  on  CP/M  may 
be  ugly,  but  it  is  transparent  to  the 
average  user/' 

Mark  Davidson  of  Chattanooga, 
Tennessee,  sent  two  separate,  de¬ 
tailed  letters  on  Concurrent  DOS  4.1, 
which  I  have  abstracted  to  some  ex¬ 
tent:  “The  new  version  really  only 
supports  path  names  as  far  as  the 
CHDIH,  RMDIR,  and  MKDIR  commands 
go.  None  of  the  Concurrent  PC-DOS 
commands  will  accept  a  directory 
path.  ...  As  for  using  your  DOS  utili¬ 
ties  under  Concurrent  DOS,  it  de¬ 
pends  on  what  version  of  DOS  these 
utilities  belong  to.  If  you  are  using  PC- 
DOS  3.0  when  you  install  Concurrent 
DOS,  you  can  forget  about  running 
any  of  your  PC-DOS  utilities.  They  all 
refuse  to  run,  giving  the  incorrect 
DOS  version'  message.  The  story  is  a 
little  different  if  you  are  using  PC-DOS 
2.1.  Some  utilities  will  run  fine  (such 
as  TREE  and  FIND),  whereas  others  do 
things  that  are  very  unexpected 
(CHKDSK  checks  drive  A:  instead  of  the 
current  drive).  DRI  warns  that  BACK¬ 
UP  and  RESTORE  should  not  be  used. 
Also,  it  claims  that  you  can  run  BA- 
SICA  under  Concurrent  DOS  with  the 
only  side  effect  being  that  multiuser 
activity  will  halt.  This  appears  to  be 
an  understatement.  BASICA  on  the  PC/ 


AT  using  the  BASICA  that  comes  with 
PC-DOS  3.1  will  produce  the  “incorrect 
DOS  version'  error.  My  attempts  to 
run  BASICA  from  PC-DOS  2.1  under 
Concurrent  DOS  produced  an  inter¬ 
esting  display  of  nothing  while  caus¬ 
ing  a  horrendous  beeping  to  come 
from  the  speaker. 

"I  found  some  other  unexpected 
surprises,  too.  Commands  such  as 
type  foo.doc  I  more  will  type  the  file 
but  not  pause  attheendof  each  screen¬ 
ful.  Could  this  mean  that  pipes  don't 
work?  Also,  because  none  of  the  PC-DOS 
3  commands  will  run  under  Concur¬ 
rent  DOS,  attempts  to  execute  the  Ver¬ 
sion  3  command.com  as  a  subprocess 
will  fail.  I  haven 't  tried  this  with  the  PC- 
DOS  2.1  command.com. 

"But  this  letter  isn't  full  of  just  bad 
news.  DRI  has  obviously  fixed  some  of 
the  problems  that  were  present  in 
Concurrent  DOS  3.2.  Many  programs 
that  wouldn't  execute  under  3.2  now 
run  fine  under  4.1 — these  include  the 
Lattice  C  compiler  and  DeSmet’s  C 
compiler.  Also,  because  some  of  the 
PC-DOS  2.1  utilities  at  least  try  to  run,  it 
is  evident  that  several  internal 
changes  have  been  made. .  . . 

"Concurrent  DOS  is  still  noticeably 
slower  than  PC-DOS,  even  if  you  have 
only  one  task  running.  And  it  is  a  big 
system,  still  requiring  approximately 
1,700K  of  disk  space;  DRI  also  suggests 
that  you  have  at  least  512K  RAM  in 
your  machine." 

Brian  J.  Mullan  of  Lutz,  Florida, 
sent  an  articulate  defense  of  Concur¬ 
rent  DOS  and  its  capabilities  (both  pre¬ 
sent  and  future).  He  wrote:  "I  am  a 
senior  software  systems  analyst  with 
a  company  based  in  McLean,  Virgin¬ 
ia,  and  I  would  like  to  provide  some 
comments  regarding  your  editorial 
statements  on  Digital  Research’s  Con¬ 
current  DOS  operating  system. 

"IBM  has  just  implemented  DRl's 
Concurrent  DOS  286  as  the  host  IBM 
PC/AT  OS  for  a  128-terminal  system 
that  it  is  going  to  market  under  the 
system  4680  name.  I  don’t  know  how 
much  you  read  in  other  professional 
trade  magazines,  but  the  IBM  repre¬ 
sentatives  who  commented  on  the 
release  of  the  4680  system  stated  in  an 
MIS  Week  issue  three  or  four  weeks 
ago  that  ‘this  is  a  true  multitasking/ 
multiuser  operating  system  allowing 
IBM  PC  software  to  run  in  the  IBM  PC/ 
ATs  protected  mode.’ 

"IBM  also  stated  that  it  had  worked 


with  DRI  to  develop  Concurrent  DOS 
286  and  to  allow  it  to  run  PC-DOS  soft¬ 
ware  in  the  AT’s  protected  mode!  The 
single  AT  running  this  OS  not  only 
provides  the  horsepower  to  manage 
the  128  dumb  terminals  tied  to  it  (note: 
this  system  is  not  a  LAN!),  but  the  mul¬ 
titasking  capabilities  of  the  system  al¬ 
low  on-line  communications  to  an 
IBM  mainframe  host  concurrently 
with  other  processing  functions. 

"So  first  of  all,  it  is  not  true  that  DRI 
gave  up  on  the  80286  Protected  Mode 
version  of  its  OS.  Where  is  Micro¬ 
soft's?  [I  didn’t  say  DRI  had  given  up  on 
it,  I  said  it  admitted  the  OS  would  not 
be  delivered  in  the  form  originally 
advertised.] 

“The  mention  you  made  of  the  DRI 
Unix  events  are  not  quite  accurate 
either.  .  .  .  According  to  the  trade  me¬ 
dia  coverage  (by  Computerworld  and 
MIS  Week),  AT&T  was  the  cause  of  the 
breakoff  of  the  DRI  Unix  library  de¬ 
velopment  effort.  Apparently  AT&T 
decided  that  the  Unix  library  needs 
could  not  possibly  be  fullfilled  by  a 
single  company  (which  I  think  you 
should  note  included  AT&T  Informa¬ 
tions  Systems  division)  in  the  time 
necessary  to  bring  AT&T's  computer 
line  up  against  IBM.  Because  AT&T 
had  signed  an  exclusive  agreement 
with  DRI  for  the  development  of  this 
library,  this  prohibited  AT&T  from 
parceling  out  the  tremendous 
amount  of  work  to  be  done  to  even  a 
single  other  company.  So  it  was  at 
AT&T’s  request  that  the  contract  was 
canceled  and  with  the  acknowledge¬ 
ment  that  DRI  was  not  delinquent  in 
its  contractual  obligations  to  AT&T. 

"Again,  AT&T  did  not  go  to  Micro- 
spft  for  this  development  work, 
which  should  also  make  some  sort  of 
a  statement! 

“Last,  Digital  Research's  Concurrent 
DOS  version  for  the  IBM  PC/XT  is  the 
only  true  multitasking/multiuser,  PC- 
DOS-compatible  OS  for  those  ma¬ 
chines.  Yes,  there  is  Xenix  (no  DOS 
compatibility),  which  costs  only  seven 
times  as  much  and  takes  up  6-8  mega¬ 
bytes  of  disk  storage  space  vs.  the  160K 
for  Concurrent  DOS. 

“'I  am  also  a  Unix  advocate  and 
have  programmed  under  that  OS  for 
several  years  now.  At  home,  howev¬ 
er,  I  use  Digital  Research’s  Concur¬ 
rent  PC-DOS,  Version  4.1. 1  find  it  to  be 
a  very  good  operating  system  envi¬ 
ronment  with  nearly  all  the  profes- 
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sional  systems  design  concepts  de¬ 
scribed  as  essential  for  modern 
computing  by  such  books  as  Operat¬ 
ing  System  Elements — A  User  Per¬ 
spective  by  Peter  Calingaert  (Pren¬ 
tice-Hall).  Among  the  state-of-the-art 
features  pointed  out  in  this  book  that 
Concurrent  PC-DOS  provides  and  MS- 
DOS  does  not  are: 

•  the  concept  of  programs  as  finite- 
state  processes  within  the  computer 

•  dynamic  memory  management  in 
the  multitasking/multiuser  environ¬ 
ment 

•  systems  support  for  QUEUEING 
structures  (that  is,  interprocess  mes¬ 
sage  queues,  priority  queues,  mutual 
exclusion  queues,  and  so  on) 

•  support  for  multilevel  PRIORITY  as¬ 
signment  to  allow  efficient  schedul¬ 
ing  of  multiple  concurrent  processes 

•  inclusion  of  a  directory  hashing  al¬ 
gorithm  (which  drastically  increases 
system  throughput) 

•  logical  file  and  record  locking 

•  multilevel  passwording  of  files 
controlling  read,  write,  and  delete 
privileges 

•  time  and  date  stamping  of  files  (for 
creation,  last  access,  and  last 
modification) 

•  system  support  for  processes  to  is¬ 
sue  logical  waif  or  resume  inter¬ 
rupts — another  efficient  method 
used  in  interprocess  communications 

•  real-time  multitasking  and  mul¬ 
tiuser  support  (note  that  Microsoft 
Windows  uses  a  nonpreemptive  mul¬ 
titasking  algorithm,  which  means  it 
cannot  be  used  for  applications  re¬ 
quiring  real-time  response) 

•  logical  data  storage  elements 

•  the  ability  to  spawn  multiple  sub¬ 
processes  from  any  single  process  (in¬ 
valuable  for  any  application  that 
must  monitor  multiple  port  I/O  such 
as  in  communications  or  instrumen¬ 
tation  control) 

“I  agree  and  disagree  with  your 
statement  that  DRI  will  always  be 
playing  catch-up  to  Microsoft’s  MS- 
DOS.  I  believe  that  if  you  consider  the 
features  that  DRI's  PC-DOS-compatible 
OS  family  (which  by  the  way  runs  on 
the  8088,  8086,  80286,  and  68000)  al¬ 
ready  provides,  and  which  Microsoft 
is  only  now  beginning  to  address  for 
its  MS-DOS,  you  might  take  a  different 
attitude  as  to  which  operating  system 
really  provides  the  professional  pro- 
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grammer  with  the  more  state-of-the- 
art  programming  environment! 

“Yes,  DRI  is  playing  catch-up  but 
only  in  an  attempt  to  maintain  file 
and  programming  compatibility 
with  MS-DOS  as  Microsoft  attempts  to 
implement  all  of  the  aforementioned 
features.  DRI's  next  release  of  the  PC/ 
XT  version  of  this  OS  in  two  to  three 
months  and  which  is  already  in  beta 
testing  should  provide  the  last  ves¬ 
tiges  of  compatibility  with  MS-DOS, 
Version  2.1,  including: 

•  full  path  support 

•  installable  device  drivers  (the  cur¬ 
rent  version  allows  only  hard-disk 
device  drivers  to  be  installed 
dynamically) 

•  DOS  environment  variable  support 
via  MS-DOS  set  command 

"An  extension  to  the  version  of  the 
OS  currently  in  beta  testing,  sched¬ 
uled  for  summer  1986,  is  supposed  to 
provide  full  MS-DOS,  Version  3.1, 
compatibility! 

"After  all,  if  DRI  has  learned  any 
lesson  from  the  past  four  years,  it  has 
been  that  the  public  has  been  sold  on 
the  MS-DOS  environment,  and  DRI 
must  provide  that  functionality  in  its 
systems  software.  This  only  indicates 
to  me  that  DRI  is  responding  to  the 
marketplace  and  if  anything  is  look¬ 
ing  backward  to  Microsoft's  limited 
OS  to  see  how  it  can  be  supported. 

"Many  a  systems  engineer  will 
support  the  theory  that  a  good  oper¬ 
ating  system  must  be  designed  from 
the  beginning  to  incorporate  the 
structures  necessary  for  real-time 
multiuser/multitasking.  Attempting 
to  do  otherwise  invites  development 
of  a  most  haphazard  and  kludged  de¬ 
sign  in  the  attempt  to  maintain  com¬ 
patibility  with  whatever  the  current 
operating  system  provides.  I  think 
this  problem  with  MS-DOS  will  be¬ 
come  more  evident  as  Microsoft  at¬ 
tempts  to  introduce  multitasking  and 
multiuser  support  to  its  OS.  I  think  it 
is  relevant  and  most  significant  to  no¬ 
tice  that  Microsoft  did  not  provide  its 
first  attempt  at  multitasking  through 
its  operating  system  but  through  an 
externally  run  program — Windows. 

"Although  it  is  true  that  DRI  has 
made  several  heroic  blunders  in  the 


past,  I  do  not  believe  they  should  be 
held  as  some  sort  of  crucifix  for  it  to 
bear.  Everyone  makes  mistakes,  and  I 
do  believe  that  DRI  has  and  still  is  pay¬ 
ing  for  its!  I  also  believe,  however, 
that  it  is  the  duty  of  columnists  such 
as  yourself  to  keep  an  open  mind  and 
to  provide  information  that  benefits 
the  computing  public  at  large  and  not 
to  blindly  assume  such  things  as  MS- 
DOS'  a  priori  superiority  of  design. 

"You  must  remember  that  90  per¬ 
cent  of  all  businesses  in  the  United 
States  are  small  businesses  that  only 
have  need  for  two  to  five  terminal  us¬ 
ers.  LANs  are  great  and  very  cost-effec- 
tive  for  six  or  more  users,  but  for  small 
businesses,  a  multiuser  operating  sys¬ 
tem  that  allows  the  attachment  of 
$400-$500  dumb  terminals  to  a  single 
PC/XT/ AT  is  a  much  more  realistic  and 
cost-effective  approach  to  increased 
office  productivity.  The  argument 
can  be  made  for  the  use  of  multiple, 
cheap,  clone  PCs  in  such  a  situation, 
but  how  many  businessmen  would 
want  multiple  copies  of  their  ac- 
counts-receivable  file  or  inventory 
file  on  several  different  machines?  I 
believe  that  multiuser  operating  sys¬ 
tems  such  as  Digital  Research's  Con¬ 
current  DOS  definitely  have  their 
place  in  the  world.  They  may  not  nec¬ 
essarily  fit  every  situation  or  need,  but 
then  neither  does  the  more  simplistic 
environment  provided  by  the  current 
versions  of  MS-DOS." 

I  don’t  agree  with  all  of  Mr.  Mul- 
lan's  arguments,  but  for  once  I  am  go¬ 
ing  to  pass  up  my  prerogative  as  the 
columnist  to  have  the  last  word  on  the 
subject.  Further  comments  on  the  al¬ 
leged  need  for  multitasking,  mul¬ 
tiuser  operating  systems  in  personal 
computers  are  solicited  from  DDJ 
readers! 
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columns  STRUCTURED  PROGRAMMING 

Forth:  Philosophy,  Standards,  and  Practical  Advice 


Programming  is  control;  lan¬ 
guages  that  most  directly  give 
the  programmer  control 
touch  most  deeply  the  programming 
impulse.  That’s  the  appeal  of  assem¬ 
bly  language:  mano  a  mano  with  the 
machine’s  bare  metal.  Those  who 
prefer  high-level  languages  find  in 
Forth  an  edge-of-the-envelope  pro¬ 
gramming  environment.  What's  it 
like  out  there? 

Forth  puts  the  programmer  into  in¬ 
timate  contact  with  the  insides  of  the 
language,  unlike  other  high-level  lan¬ 
guages  whose  compilers  are  black 
boxes.  The  Forth  compiler  consists  of 
instructions  in  Forth  itself — the  com¬ 
piler's  right  there,  where  the  pro¬ 
grammer  can  reach  out  and  touch  it, 
not  locked  away  on  the  other  side  of 
some  impenetrable  barrier.  Reach 
out,  touch  it,  and  put  a  little  spin  on  it. 

Programming  in  Forth  consists  of 
adding  new  commands  to  the  lan¬ 
guage.  The  programmer-created 
commands  climb  latticelike  to  the  so¬ 
lution.  The  command  at  the  top  is  the 
program;  when  executed,  it  answers 
the  question  posed  by  the  task.  This 
topmost  command  is  defined  in 
terms  of  commands  lower  in  the  hi¬ 
erarchy,  and  those  commands  are 
defined  in  terms  of  commands  lower 
still.  (Though  recursion  in  Forth  is 
possible,  it  is  not  used  as  often  as  it  is 
in,  say,  LISP.)  The  program’s  founda¬ 
tion  is  a  small  set  of  primitives  writ¬ 
ten  in  the  language  of  the  computer 
on  which  the  program  will  run. 

The  program  may  also  contain  a 
few  assembly-language  commands 


by  Michael  Ham 

added  by  the  programmer  at  speed- 
critical  parts  of  the  application.  Most 
of  the  program,  however,  will  con¬ 
sist  of  commands  written  in  Forth: 
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some  constitute  the  Forth  nucleus, 
some  are  the  programmer’s  own 
general-purpose  tool  words,  and  the 
remainder  are  specific  to  the  prob¬ 
lem  at  hand.  Some  of  these  program¬ 
mer-created  commands  extend  the 
compiler.  But  first  let’s  look  at  the 
programmer’s  tools. 

Over  time,  Forth  programmers 
create  or  collect  a  set  of  tiny  tools  that 
they  graft  onto  the  Forth  they  use. 
(Every  Forth  implementation  pro¬ 
vides  a  way  for  its  user  to  customize  it 
through  the  permanent  addition  of 
new  commands.)  Tiny  tools  percolate 
through  the  community  of  Forth  pro¬ 
grammers  and  in  time  become  assim¬ 
ilated  as  regular  Forth  words.  NIP  and 
TUCK  are  close  to  becoming  a  part  of 
generic  Forth.  A  few  tiny  tools  are 
shown  in  Listing  One,  page  104;  do 
you  know  their  authors?  Before  their 
origins  are  forgotten,  we  should  ac¬ 
knowledge  their  creators  and  refin¬ 
ers.  Send  in  your  own  favorite  tiny 
tools  (with  attribution  if  you  can),  and 
I'll  publish  them  for  general  con¬ 
sumption  to  expedite  the  diffusion. 

In  addition  to  these  tiny  tools,  pro¬ 
grammers  build  larger  tools  as  well. 
These  are  generally  shaped  by  the 
kind  of  applications  the  programmer 
writes.  Later  in  this  column,  I  de¬ 
scribe  (as  a  challenge  to  you)  a  num¬ 
ber-input  tool  I  have  developed.  I 
would  be  interested  in  seeing  your 
solution.  I'll  include  the  best  solution 
I  get  (or,  by  default,  my  own  effort)  in 
a  future  column. 

Extensions  to  the  compiler  (which 
at  first  I  avoided  altogether)  are  the 
source  of  some  of  Forth's  magic.  Ex¬ 
tensions  are  of  two  types:  the  CREA¬ 
TE  ..  .  DOES>  defining  commands 
normally  used  to  add  new  data  class¬ 


es  and  the  IMMEDIATE  words  that  can 
be  used  to  make  new  control  struc¬ 
tures.  Let’s  examine  the  CREATE- 
. . .  DOES>  commands  now  and  save 
the  IMMEDIATE  guys  for  a  future  col¬ 
umn.  With  a  defining  command  you 
can  create  a  family  of  structures  in 
which  all  members  obey  the  rule  laid 
down  in  DOES>. 

Suppose,  for  example,  you  will  be 
using  a  variety  of  arrays  in  some  ap¬ 
plication.  Most  Forths  don’t  provide 
an  array-defining  word:  an  array- 
creating  command  is  easy  to  write, 
and  different  situations  demand  dif¬ 
ferent  array  specialties.  Some  pro¬ 
grammers  might  want  the  array  to 
do  a  range  check  on  indices;  others 
(such  as  myself)  prefer  to  do  any  nec¬ 
essary  edits  before  the  indices  are 
passed  to  the  array.  When  some  in¬ 
ternal  program  routine  generates  the 
indices  within  definite  bounds,  range 
checking  would  sacrifice  speed  un¬ 
necessarily.  I  discuss  a  series  of  varia¬ 
tions  on  an  array-defining  command 
later  in  this  column. 

Because  Forth  doesn't  have  a 
"hands-off”  compiler  whose  inter¬ 
nals  are  secret,  Forth  application  pro¬ 
grammers  are  led  within  the  lan¬ 
guage.  They  work  outward  toward 
their  application,  but  at  the  same 
time  they  work  inward  to  tinker 
with  the  language  itself.  You  don't 
even  have  to  scratch  a  Forth  applica¬ 
tion  programmer  to  find  the  systems 
programmer  within:  the  systems 
programmer  is  right  there,  working 
alongside  the  application  program¬ 
mer.  In  the  array-defining  com¬ 
mands,  for  example,  you  work  to¬ 
ward  adding  a  kind  of  type 
declaration  to  the  language,  a  func¬ 
tion  already  embedded  within  the 
compilers  of  many  languages:  in 
those  languages,  however,  you  usual¬ 
ly  don’t  have  a  chance  to  make  it 
work  in  the  way  you  want. 

Every  Forth  programmer  spends 
some  time  working  on  the  language 
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[  itself  as  the  application.  The  systems  I 
I  enhancements  become  part  of  her  or 
his  toolkit  for  future  work,  and  Forth  ' 
grows  vinelike  to  enclose  the  pro¬ 
gramming  problems  most  often 
encountered. 

Forth  is  by  design  an  open-archi-  1 
tecture  language.  An  accident  of  his-  | 
tory  plunged  Forth  programmers  i 
deep  into  that  architecture  from  the  j 
beginning.  The  first  Forth  products,  ! 
sold  by  FORTH  Inc.,  were  beyond  the 
financial  reach  of  hobbyists.  So  a  j 
band  of  programmers,  the  original  ] 
Forth  Interest  Group  (FIG),  developed  j 
public-domain  Forth  systems  to  pro-  ■ 
mulgate  the  language  to  hobbyists  j 
i  and  hackers.  The  fig-Forth  systems  1 
were  distributed  in  the  form  of 
source-code  listings,  so  early  Forth  ' 
users  were  willy-nilly  systems  pro-  j 
grammers  as  they  typed  in  the  code  j 
and  tuned  it  to  their  needs.  Many 
commercial  Forth  products  were  j 
built  upon  and  grew  out  of  these  ear¬ 
ly  fig-Forth  listings.  Control  of  the 
machine  was  sublimated  into  control 
of  the  language. 


Forth  Standards 

Because  Forth  so  readily  grows  in  ev¬ 
ery  direction,  standards  were  need¬ 
ed  to  define  a  common  core.  Three 
standards  have  come  to  be,  the  later 
supplanting  the  earlier.  The  first  was 
the  FIG  standard,  a  de  facto  standard 
created  by  the  popularity  and  wide¬ 
spread  distribution  of  those  early  FIG 
listings.  This  was  followed  by  the  79  j 
Standard,  the  first  attempt  at  a  formal 
and  deliberate  standard.  The  79  Stan¬ 
dard  benefited  from  hindsight:  It 
contained  what  the  original  fig-Forth 
would  have  included  if  its  creators 
had  had  more  Forth  experience  in¬ 
stead  of  learning  while  doing.  The 
latest  standard  is  the  83  Standard — an 
effort  to  polish,  refine,  and  extend 
the  79  Standard. 

In  most  of  the  computer  industry's 
standards  efforts,  intense  conflicts 
arise  between  unassailable  logic  (my 
position)  and  pointless  pig-headed  re¬ 
sistance  (your  position).  This  dynamic 
could  also  be  detected  in  the  develop¬ 
ment  of  the  83  Standard.  When  the  83 
Standard  was  announced,  the  Forth 
community’s  delight  at  discovering 
refinements  (read:  changes)  from  the 
79  Standard  was  muted.  The  spirit  of 
innovation  had  acquired  a  conserva¬ 
tive  cast. 


Those  moving  up  to  83  Standard 
Forths  should  take  note  of  Ray  Dun¬ 
can’s  article  "Converting  FIG-Forth  to 
Forth  83”in  the  May  1984  DDJ,  Robert 
Berkey’s  two  articles  entitled  "79-  1 
Standard  to  83-Standard”  in  Forth  Di-  j 
mensions  (vol.  6,  nos.  3  and  4),  and  Ke¬ 
vin  McCabe’s  review  of  the  83 
Standard  in  the  August  1984  issue  of 
Byte. 

The  83  Standard  defines  the  behav¬ 
ior  of  a  core  of  Forth  words.  Several 
different  Forths  adhere  to  the  83 
Standard;  their  standard  words  work 
in  the  prescribed  manner,  though 
they  may  differ  in  speed  of  execution 
because  of  the  differences  in  how 
they  were  implemented.  The  exten¬ 
sions  (such  as  the  file-support  system) 
to  these  Forths  are  not  governed  by 
the  standard  and  thus  may  differ 
considerably,  and  a  particular  Forth  | 
may  be  tuned  to  a  specific  machine —  * 
for  example,  it  might  support  func¬ 
tion  keys  and  a  speaker,  both  of 
which  go  beyond  issues  addressed  by 
the  standard. 

Several  implementations  of  83  ! 
Standard  Forth  are  available.  Labora¬ 
tory  Microsystems  and  Micromotion 
have  83  Standard  Forths  for  a  variety 
of  computers.  Harvard  Softworks  has 
an  overlay  file  that  makes  its  Forth 
meet  the  83  Standard.  F83,  a  Forth 
written  by  Henry  Laxen  and  Michael 
Perry,  is  a  public-domain  version  of 
an  83  Standard  Forth. 

Because  the  83  Standard  specifies 
only  a  16-bit  implementation,  32-bit 
Forths  (which  can  address  more  than 
64K  of  instruction  space)  are  by  defini¬ 
tion  nonstandard.  Some  32-bit  Forths, 
however,  (such  as  Palo  Alto  Shipping 
Company’s  Forth  for  the  Macintosh 
and  LMI’s  Forth +  products  for  the 
8088/8086  and  the  68000)  strive  to  be 
standard  in  all  other  respects. 

Although  the  83  Standard  will 
probably  stand  as  the  latest  effort  for 
quite  a  while,  it  fails  to  address  some 
important  topics:  floating  point  (a  de 
facto  standard  seems  to  be  emerging), 
graphics,  and  a  standard  implemen¬ 
tation  for  Forths  that  inhabit  memo¬ 
ry  beyond  64K.  These  issues  are  nec¬ 
essarily  being  addressed  by  Forth 
vendors,  and  a  consensus  may  in 
time  emerge  and  be  recognized  in  a  i 
later  standard. 


Where  Is  It  Used,  and 
Who  Uses  It? 

Forth  is  well  known  as  a  language  for 
data  acquisition  and  machine  and 
process  control  and  is  often  the  high- 
level  language  hiding  inside  the  ROM 
of  an  intelligent  machine.  But  Forth  is 
found  laboring  in  other  vineyards  as 
well.  Business  applications,  for  exam¬ 
ple,  are  not  commonly  thought  of  as 
Forth  territory,  but  Forth  was  in  busi¬ 
ness  from  its  commercial  birth.  When 
Forth  emerged  from  its  womb  of  as¬ 
tronomical  telescope  control  and  was 
delivered  to  FORTH  Inc.’s  first  custom¬ 
er,  it  was  for  a  business  database  sys¬ 
tem  in  a  custom  application.  How 
many  of  you  are  writing  Forth  code  to 
address  applications  that  might  be 
thought  of  as  food  for  COBOL? 

For  that  matter,  what  is  the  range 
of  application  areas  addressed  by 
Forth?  Many  software  products  don’t 
reveal  their  lingual  origins  unless  the 
language  in  question  is  riding  high  or 
deemed  especially  appropriate  for 
the  given  application  area.  Do  you 
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know  accounting  packages  that  are 
unexpectedly  Forth  at  heart?  Data¬ 
bases?  Games?  Instructional  pro¬ 
grams?  I  would  like  to  hear  about  in¬ 
triguing  uses  of  Forth.  Send  me 
information  that  I  can  print,  and  let’s 
see  what  an  honor  roll  of  Forth  pro¬ 
grams  looks  like. 

Forth  programmers  are  an  inter¬ 
esting  lot.  Compared  to  program¬ 
mers  of  most  other  languages,  rela¬ 
tively  few  Forth  programmers  have 
degrees  in  computer  science.  Many 
(most?)  are  self-taught  programmers: 
they  had  a  project  that  involved  some 
programming  and  found  Forth  a 
good  tool — easy  to  learn,  quickly  pro¬ 
ductive,  and  well  adapted  to  an  ex¬ 
perimental  approach.  These  charac¬ 
teristics  result  from  Forth’s 
evolution:  a  working  language 
shaped  in  the  field  by  a  programmer 
who  had  to  fit  big  solutions  into  small 
computers  in  little  time. 

Forth  programmers  include  a  high 
proportion  of  hardware-oriented 
people  who  enjoy  working  at  the 
boundary  between  software  and 
hardware,  using  knowledge  gained 
by  experimentation  and  experience. 
Forth  programmers  abhor  protective 
protocols  and  demand  the  ability  to 
grab  the  guts  of  the  hardware  and 
software.  They  are  an  innovative  lot, 
generally  impatient  with  theory  in 
their  eagerness  to  get  the  job  done. 
They  are  willing  to  share  their  idea 
but  are  sometimes  reluctant  to 
change  their  own  approach.  This 
leads  to  the  reinvention  as  well  as  the 
refinement  of  techniques. 

Where  Can  You  Talk 
with  Them? 

Forth  people  are  scattered  across  the 
country.  Many  are  members  of  the 
Forth  Interest  Group  [P.O.  Box  8231, 
San  Jose,  CA  95155;  (408)  277-0668],  FIG 
publishes  a  journal  and  also  has  a  300- 
baud  bulletin  board  for  discussions 
(no  files).  It’s  at  (415)  962-8653— press 
two  carriage  returns  when  you  con¬ 
nect.  FIG’s  local  chapters  across  the 
country  provide  opportunities  for 
face-to-face  contact. 

DDJ  includes  Forth  offerings  in  its 
own  CompuServe  forum  (GO  DDJ  at 
the  !  prompt).  Creative  Solutions,  a 
Forth  vendor,  also  hosts  a  Forth  dis¬ 
cussion  group  on  CompuServe  (GO 
FORTH).  Two  exclusively  Forth  bulle¬ 
tin  boards  are  the  East  Coast  Forth  BBS 


[(703)  442-8695]  and  the  West  Coast 
LMI  BBS  [(213)  306-3530],  Both  operate 
at  300/1200/2400  bps,  are  available 
around  the  clock,  and  include  both 
discussion  and  files  of  source  code. 

A  Look  at  Arrays 

Array-defining  words  are  the  five-fin¬ 
ger  exercises  of  defining  words.  It's 
easy  to  extend  the  compiler  to  build 
arrays  that  match  your  taste  and 
needs  exactly.  Listings  Two  through 
Eight  trace  one  path  of  development 
for  an  array-defining  word. 

Listing  Two,  page  104,  shows  a  first 
attempt.  Though  this  is  certainly 
good  enough  for  workaday  use,  it  has 
a  couple  of  drawbacks:  it  defines  ar¬ 
rays  only  for  single-precision  num¬ 
bers,  and  the  use  of  ARRAY  for  the 
name,  though  an  obvious  choice,  re¬ 
sults  in  awkward  and  un-English 
phrasing  in  the  source  code. 

You  will  note  that  the  stack  com¬ 
ment  following  DOES>  contains  one 
address  in  angle  brackets.  This  is  the 
address  that  DOES>  places  on  the 
stack  at  execution  time.  I  look  at  the 
stack  comments  as  I  write  the  defini¬ 
tion,  and  if  I  slip  and  forget  that  this 
address  is  present,  I  write  bugs.  I  put 
the  address  in  brackets  to  indicate 
that  it  is  supplied  by  the  word  itself. 

Listing  Three,  page  104,  shows  a 
more  flexible  array-defining  word:  It 
can  create  an  array  of  bytes,  cells,  or 
double-precision  numbers.  The 
name  FOR  is  used  instead  of  ARRAY  to 
make  the  code  read  more  naturally. 
Picking  good  names  for  Forth  words 
is  a  difficult  art;  you  can  be  led  astray 
by  an  impulse  to  name  words  accord¬ 
ing  to  their  internal  implementation 
rather  than  with  an  eye  to  their  use. 

At  creation  time,  FOR  stores  the  ar¬ 
ray  type  (the  number  of  bytes  an  en¬ 
try  occupies)  into  the  first  byte  of  the 
array  area  and  initializes  the  rest  of 
the  array  to  0s.  The  index  is  present¬ 
ed  at  execution  time,  and  the  type  is 
retrieved  (with  COUNT).  The  product 
of  the  type  and  the  index  then  gives 
the  offset  to  the  entry,  and  this  offset 
(possibly  0)  is  added  to  the  address  of 
the  first  entry. 

This  definition,  however,  makes 
the  programmer  pick  the  correct 
storage  or  retrieval  word.  Every  deci¬ 
sion  the  programmer  makes  repre¬ 
sents  an  opportunity  to  decide  incor¬ 
rectly.  Moreover,  if  I  happen  to  use 
the  wrong  storage  or  retrieval  word, 


it  is  hard  for  me  to  spot  the  error.  If 
the  right  kind  of  word  is  in  the  right 
place,  it  looks — well — right.  If  I  use 
@  with  a  byte  or  double-precision  ar¬ 
ray  (when  I  should  have  used  C@  or 
2(g)),  the  result  is  wrong,  but  I  have  a 
devil  of  a  time  seeing  the  error,  even 
when  I  am  looking  at  it. 

Listing  Four,  page  104,  shows  one 
solution:  give  that  responsibility  to 
the  array  word.  The  flags  PUT  and 
GET  determine  the  direction  in 
which  the  datum  will  move.  When 
the  array  word  is  executed,  the 
DOES>  clause  of  its  parent  FOR  uses 
the  type  number  (a  copy  of  which  it 
momentarily  stashes  on  the  return 
stack  while  it  does  other  work)  to  dip 
into  either  STORES  or  FETCHES  to  re¬ 
trieve  the  correct  operation  to  per¬ 
form.  (The  command  ]  turns  on  the 
compiler,  and  so  the  stores  and 
fetches  following  are  not  immediate¬ 
ly  executed;  rather,  their  (2-byte)  ad¬ 
dresses  are  stored  into  the  dictionary. 
The  [  turns  the  compiler  off  again.) 

I  often  use  bit  arrays  to  save  room. 
Listing  Five,  page  104,  shows  my  col¬ 
lection  of  bit  tools;  these  appeared  in 
a  slightly  different  form  in  an  article 
in  Computer  Language.  The  prefix  + 
for  "turn  on”  and  —  for  "turn  off” 
follow  naming  conventions  suggest¬ 
ed  by  Kim  Harris  (see  later).  I  use  ~  as 
a  prefix  meaning  toggle.  (cDBIT  uses 
the  word  FLAG  to  force  nonzeros  to 
the  83  Standard  Boolean  value  for 
true  (  —  1)  so  that  the  fetched  value 
will  work  appropriately  with  logical 
operators  such  as  AND  and  OR.  You 
should  note  that  the  NOT  in  the  defi¬ 
nition  of  —BIT  is  the  83  Standard  NOT, 
which  operates  bitwise  (as  do  the 
other  logical  operators  AND,  OR,  and 
XOR).  The  79  Standard  NOT  was  mere¬ 
ly  a  synonym  for  0= .  If  you  have  not 
yet  moved  to  an  83  Standard  Forth, 
you  should  replace  NOT  with  —1XOR. 

The  FOR  in  Listing  Six,  page  104,  can 
also  create  bit  arrays.  For  arrays  of 
bytes,  cells,  or  doubles,  this  FOR 
works  exactly  like  the  FOR  in  Listing 
Four  does.  The  range  of  values  that 
can  be  stored  in  a  bit  is  limited,  so  I 
embed  the  PUT  function  in  SET,  ZAP, 
and  FLIP  to  make  the  phrases  read 
better  in  the  bit  context. 

At  one  time  I  would  have  stopped 
here.  But  Kim  Harris  has  pointed  out 
that  whenever  you  create  a  new  data 
structure,  you  should  also  create  a 
word  to  display  its  contents.  These 
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"inspection”  words  inevitably  repay 
their  development  cost  as  soon  as  you 
begin  to  use  the  new  structures. 
(Think  of  trying  to  use  the  stack  with¬ 
out  .S  to  let  you  look  at  what's  there.) 

So  I  go  one  step  further.  The  dis¬ 
play  word  needs  to  know  how  many 
elements  to  display,  so  a  new  FOR  is 
shown  in  Listing  Seven,  page  105. 
This  FOR  stores  the  number  of  slots  as 
part  of  the  array  information.  I  then 
need  a  word  to  move  past  the  cell 
holding  the  array  size  to  the  byte 
where  the  type  is  stored.  Rather  than 
put  this  step  in  the  definition  as  a 
(subsequently)  mysterious  2+,  I  fac¬ 
tor  it  out  for  separate  definition  as 
>  TYPE.  If  I  move  to  a  32-bit  architec¬ 
ture,  I’ll  know  to  modify  this  word 
accordingly.  > DATA  is  defined 
similarly. 

My  first  impulse  was  to  have  SPILL 
just  be  a  constant  with  a  negative  val¬ 
ue.  FOR’ s  DOES>  clause  would  then 
be  modified  to  first  check  the  sign  of 
the  index.  If  the  index  was  positive, 
DOES>  would  do  its  usual  work  of 
storage  and  retrieval;  if  the  index  was 
negative,  DOES>  would  know  that 
what  was  wanted  was  a  display  of 
the  array  contents  and  it  would  in¬ 
clude  the  code  for  that. 

I  rejected  this  approach,  even 
though  FOR’ s  definition  could  still  be 
made  readable  by  factoring  out  some 
of  the  subfunctions.  The  display  func¬ 
tion  is  only  for  development,  but  FOR 
is  a  production  word  and  so  it  should 
not  include  development  tasks.  By  de¬ 
fining  the  display  word  separately,  I 
don't  have  to  include  it  in  the  produc¬ 
tion  version  of  the  program. 

Listing  Eight,  page  105,  shows  the 
development  of  SPILL,  which  expects 
to  be  followed  by  the  name  of  an  ar¬ 
ray.  SPILL  displays  only  five  double- 
precision  numbers  per  line  because 
of  their  potential  length;  otherwise 
ten  array  entries  are  shown  per  line. 
}LINE  starts  a  new  line  when  appro¬ 
priate.  My  naming  convention  for 
words  that  execute  conditionally  is  to 
use  J  as  a  prefix.  This  doesn't  match 
the  example  of  ?DUP,  but  I  prefer  to 
restrict  my  use  of  the  prefix  ?  to 
words  that  expect  a  flag.  You  can 
read  }  as  "maybe.” 

In  my  first  iteration  of  developing 
the  bit  display,  bits  were  shown  in 


the  "natural”  way,  as  Os  and  Is.  [Be¬ 
cause  (a )BIT  converts  bits  to  Boolean 
flags  (0  and  —  1),  I  used  NEGATE  to  pro¬ 
duce  more  conventional  bit  values  (0 
and  1)  for  the  display.]  On  testing  the 
word,  however,  I  found  that  I 
couldn’t  see  the  Is  for  the  Os.  So  I  re¬ 
vised  the  display  to  show  "off”  bits  as 
hyphens.  The  Is  of  the  "on"  bits  then 
stand  out  nicely. 

I  assumed  that  an  array  will  have 
fewer  than  10,000  elements,  and  so 
the  line  label  is  set  to  have  at  most 
four  digits.  In  fact,  the  display  word, 
like  the  array  word,  reflects  any 
number  of  assumptions  about  how 
the  data  should  be  presented.  These 
reflect  my  taste  and  requirements. 
(Two  examples  in  addition  to  those 
mentioned  above:  even  though  the  fi¬ 
nal  FOR  knows  the  number  of  slots  in 
the  array,  I  still  prefer  that  the  array 
word  not  perform  a  range  check  on 
the  index;  and  single-precision  num¬ 
bers  are  displayed  with .  instead  of  U. 
because  the  arrays  I  use  are  more 
likely  to  contain  negative  numbers 
than  addresses.)  It  is  the  strength  of 
Forth  that  you  can  tailor  these  tools  to 
suit  yourself. 

Warning  of  Parts 

I  have  learned  the  hard  way  that 
JOAN  and  JOHN  would  be  poor  names 
for  program  words.  Not  only  do  they 
fail  to  tell  the  reader  what  is  going  on 
but  they  also  are  spelled  the  same  ex¬ 
cept  for  the  difference  of  a  single  let¬ 
ter  and  (worse)  they  are  the  same 
kind  of  word.  You  might  type  "H” 
when  "A”  is  intended.  The  error  will 
be  accepted  because  JOHN  is  a  valid 
word.  The  program  will  even  work 
after  a  fashion  because  JOHN  and 
JOAN  fulfill  similar  functions.  And 
once  again  I  would  be  trying  to  find  a 
bug  that  consists  of  the  right  kind  of 
word — but  not  the  right  word — in 
the  right  place.  Whenever  possible,  I 
make  sure  that  names  differ  by  more 
than  a  single  letter. 

Another  poor  name  choice  that  I 
considered  briefly  was  TO  for  PUT. 
The  problem  with  TO  is  that  it  is  a 
homonym  for  2.  Homonyms  are  an 
annoyance  when  you  try  to  talk 
about  the  code. 

If  you  ever  use  hex,  it's  also  a  bad 
idea  to  use  names  that  could  be  num¬ 
bers.  This  problem  can  be  alleviated 
by  making  it  an  absolute  rule  to  write 
hex  numerals  with  a  leading  0. 


A  pattern  of  naming  Forth  words 
has  developed  slowly.  Kim  Harris  has 
compiled  a  reasonably  large  set  of 
naming  conventions  that  seem  to  be 
generally  accepted.  These  have  been 
published  as  an  appendix  to  Leo  Bro- 
die’s  Thinking  Forth  (Englewood 
Cliffs,  N.J.:  Prentice-Hall,  1984)  and  as 
papers  in  the  1984  Rochester  Forth 
Applications  Conference  Proceedings 
and  the  1983  FORML  Conference  Pro¬ 
ceedings. 

A  Number-Input  Word: 
Challenge  to  Readers 

Programmers  often  want  users  to  en¬ 
ter  numeric  information.  The  chal¬ 
lenge  is  to  develop  an  easy-to-use 
command  with  a  user-friendly  face. 
I'll  now  discuss  some  suggested  de¬ 
sign  specifications. 

Each  digit  is  displayed  on  the 
screen  as  it  is  entered.  The  display  is 
"calculator”  style,  with  digits  appear¬ 
ing  (and  disappearing)  at  the  right¬ 
most  end  of  the  number.  The  routine 
inserts  commas  in  the  display  as 
needed.  The  minus  key  operates  as  a 
toggle  (which  accommodates  the  usu¬ 
al  entering  the  minus  sign  at  the  be¬ 
ginning  but  also  permits  it  to  be 
turned  on  or  off  after  the  number  is 
underway).  Backspace  and  Delete 
(and  any  other  left-arrow  key  you 
might  have  on  your  computer)  rub 
out  the  rightmost  character  (which 
might  be  a  minus  sign  or  a  decimal 
point).  The  remaining  characters  in 
the  field  shift  one  place  to  the  right  to 
fill  the  gap.  Entering  "B”  or  "C"  (up¬ 
percase  or  lowercase)  erases  every¬ 
thing  that  has  been  entered.  Entering 
any  illegal  character  or  attempting  to 
delete  when  the  field  is  blank  results 
in  a  beep.  Thus  every  key  either  pro¬ 
duces  some  alteration  in  the  display 
or  sounds  a  bell. 

If  the  user  enters  a  0  to  start,  enter¬ 
ing  additional  0s  immediately  there¬ 
after  does  not  result  in  a  repeating  se¬ 
ries  of  0  (unless,  of  course,  a  decimal 
point  was  entered  first).  Other  digits 
do  repeat.  As  a  courtesy  to  the  user, 
the  letter  l  (uppercase  or  lowercase)  is 
accepted  as  the  number  1  and  the  let¬ 
ter  o  as  the  number  0. 

The  programmer  specifies  wheth¬ 
er  a  minus  sign  is  allowed;  if  it  is  not, 
pressing  the  minus  key  produces  a 
beep  but  no  entry.  Similarly,  if  the 
programmer  indicates  no  decimal 
places,  the  decimal  point  is  beeped  as 
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invalid  input. 

The  format  of  the  commands  the  i 
programmer  uses  to  manipulate  the  J 
routine  in  his  or  her  program  is  as 
follows: 

|  1.  n  PLACES — n  is  the  number  of 
places  to  the  right  of  the  decimal 
point.  The  value  presumably  is 
stored  in  a  variable.  The  number  the 
user  enters  is  collected  as  a  double- 
precision  integer,  so  the  number  of 
decimal  places  is  a  scaling  factor.  A 
decimal  point  is  a  legal  character  for 
the  user  to  enter  only  if  the  number 
of  places  is  greater  than  zero.  The  de¬ 
fault  is  zero  places.  If  the  user  presses 
|  Return  after  entering  only  the 
!  whole-number  portion  of  a  number 
I  with  decimal  places,  the  decimal 
j  point  and  trailing  Os  are  supplied  by 
the  routine. 

j  2.  NEG-OK  ON — NEG-OK  is  a  variable. 
The  default  value  is  false  (off).  Minus 
signs  are  accepted  only  if  NEG-OK  is 
on. 

3.  d  n  - 1  DIGITS  or  n  0  DIGITS— The 
true/false  flag  (embedded  in  some 
mnemonic  name)  tells  the  routine 
whether  it  is  being  supplied  with  a 
number  to  begin  with.  If  the  flag  is 
true,  the  (double-precision)  number  is 
displayed  in  the  entry  field  (with  com¬ 
mas,  minus  sign,  and  decimal  point  as 
appropriate)  for  the  user  to  accept  or 
alter  as  needed.  If  the  flag  is  false,  no 
number  is  supplied  and  the  routine 
begins  with  a  blank  entry  box. 

The  single-precision  number  n 
specifies  the  total  number  of  digits 
the  user  may  enter.  This  value,  to¬ 
gether  with  the  number  of  places,  de¬ 
termines  the  number  of  digits  al¬ 
lowed  to  the  left  of  the  decimal  point. 
The  sequence  2  PLACES  5  NEW  DIGITS, 
for  example,  means  that  there  will  be 
at  most  three  digits  to  the  left  of  the 
decimal  point  and  at  most  two  digits 
to  the  right.  ( NEW  here  is  assumed  to 
be  a  constant  equal  to  0.) 

DIGITS  presents  an  inverse-video 
field  at  the  current  cursor  location. 
The  field  allows  room  for  minus  (but 
only  if  NEG-OK  is  on),  for  commas  (but 
only  as  many  as  can  be  entered  given 
the  number  of  digits  allowed),  and 
for  a  decimal  point  (but  only  if  more 
than  zero  places  have  been  speci¬ 
fied).  The  field  includes  a  blank  in¬ 
verse  space  before  and  after  the 
spaces  needed  to  hold  the  number, 
sign,  commas,  and  decimal  point  of 


the  number  being  entered. 

When  the  user  signifies  the  end  of 
input  by  pressing  the  carriage  re¬ 
turn,  the  stack  contains  a  double-pre¬ 
cision  number  (the  value  of  the  entry) 
under  a  single-precision  number  (the 
number  of  digits  the  user  actually  en¬ 
tered).  This  allows  the  program  to 
distinguish  "no  entry”  from  an  en¬ 
tered  0. 

Send  me  your  own  solution,  pref¬ 
erably  in  an  83  Standard  Forth.  In  a 
future  column,  I'll  take  a  look  at  the 
results. 

Operating  Systems  and 
Text  and  Block  Files 

Forth  was  originally  its  own  operat¬ 
ing  system:  It  seized  control  of  the  en¬ 
tire  computer  and  handled  every¬ 
thing  itself.  This  Forth  operating 
system  included  a  simple  and  effec¬ 
tive  way  to  access  the  disk  directly 
using  a  block  number.  Each  block 
was  IK,  and  source  code  was  dis¬ 
played  on  the  screen  in  one-block 
chunks,  so  blocks  were  also  called 
"screens.” 

As  the  micro  world  grew  to  in¬ 
clude  more  applications  and  hard¬ 
disk  storage  became  more  common, 
the  omnipresence  of  the  operating 
system  became  inescapable.  Few  us¬ 
ers  were  willing  to  reboot  between 
applications  simply  so  that  Forth 
could  run  its  own  show,  and  fewer 
still  wanted  to  partition  their  hard 
disk  to  allow  different  disk  formats  to 
share  the  space.  (Embedded  applica¬ 
tions  do  not  have  this  problem,  of 
course,  and  the  Forth  operating  sys¬ 
tem  is  still  often  found  in  that  envi¬ 
ronment  as  well  as  in  totally  dedicat¬ 
ed  systems,  such  as  for  process 
control  and  data  acquisition.) 

Forth  now  commonly  runs  under 
an  operating  system  and  makes  use 
of  the  operating  system's  I/O  ser¬ 
vices.  Blocks  are  still  used,  but  in  this 
environment  they  reside  within  files. 

The  efficacy  of  the  block  files  is  a 
topic  of  perennial  debate.  Some  pro¬ 
grammers  prefer  text  files  so  that 
they  don't  have  to  group  the  source 
code  into  IK  blocks.  Others  accept  the 
modular  discipline  of  the  IK  chunks 
and  as  a  bonus  retain  the  the  ability  to 
incrementally  compile  a  module  un¬ 
der  development.  That  is,  they  load 
and  test  a  block  until  it  works;  write, 
load,  and  test  the  next  block;  and  so 


|  on — instead  of  reloading  the  entire  I 
file  with  each  change.  Block  files, 
with  their  separately  loadable 
blocks,  fit  the  interactive  program 
development  style  that  is  Forth's  spe¬ 
cial  tactic. 

One  practice  sometimes  seen  in 
block  files — using  block-number 
ranges  to  create  subfiles  within  a 
file — seems  worth  discarding.  With¬ 
in  a  block  file  a  programmer  might 
use,  for  example,  blocks  5—10  are  for 
one  module,  15  —  25  for  another, 
30—40  for  a  set  of  data  pointers,  and 
block  50  and  beyond  for  the  data. 
These  block-number  ranges  are  a 
hangover  from  the  "file”  systems 
S  typically  used  in  native-mode  Forths, 
when  the  only  disk  access  was  by 
block  number. 

The  gaps  in  the  block  ranges  are 
intended  to  simplify  expansion  and 
maintenance  of  the  "subfile”  system. 
Because  Forth  stores  IK  per  screen, 
though,  this  technique  eats  up  too 
much  storage  room  in  operating  sys¬ 
tems  such  as  MS-DOS  or  PC-DOS,  where 
files  cannot  have  gaps.  Moreover, 
adding  blocks  to  accommodate  new 
functions  will  often  throw  a  monkey 
wrench  into  the  numbering  scheme 
and  invalidate  the  block  numbers  in 
the  load  block. 

It  is  simpler  and  more  efficient  to 
exploit  the  strengths  of  the  file  system 
and  use  different  files  for  separate 
submodules  of  source  code.  Forths 
running  under  an  operating  system 
will  include  a  complement  of  file¬ 
handling  words  so  that  the  program 
can  open  and  close  files  as  needed.  [ 
Different  files  of  Forth  source  code, 
whether  block  or  text  files,  can  be 
called  during  a  load  sequence  with 
some  word  such  as  INCLUDE.  The  load 
block,  instead  of  specifying  block 
number  ranges,  can  INCLUDE  specific 
file  names,  and  those  files  can  expand 
or  contract  as  the  program  is  main¬ 
tained  and  revised,  with  no  effect  on 
the  load  instructions. 

Indeed,  if  a  particular  submodule 
(for  example,  the  number-input  rou¬ 
tine  described  earlier)  turns  out  to  be 
generally  useful,  it  is  quite  handy  to 
have  it  as  a  file  of  its  own  to  be  IN- 
CLUDEd  in  as  many  programs  as 
needed.  Some  Forths  allow  the  devel¬ 
oper  to  create  small,  relocatable  bina¬ 
ry  overlays  so  that  such  modules  can 
be  called  quickly  and  serve  as  a  com¬ 
ponent  of  a  Forth  library  of  tools. 
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Factoring  modules  into  separate 
files  is  an  extension  of  the  idea  of  fac¬ 
toring  functions  into  separate  words. 
A  Forth  programmer  learns  through 
experience  when  a  routine  deserves 
its  own  identity,  whether  as  word  or 
as  file. 

There's  no  denying,  however,  that 
blocks,  whether  in  files  or  in  native 
mode,  consume  a  lot  of  disk  space. 
Most  of  this  is  because  of  their  puffi¬ 
ness:  a  block  occupies  IK  of  disk 
space  even  though  a  considerable 
part  of  that  IK  may  be  blanks.  That’s 
why  Forth  programmers  dearly  love 
the  archiving  programs  that  squeeze 
out  the  blanks  when  the  file  is  stored 
in  archive  format.  My  archived  files 
are  typically  20  percent  of  their  origi¬ 
nal  size.  (This,  of  course,  includes 
compression  beyond  merely  squeez¬ 
ing  down  the  blanks.) 

The  program  I  use  is  a  shareware 
program  called  ARC.  It  is  under  con¬ 
tinuing  development  by  System  En-  1 
hancement  Associates  (21  New  Street, 
Wayne,  NJ  07470).  You  can  buy  it 
from  the  firm  for  $50,  but  it  prefers 
that  you  obtain  the  program  through 
the  normal  shareware  distribution 
channels.  Version  5.1  was  released  in 
January,  but  new  versions  appear 
with  disconcerting  frequency.  A  ver¬ 
sion  can  read  and  decompress  ar¬ 
chive  files  created  by  any  lower- 
numbered  version  but  not  vice  versa. 

ARC  builds  archive  files  that  con¬ 
tain  as  many  compressed  files  as  you 
want.  You  can  add  files  to  an  archive 
file  and  extract  them  quickly  when¬ 
ever  you  need  them;  it  is  also  easy  to 
update  an  archived  file  with  a  later 
version.  The  use  of  ARC  makes  the 
bulkiness  of  the  block  file  much  less 
of  an  issue. 

Background 

I  plan  to  be  a  regular  denizen  of  these 
pages,  so  you  might  want  some  idea 
of  my  programming  background  and 
Forth  experience.  I  started  program¬ 
ming  on  an  IBM  1401,  and  the  lan¬ 
guage  was  Autocoder.  From  there  I 
moved  on  to  FORTRAN,  dipped  into 
BASIC,  glanced  at  APL  and  Pascal,  and 
at  last  discovered  Forth  through  an 
article  in  DDJ  several  years  ago. 

I  got  a  copy  of  Miller  Microcomput¬ 
er  Services’  MMSForth  and  found 
Forth  irresistible.  Because  I  wanted  to 
share  and  sell  my  programs,  I  moved 
to  Forth  Technology’s  Forth/Level  2, 


a  spin-off  of  FORTH  Inc.'s  polyFORTH.  [ 
Forth/Level  2  required  no  license  j 
fees  or  royalties,  and  its  TURNKEY  j 
word  was  an  easy  way  to  produce 
bootable  programs. 

Finally,  however,  I  had  to  recog¬ 
nize  that  the  world  of  business  appli¬ 
cations  in  which  I  worked  was  in¬ 
creasingly  dominated  by  PC-DOS/MS- 
DOS.  Native-mode  Forths  did  not  fit 
that  environment  comfortably,  par¬ 
ticularly  as  hard  disks  became  more  J 
common.  I  moved  to  Laboratory  Mi¬ 
crosystems’  PC/Forth  because  it 
worked  well  with  DOS  and  because  it 
was  one  of  the  few  vendor-support¬ 
ed,  83  Standard  Forths  then  available. 

It  also  required  no  license  fees  or  roy¬ 
alties  for  turnkeyed  programs. 

I  did  not  really  consider  a  public- 
domain  Forth.  Because  I  write  pro¬ 
grams  for  a  living,  I  want  vendor  sup¬ 
port.  I  don’t  want  to  be  the  one  who 
has  to  write  every  extension  package 
and  constantly  track  new  technology 
and  adjust  my  system  to  fit.  I  feel  that 
my  time  is  better  spent  on  billable 
projects,  and  I  am  willing  to  pay  the 
minor  upgrade  charges  to  have  the 
vendor  keep  the  system  tuned  to 
new  machines  and  new  versions  of  1 
the  operating  system. 

Currently  I  am  completing  a  rea¬ 
sonably  large  Forth  application 
(about  a  thousand  screens),  a  soft¬ 
ware  package  that  will  be  published  j 
RSN.  I  am  also  an  outside  contractor  j 
for  Laboratory  Microsystems,  assist¬ 
ing  with  technical  support  and  docu¬ 
mentation — a  natural  progression 
from  my  own  extensive  use  of  the 
company's  technical  support. 

From  my  experience,  I  know  the 
above-mentioned  Forths  better  than  I 
do  others,  but  I  am  sure  that  my  read¬ 
ers  will  expand  my  horizons.  You  are 
welcome  to  write  to  me  on  the  DDJ 
Forum  on  CompuServe  or  care  of  the 
magazine.  I  look  forward  to  hearing 
from  you. 

DDJ 
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PROGRAMMER'S  SERVICES 

OF  INTEREST 


PCC/Systems  has  intro¬ 
duced  cc:Mail  for  local- 
area  networks.  With  this 
system,  users  of  the  IBM  PC 
and  compatibles  can  send, 
receive,  store,  and  edit 
electronic  message  enve¬ 
lopes.  Anything  created  on 
a  PC,  such  as  text,  graphics, 
data  files,  and  display 
screens  from  other  soft¬ 
ware  application  pro¬ 
grams,  can  be  sent  to  an¬ 
other  PC  in  an  envelope. 
The  cc:Mail  package  in¬ 
cludes  a  full-featured  word 
processor  with  a  built-in, 
felt-tip  highlighting  pen 
and  a  graphics/drawing 
package.  Users  have  a 
choice  of  color  palettes  and 
can  edit  materials  from 
other  sources.  Screen  con¬ 
tent  from  any  application 
program  can  be  frozen  to 
create  snapshots,  which 
can  then  be  edited  and  in¬ 
serted  into  messages.  Each 
message  can  include  any 
combination  of  up  to  20 
text,  graphics,  and  file 
items.  The  starter  package 
for  ten  users  costs  $995,  and 
expansion  kits  are 
available. 

Ashton-Tate  has  intro¬ 
duced  the  dBASE  III  Plus 
LAN  Pack,  designed  to  en¬ 
able  multiple  users  to  share 
dBASE  Plus  files  on  a  local- 
area  network.  Equipped 
with  built-in  multiuser  and 
stand-alone  capability, 
dBASE  III  Plus  can  network 
an  unlimited  number  of  us¬ 
ers.  Combining  one  dBASE 
III  Plus  with  one  LAN  Pack 
provides  a  four-user  net¬ 
work.  dBASE  III  Plus  and 


dBASE  III  Plus  LAN  Pack  can 
run  on  any  network  that 
supports  PC-DOS,  Version 
3.1,  including  the  IBM  PC 
Network,  3Com's  3Plus, 
and  Novell's  Advanced 
NetWare,  Version  1.01,  or 
later.  Other  LANs  that  use 
an  operating  system  com¬ 
patible  with  PC-DOS  3.1  can 
also  be  supported. 

Kyss!,  an  advanced  oper¬ 
ator  interface  with  system 
enhancement  facilities,  is 
available  from  The  Infor¬ 
mation  People.  Kyss!  in¬ 
cludes  a  menu  generator, 
extended  DOS  batch-pro¬ 
cessing  capabilities,  disk 
file  management,  job 
tracking,  and  a  text  display 
facility  for  preparing  on¬ 
line  instructions.  The  sug¬ 
gested  retail  price  is  $150 
for  single-user  versions; 
network  versions  begin  at 
$300  for  six-user  systems. 

The  MLink  Data  Commu¬ 
nications  System  from 
Corporate  Microsystems 
includes  the  Development 
System,  a  software  pack¬ 
age  recommended  for  sys¬ 
tem  developers.  MLink 
also  includes  terminal  em¬ 
ulation,  an  on-line  help  sys¬ 
tem,  a  configuration  sys¬ 
tem,  three  file-transfer 
protocols,  a  script  inter¬ 
preter,  a  script  debugger,  a 
script  assembler,  24  appli¬ 
cation  scripts,  and  script 
source  files.  The  system  is 
designed  to  facilitate  mi- 
cro-to-mainframe,  micro- 
to-micro,  PC-to-Unix,  and 
other  data-communication 
links.  Prices  vary  accord¬ 
ing  to  configuration. 

Information  Technol¬ 
ogies'  LinkUp  3270  SNA, 
3270  BSC,  and  3770  SNA  em¬ 
ulations  have  been  en¬ 
hanced.  The  products  fea¬ 
ture  foreground/ 

background  operations, 
enhanced  multiple  print¬ 
ing  capacities,  and  up  to  32 
simultaneous  sessions. 


They  support  printer  out¬ 
put  to  standard  DOS  print¬ 
ers,  a  high-speed  serial 
printer,  and  spooling  of 
print  files  to  disk.  All 
modes  can  be  driven  simul¬ 
taneously.  The  stand-alone 
coprocessor  version  is 
available  for  $995. 

VersaLAN  is  a  local-area 
network  solution  from 
Software  Clearing  House 
that  includes  software, 
hardware,  and  wiring. 
VersaLAN  can  handle  up  to 
32  PCs  and  is  compatible 
with  PC-DOS  and  MS-DOS 
and  the  IBM  PC  Network.  It 
also  has  software  hooks  so 
that  advanced  users  can 
program  it  to  add  functions 
such  as  private  data  en¬ 
cryption  or  links  to  user- 
written  software.  In  addi¬ 
tion,  VersaLAN  features 
electronic  mail,  file  trans¬ 
fer  between  micros,  and 
hard  disk  and  printer  shar¬ 
ing.  The  product  costs  $250 
per  PC;  additional  PC  con¬ 
nections  cost  from  $175. 

Polygon  Associates  has 
enhanced  its  poly-COM/240 
terminal-emulation  and 
file-transfer  communica¬ 
tion  software  package.  The 
package  now  offers  hot¬ 
key  control  for  switching 
between  a  DOS  screen  and 
VAX  terminal  session  with¬ 
out  losing  the  communica¬ 
tion  link,  instant  toggle  be¬ 
tween  text  and  graphics 
modes,  host  control  com¬ 
mands  for  unattended  or 
distributed  applications, 
and  a  screen-saver  func¬ 
tion  that  blanks  the  PC 
screen  after  a  defined  peri¬ 
od  to  reduce  video  screen 
wear. 

Security 

Several  products  that 
guard  against  unautho¬ 
rized  computer  access  are 
available  from  Digital 
Pathways.  The  Defender 
IID  provides  direct-dial  user 


verification.  The  verifica¬ 
tion  process  takes  only  one 
phone  call,  requiring  a  val¬ 
id  access  code,  password, 
and/or  SecureNet  Key  vali¬ 
dation.  The  Defender  Ilk  is 
a  data  encryption  manager 
for  highly  secure  dial-up 
links.  It  enables  remote  us¬ 
ers  with  PCs  to  install  an 
encryption  board  to  pro¬ 
tect  data  in  transmission. 
The  SecureNet  Key  pro¬ 
vides  an  additional  level  of 
security  for  any  Defender 
II  system.  Each  user  is  pro¬ 
vided  with  a  credit-card- 
size  key  that  has  been  ini¬ 
tialized  with  a  unique  key 
number.  The  user  then 
arms  the  key  with  a  per¬ 
sonal  identification  num¬ 
ber.  Prices  vary  according 
to  configuration. 

Release  2.0  of  System 
Automation  Software’s 
Logger  computer  resource 
monitor  is  a  RAM-resident 
program  that  tracks  and 
documents  the  everyday 
use  of  IBM  PC,  PC/XT,  PC/AT, 
and  compatible  comput¬ 
ers.  The  new  version  in¬ 
cludes  log-in  security  and  a 
summary  option  in  the  re¬ 
porting  subsystem  that 
summarizes  computer  us¬ 
age  by  user,  directory,  and 
program  and  calculates  the 
duration  of  each  activity. 
Logger's  retail  price  is 
$74.95. 

Artificial 

Intelligence 

XSYS  is  an  advisory  expert- 
system  shell  from  Califor¬ 
nia  Intelligence  that  runs 
on  IBM  PCs.  In  a  typical  sce¬ 
nario,  the  system  asks  the 
user  problem-related  ques¬ 
tions  and  displays  selection 
menus,  depending  on 
which  specialized  knowl¬ 
edge  base  the  user  has  se¬ 
lected  to  attach  to  the  ge¬ 
neric  XSYS  shell  program. 
The  system  can  also  ex¬ 
plain,  step-by-step,  its  pro- 
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gress  and  conclusions  dur¬ 
ing  and  after  each 
consultation.  XSYS’  facilities 
include  knowledge  attri¬ 
butes,  variables,  and  opera¬ 
tors  in  the  if  and  then  parts 
of  any  rule,  handling  of  un¬ 
certainty  and  negation, 
and  automatic  concatena¬ 
tion  of  hierarchically  relat¬ 
ed  knowledge  bases.  The 
system  requires  an  IBM  PC, 
PC/XT,  or  PC/AT  with  at 
least  640K  and  DOS  2.X.  The 
license  fee  for  a  single-CPU 
copy  is  $995. 

Borland  International's 

fifth-generation  language 
development  system,  Tur¬ 
bo  Prolog,  is  designed  to  in¬ 
fer  or  derive  information 
from  stated  facts.  The  PRO¬ 
LOG  language  employs  a 
theorem-proving  algo¬ 
rithm  for  logic  program¬ 
ming  in  order  to  take  a  set 
of  premises  and  arrive  at  an 
appropriate  conclusion. 
The  algorithm  utilizes  pat¬ 
tern  matching  and  back 
tracking.  Turbo  Prolog  is 
priced  at  $99.95  and  is  avail¬ 
able  for  IBM  PC  and  compat¬ 
ible  microcomputers. 

The  GCLisp  286  Develop¬ 
er  from  Gold  Hill  Comput¬ 
ers  includes  a  memory  in¬ 
terpreter  that  features 
lexical  scoping  and  the 
ability  to  address  up  to  15 
megabytes  of  physical 
memory.  It  also  features  a 
memory  compiler  de¬ 
signed  to  allow  applica¬ 
tions  to  run  up  to  15  times 
faster  than  normal.  The 
GCLisp  286  requires  an  IBM 
PC/AT  or  compatible  with 
at  least  2  megabytes;  PC-DOS 
3.0  or  later;  one  double-sid¬ 
ed,  double-density  or  quad- 
disk  drive;  and  a  hard  disk. 

Application 

Development 

Orchid  Technology’s  PC- 

turbo  286e  utilizes  an  8- 
MHz  80286  CPU,  80287 
match  processor  socket, 
and  a  16-bit  internal  system 
bus.  With  the  connection 
of  an  optional  RAM  card. 


the  PCturbo  286e  accom¬ 
modates  the  Lotus/Intel/ 
Microsoft  Expanded  Mem¬ 
ory  Specification.  PCturbo 
286e  with  1  megabyte  of 
RAM  costs  $1,195. 

MasterSweep-File  Main¬ 
tenance  Utility  is  a  disk  util¬ 
ity  from  The  Software 
Store  that  gives  users  ac¬ 
cess  to  disk  directories  and 
files.  It  enables  users  to 
find,  view,  copy,  print,  re¬ 
name,  move,  delete,  or  tag 
files,  and  it  supports  path 
directories  under  PC-DOS. 
MasterSweep  costs  $49  and 
is  available  for  PC-DOS  and 
CP/M-80  computers. 

PRO-C  is  a  software  pack¬ 
age  from  Majic  Software 
that  steps  a  developer 
through  an  application 
definition  and  then  gener¬ 
ates  a  C  program.  The 
product  comes  with  a  half¬ 
megabyte  of  context-sensi¬ 
tive,  on-line  help  that  is 
available  at  the  touch  of  a 
key.  Its  generic  record-re¬ 
trieval  mechanism  allows 
users  to  interface  a  gener¬ 
ated  program  with  an  ex¬ 
isting  file  system.  Alterna¬ 
tively,  users  can  select  the 
interface  to  industry  prod¬ 
ucts  such  as  Btrieve  and  C- 
ISAM.  The  C  compilers  cur¬ 
rently  supported  by  PRO-C 
are  Microsoft’s  Version  2.0, 
Lattice's  Version  2.15,  Com¬ 
puter  Innovations’  Version 
2.3F,  and  DeSmet's  Version 
2.4.  PRO-C  costs  $195. 

Fort’s  Software  has  an¬ 
nounced  V-EMM,  the  Virtu¬ 
al  Expanded  Memory  Man¬ 
ager.  V-EMM  provides  up  to 
8  megabytes  of  virtual  ex¬ 
panded  memory  and  can 
execute  many  unaltered 
programs  that  support  the 
Lotus/Intel/Microsoft  Ex¬ 
panded  Memory  Specifica¬ 
tion.  The  price  is  $89.95. 

Calvert  Computer  Sys¬ 
tems  has  released  Profes¬ 
sional  Applications  System 
(PAS)  software  for  program 
developers.  PAS  consists  of 
four  programs:  two  for 
generating  applications 


OF  INTEREST 


and  two  for  running  them. 
Programs  are  menu-driven 
and  support  full-screen 
editing,  color  systems, 
function  and  arrow  keys, 
and  unlimited  nesting  of 
menus.  PAS  applications 
can  run  any  .COM  or  .EXE 
program.  The  system  re¬ 
quirements  are  MS-DOS, 
256K,  two  360K  disk  drives, 
and  an  ANSI.SYS  driver.  The 
product  costs  $49.95. 

Specialized  Systems 
Consultants  has  an¬ 
nounced  an  IBM  PC,  PC/AT, 
or  Xenix  System  V  port  for 
its  Unix-based  Hitachi  6301 
C  Cross  Compiler.  The  port 
features  a  stack  frame  de¬ 
signed  to  minimize  over¬ 
head,  separate  compilation 
and  linking,  a  source-code 
optimizer,  and  a  run-time 
library. 

The  Synergy  Develop¬ 
ment  Toolkit  from  Matrix 
Software  Technology 
Corp.  provides  tools  for  ac¬ 
cessing  Synergy  run-time 
function  calls  from  a  wide 
range  of  languages.  These 
language  gateways  are  de¬ 
signed  for  the  IBM/MS  Mac¬ 
ro  Assembler,  Turbo  Pascal, 
IBM/MS  BASIC  Compiler  and 
Pascal  Compiler,  Lattice  C 
Compiler,  IBM/MS  BASIC  In¬ 
terpreter,  Microsoft  C  Com¬ 
piler,  and  dBASE  II/IH.  The 
toolkit  features  a  font  col¬ 
lection,  compiler,  manager, 
and  graphics  resource  edi¬ 
tor.  The  retail  price  is  $395. 

Microtec  Research  has 
introduced  the  ASM180 
cross  assembler  package,  a 
full  implementation  of  a 
relocatable  macro  assem¬ 
bler  for  the  Hitachi 
HD64180  microprocessor's 
specified  assembly  lan¬ 
guage.  ASM180  is  available 
on  DEC  VAX/VMS  and  Micro- 
VAX/VMS.  The  assembler 
features  a  compatible  in¬ 
struction  set  and  directives, 
conditional  assembly,  sym¬ 
bolic  addressing,  relative 


addressing,  and  symbol 
cross-reference  listing.  A 
binary  license  for  the 
ASM180  is  $2,000  for  the 
VAX  under  VMS  or  Ultrix. 

The  following  utilities 
are  available  from  Lattice: 
Lattice  Text,  a  collection  of 
eight  programs  that  pro¬ 
vide  a  set  of  tools  for  exam¬ 
ining  and  editing  text  files; 
Lattice  Make,  an  automat¬ 
ed  product  generator;  Lat¬ 
tice  Screen,  which  pro¬ 
vides  error  tracking;  and 
Lattice  dBC  III  Library, 
which  contains  more  than 
70  C  functions. 

BlueFish,  a  software 
product  from  Computer 
Access  Corp.,  provides 
full  text-management  ca¬ 
pability  for  users  of  IBM  PCs 
and  compatibles.  BlueFish 
can  handle  correspon¬ 
dence,  contracts,  medical 
journals,  government  reg¬ 
ulations,  engineering 
specifications,  legal  re¬ 
search,  insurance  docu¬ 
ments,  or  company  per¬ 
sonnel  records.  The 
software  operates  on  a 
minimum  configuration  of 
a  PC  with  256K,  one  disk 
drive,  and  PC-DOS.  The 
package  comes  in  two  con¬ 
figurations:  an  office-auto¬ 
mation,  full-test,  manage¬ 
ment  system  with  both 
build  and  search/retrieval 
modules;  and  a  search  and 
retrieval  module  designed 
for  publishers  of  data  dis¬ 
tributed  on  optical  or  other 
mass-storage  media.  Site  li¬ 
censes  start  at  $750  per  site. 

Languages 

PforCe,  a  library  of  object- 
oriented  functions  and  sub¬ 
systems  for  C,  is  available 
from  Phoenix  Computer 
Products  Corp.  Written  in 
C  and  assembly  language, 
PforCe  offers  programmers 
both  high-  and  low-level 
functions  that  are  ready  to 
use.  High-level  functions  al¬ 
low  programmers  to  ma¬ 
nipulate  windows,  screens 
of  fields  and  Lotus-like 
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menus,  and  databases  as  ob¬ 
jects.  Low-level  functions 
give  programmers  hard¬ 
ware  control  and  enable 
them  to  change  defaults  at 
will.  Sophisticated  subsys¬ 
tems  are  also  offered. 
I  PforCe  is  available  for  Mi¬ 
crosoft,  Lattice,  Computer 
Innovations,  and  Wizard 
compilers.  It  is  priced  at 
$395. 

The  Greenleaf  Comm  Li¬ 
brary  (Version  2.0),  a  pro¬ 
grammers'  tool  supporting 
C,  is  available  from  Green- 
leaf  Software.  More  than 
120  functions  are  provided 
to  support  communica¬ 
tions  at  up  to  9,600  baud,  up 
to  16  simultaneous  chan¬ 
nels,  XON/XOFF  and  XMO¬ 
DEM  protocols,  and  flow- 
control  options.  Version  2.0 
supports  PC-DOS  and  MS-DOS 
and  retails  for  $185. 

Absoft  Corp.  has  added 
I  two  members  to  the  Mac- 
Fortran  family:  MacFor- 
;  tran/020  and  MacFortran/ 
RL.  Both  were  designed  to 
take  advantage  of  new 
high-performance  Macin¬ 
tosh  hardware,  General 
Computer’s  HyperDrive 
2000,  and  Levco’s  MAC  Su¬ 
per  20FP.  MacFortran/020 
is  designed  to  generate 
code  for  Macintoshes  up¬ 
graded  with  an  MC68020 
CPU  and  MC68881  math  co¬ 
processor.  MacFortran/RL 
is  a  series  of  replacement 
run-time  libraries  for  Mac- 
Fortran  users  using  hard¬ 
ware  floating  point.  It  sup¬ 
ports  NS32081  boards,  the 
MC68881,  or  General  Com¬ 
puter's  HyperDrive  2000. 

FORTRAN-80  Utilities 
from  Cleydale  Engineer¬ 
ing  are  designed  to  comple¬ 
ment  the  Microsoft  FOR- 
TRAN-80  compiler,  which 
runs  under  CP/M-80.  These 
utilities  consist  of  an  opti¬ 
mized,  scientific,  subrou¬ 
tine  library;  Forlib.Rel 
j|  math  addition;  an  escape 
sequence  and  control  char¬ 
acter  generator  for  control¬ 
ling  peripheral  devices; 


and  three  FORTRAN  pro¬ 
gramming  tools.  Each  sub¬ 
routine  module  is  fur¬ 
nished  with  a  demonstra¬ 
tion  driver  program. 
Subject  areas  include  linear 
and  nonlinear  regression 
analysis  for  curve  fitting  ex¬ 
perimental  data,  statistics, 
matrix  operations,  simulta¬ 
neous  equations,  forward 
and  inverse  fast  Fourier 
transforms,  numeric  inte¬ 
gration,  equation  roots,  and 
graphics.  The  entire  pack¬ 
age  consists  of  60  files  occu¬ 
pying  238K  of  disk  storage 
and  is  distributed  in  the 
standard  single-sided,  sin¬ 
gle-density  CP/M  format. 
The  cost  is  $49.95. 

TDI  Software  has  re¬ 
leased  the  UCSD  Pascal  com¬ 
piler,  which  includes  the  p- 
System  operating  system, 
for  the  Atari  520ST.  UCSD 
Pascal  features  support 
units  for  separate  compila¬ 
tion,  assembly-language 
procedures,  full  implemen¬ 
tation  of  Pascal,  and  a  full¬ 
screen  editor.  The  product 
is  available  in  a  regular  and 
a  developers'  version.  In  ad¬ 
dition  to  the  UCSD  Pascal 
compiler  and  p-System  op¬ 
erating  system,  the  devel¬ 
opers'  version  contains  an 
M68000  assembler,  a  native 
code  generator,  a  symbolic 
debugger,  and  assorted  Pas¬ 
cal  units  for  manipulating 
directories  and  performing 
systems  work.  UCSD  Pascal 
for  the  Atari  520ST  is  priced 
at  $79.95;  the  developers’ 
version  is  priced  at  $149.95. 

Philon’s  Fast/Pascal  is  a 
high-quality  compiler  de¬ 
veloped  for  use  by  pro¬ 
grammers  in  the  scientific 
and  educational  communi¬ 
ties.  It  is  designed  for  the 
16-  and  32-bit  environ¬ 
ments.  Programs  written 
in  Fast/Pascal  are  portable 
to  other  hardware/operat¬ 
ing  systems.  It  is  fully  com¬ 
patible  with  IEEE  standard 
floating-point  real  arith¬ 
metic,  and  system  calls  are 
executable  from  within 


the  language.  The  package 
also  contains  a  set  of  run¬ 
time  libraries,  file-han¬ 
dling  routines,  and  string- 
handling  capabilities. 

MasterForth,  which  is 
available  from  Micromo¬ 
tion,  is  an  implementation 
of  the  Forth  programming 
language  that  includes  a 
68000  macro  assembler 
and  a  full  interface  to  CP/M 
68K.  Relocatable  utilities 
and  transient  definitions 
make  it  possible  to  run  soft¬ 
ware  packages,  and  a 
string  package,  screen  edi¬ 
tor,  and  resident  debugger 
are  standard  features.  Mas¬ 
terForth  is  also  available 
for  the  Macintosh,  the  IBM 
PC  family,  the  Apple  II  fam¬ 
ily,  the  Commodore  64, 
and  CP/M  Z80  machines.  It 
retails  for  $125. 

For  IBM/ Apple 

Release  1.2  of  TextBank 
from  Group  L  Corp.  offers 
improved  performance 
through  the  use  of  extend¬ 
ed  memory,  support  for  ad¬ 
ditional  storage  devices, 
several  extensions  to  the 
search  and  user  interface, 
profiles  of  the  most  widely 
used  Dialog  and  BRS  on-line 
databases  to  make  informa¬ 
tion  searchable  when 
downloaded,  and  full  sup¬ 
port  for  individual  text  files 
of  up  to  20  megabytes.  Text- 
Bank  requires  an  IBM  PC  or 
compatible  with  640K,  a 
hard  disk,  and  MS-DOS.  It  is 
available  for  $995. 

The  Polytron  Version 
Control  System  (PVCS)  from 
Polytron  Corp.  is  a  source- 
code  version  and  revision 
management  system  for 
programmers  or  teams  of 
programmers  developing 
large  or  complex  programs 
on  PCs  and  networks.  The 
system  maintains  the  revi¬ 
sion  history  of  source  files 
and  chronological  and  his¬ 
torical  records  of  changes. 
It  reconstructs  any  prior  re¬ 
vision  of  any  module,  de¬ 
fines  a  version  as  specified 


revisions  of  various  mod¬ 
ules,  and  supports  branch¬ 
ing  from  prior  revisions. 
Disk  space  is  conserved  by 
an  intelligent  difference  de¬ 
tector  that  stores  only  the 
difference  between  succes¬ 
sive  revisions  of  a  module. 
A  single-user  licence  is 
available  for  $395. 

Show  Partner,  a  memo¬ 
ry-resident  graphics  editor 
with  animation,  is  avail¬ 
able  from  The  Marketing 
Channel.  One  image  can 
quickly  and  completely  re¬ 
place  another,  and  wipe, 
split,  and  box  effects  per¬ 
form  their  transitions 
along  traveling  event  line 
edges  moving  up  or  down, 
left  or  right,  together  or 
apart,  or  in  or  out.  Show 
Partner  also  offers  a  scroll 
effect  in  any  of  four  direc¬ 
tions,  fade-in  of  a  selected 
area,  and  two-part  weave 
of  an  area.  The  program 
loads  into  RAM  alongside 
other  applications  and  can 
also  work  in  a  nonresident 
stand-alone  mode.  Text  or 
graphic  screens  are  cap¬ 
tured  from  any  source  and 
saved  as  named  files.  The 
program  has  the  ability  to 
add  or  change  colors,  size 
rotate,  move  graphics,  and 
add  text  to  graphics.  Show 
Partner  supports  IBM  CGA 
and  EGA  displays  as  well  as 
the  AST  ColorGraphPlus 
palette  display,  AST  Pre¬ 
view,  or  Hercules-compati¬ 
ble  monochrome  graphics 
adapters.  It  costs  $149. 

Version  3  of  Portable 
Software’s  PortaAPL  soft¬ 
ware  package  for  the  Mac¬ 
intosh  is  a  full-featured  in¬ 
terpreter  for  standard  APL. 
PortaAPL  features  a  full¬ 
screen  editor,  the  ASCII 
character  set  option,  and 
the  Host  File  System  option. 
Also,  system  functions  are 
available  for  accessing 
many  of  the  Macintosh 
toolbox  ROM  routines,  such 
as  QuickDraw  graphics, 
communications,  sound 
generation,  and  menus. 
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The  package  for  the  Macin¬ 
tosh  is  priced  at  $275.  Cur¬ 
rent  customers  can  up¬ 
grade  to  Version  3  for  a  $25 
fee. 

Reference  Map 

Absoft  Corp.,  4268  N. 
Woodward,  Royal  Oak,  MI 
48072;  (313)  549-7111.  Read¬ 
er  Service  Number  16. 
Ashton-Tate,  20101  Hamil¬ 
ton  Ave.,  Torrance,  CA 
90502-1319;  (213)  329-8000. 
Reader  Service  Number  17. 
Borland  International 
Inc.,  4585  Scotts  Valley  Dr., 
Scotts  Valley,  CA  95066; 
(408)  438-8400.  Reader  Ser¬ 
vice  Number  18. 
California  Intelligence, 
912  Powell  St.,  #8,  San  Fran¬ 
cisco,  CA  94108;  (415)  391- 
4846.  Reader  Service  Num¬ 
ber  19. 

Calvert  Computer  Sys¬ 
tems  Inc.,  240  E.  Main  St., 


P.O.  Box  95,  Athena,  OR 
97813;  (503)  566-3338.  Read¬ 
er  Service  Number  20. 
Cleydale  Engineering, 
Rte.  1,  P.O.  Box  217-B, 
Blacksburg,  VA  24060. 
Reader  Service  Number  21. 
Computer  Access  Corp., 
Ste.  324,  26  Brighton  St.,  Bel¬ 
mont,  MA  02178-4008;  (617) 
484-2412.  Reader  Service 
Number  22. 

Corporate  Microsystems 
Inc.,  P.O.  Box  277,  Etna,  NH 
03750;  (603)  448-5193.  Read¬ 
er  Service  Number  23. 
Digital  Pathways  Inc.,  201 
Ravendale  Dr.,  Mountain 
View,  CA  94043;  (415)  964- 
0707.  Reader  Service  Num¬ 
ber  24. 

Fort’s  Software,  P.O.  Box 
396,  Manhattan,  KS  66502; 
(913)  537-2897.  Reader  Ser¬ 
vice  Number  25. 

Gold  Hill  Computers  Inc., 
163  Harvard  St.,  Cam¬ 
bridge,  MA  02139;  (617)  492- 
2071.  Reader  Service  Num¬ 
ber  26. 


Greenleaf  Software  Inc., 
1411  LeMay  Dr.,  Ste.  101, 
Carrollton,  TX  75007;  (214) 
446-8641.  Reader  Service 
Number  27. 

Group  L  Corp.,  481  Carlisle 
Dr.,  Herndon,  VA  22070; 
(703)  471-0300.  Reader  Ser¬ 
vice  Number  28. 
Information  People 
(The),  443  Hudson  Ave., 
Newark,  OH  43055;  (614) 
349-8644.  Reader  Service 
Number  29. 

Information  Technol¬ 
ogies  Inc.,  7850  E.  Evans 
Rd.,  Scottsdale,  AZ  85260; 
(602)  998-1033.  Reader  Ser¬ 
vice  Number  30. 

Lattice  Inc.,  P.O.  Box  3072, 
Glen  Ellyn,  IL  60138;  (312) 
858-7950.  Reader  Service 
Number  31. 

Majic  Software  Inc.,  224  S. 

Salisbury,  Ste.  C4,  West  La¬ 
fayette,  IN  47906;  (317)  743- 
0610.  Reader  Service  Num¬ 
ber  32. 

Marketing  Channel  Ltd. 
(The),  120  E.  Washington 
St.,  Ste.  421,  Syracuse,  NY 
13202;  (315)  474-3400.  Read¬ 
er  Service  Number  33. 
Matrix  Software  Tech¬ 
nology  Corp.,  50  Milk  St., 
15th  Floor,  Boston,  MA 
02109;  (617)  723-8327.  Read¬ 
er  Service  Number  34. 
Micromotion,  8726  S.  Se¬ 
pulveda  Blvd.,  0A171,  Los 
Angeles,  CA  90045;  (213) 
821-4340.  Reader  Service 
Number  35. 

Microtec  Research,  3930 
Freedom  Cir.,  Santa  Clara, 
CA  95054;  (800)  554-5554,  in 
CA  (408)  733-2919.  Reader 
Service  Number  36. 

Orchid  Technology, 
47790  Westinghouse  Dr., 
Fremont,  CA  95439;  (415) 
490-8586.  Reader  Service 
Number  37. 

PCC/Systems,  480  Califor¬ 
nia  Ave.,  Ste.  201,  Palo  Alto, 
CA  94306;  (415)  321-0430. 
Reader  Service  Number  38. 
Philon  Inc.,  641  Avenue  of 
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— Wendelin  Colby 
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FORUM 


The  declaration  that  some  British  j 
colonists  on  this  continent  made 
of  their  independence  200-odd  years  ; 
ago  this  month  was  not  the  first  re-  | 
hellion  against  a  regime  regarded  as  j 
tyrannical,  of  course;  nor  was  the  j 
government  they  later  formed  the 
first  democracy.  Nothing  ever  hap-  ; 
pens  for  the  first  time. 

ThC  authors  of  the  Declaration  of  In¬ 
dependence  were  particularly  elo- 
quent  in  their  defense  of  the  rights  of 
the  nonindentured  adult  white  male, 
and  over  the  succeeding  centuries 
various  of  their  descendants  have 
been  eloquent  about  the  need  to  ex¬ 
tend  recognition  of  those  rights  to  all 
Americans.  Others  have  been  equally 
eloquent  about  the  need  to  deny  such 
rights  to  blacks,  women,  homosex¬ 
uals,  and  people  of  suspect  ancestry  in  I 
time  of  war.  Americans  are  often  elo¬ 
quent  on  the  subject  of  independence, 
even  if  a  little  afraid  of  it  in  practice.  ; 
Just  think  what  they'd  be  like  if  they  j 
were  as  independent  as  they  are  elo¬ 
quent.  Why,  they'd  be  like  Forth 
programmers. 

Forth  programmers  seem  to  be  a 
particularly  independent  bunch.  Flic  j 
common  explanation,  which  is  proba¬ 
bly  correct,  is  that  the  language  en¬ 
courages  independent  thinking.  If  so, 
it  fully  justifies  this  special  Forth  issue, 
our  sixth.  Events  in  the  Forth  commu¬ 
nity  are  no  less  interesting  now  than  1 
in  1981  when  we  started  this  annual 
tradition.  In  last  year's  Forth  issue, 
you  may  recall,  Led  Brodie  led  a  tour 
of  the  architecture  of  the  then-new 
Novix  Forth  chip,  a  structure  for 
which  Forth  creator  Charles  Moore 
did  the  blueprints.  Now  Harris  Semi-  j 
conductor  has  acquired  a  Novix  li¬ 
cense  and  is  supplying  bit-slice  ver¬ 
sions  of  the  design.  What  this  added 
support  could  mean  to  Novix  and  to 
Harris  will  be  determined  by  the 
Forth  programming  community.  Pre¬ 
dictions  are  foolhardy. 

It  had  been  exactly  two  years,  I  re¬ 
marked  last  month  in  this  space. 


SWAINE'S  FLAMES 


since  we  had  reviewed  Borland's 
Turbo  Pascal,  and  now  here  was  Tur¬ 
bo  Prolog  knocking  at  the  door.  Well, 
not  exactly  at  the  door,  but  1  did  final¬ 
ly  manage  to  get  my  beta  and  final 
versions  of  the  new  Turbo  Prolog 
without  driving  to  Scotts  Valley  and 
have  since  been  comparing  notes  on 
the  product  with  Juergen  Fey,  an  edi¬ 
tor  with  PC  Magazin.  (PC  Magazin  is 
the  magazine  that  Markt  &,  Technik, 
M&.T  Publishing's  Prussian  parent 
publisher,  puts  out  for  the  fairly  tech¬ 
nical  PC  readership  in  West  Germa¬ 
ny,  and  Juergen  is  one  of  its  more 
technical  editors.) 

Turbo  Prolog  is  PROLOG,  Juergen 
thinks,  in  the  same  sense  that  Turbo 
Pascal  is  Pascal.  The  user  interface  is 
excellent,  the  performance  is  fast, 
and  there  are  many  extensions  that 
overcome  deficiencies  of  pure  PRO¬ 
LOG.  The  result — our  preliminary 
impression  only— is  that  Turbo  Pro¬ 
log  is  at  least  a  very  good  environ¬ 
ment  for  learning  Turbo  Prolog.  Be¬ 
yond  that — well,  we  are  planning  to 
review  the  product  in  the  near  fu¬ 
ture,  and  we  ll  evaluate  it  as  a  lan¬ 
guage  implementation  for  first-time 
users,  as  a  serious  development  envi¬ 
ronment,  and  as  a  PROLOG  imple¬ 
mentation.  We'll  consider  what  its 
existence,  price,  and  ease  of  use  could 
mean  for  the  spread  of  PROLOG,  and 
we  ll  evaluate  its  speed  in  light  of 
Borland's  claims  and  determine 
what  the  programmers  gave  up  for 
the  speed  they  got. 

Borland  has  taken  some  brave 
steps  in  the  past;  1  wonder  if  its  inde¬ 
pendent  spirit  will  be  affected  if  the 


|  company  goes  public  this  year,  as 
;  seems  likely. 

As  an  editor  anti  writer  1  count  the 
I  freedom  to  read  among  those  rights 
alluded  to  at  the  top  of  this  page,  and  1 
would  not  be  an  editor  if  I  failed  to 
bring  to  your  attention  the  cloud  of 
censorship  that  is  once  again  moving  j 
over  this  country.  It  s  starting  with 
"adult"  (i.e.,  adolescent)  entertain- 
|  ment,  with  guidelines  on  the  treat- 
;  ment  of  sex  in  films  and  the  removal 
of  Playboy  et  al.  from  convenience 
j  stores.  DDJ  isn't  in  the  prurient  inter- 
1  est  business,  of  course,  but  we  are 
currently  running  an  on-line  confer- 
|  ence  on  the  politically  charged  issue 
of  data  encryption,  and  I  doubt  that 
the  cloud  will  stay  over  someone 
else’s  backyard  for  long. 

Ray  Borrill,  a  pioneering  computer 
retailer,  recently  flamed  to  me  about 
the  wild  crowd  at  the  Midwest  Com¬ 
puter  Show  in  1976,  where  he  shared  j 
a  booth  with  Bob  Marsh  and  Steve 
Dompier  of  Processor  Technology.  It 
reminded  me  of  the  Atari  and  Com¬ 
modore  booths  this  year  in  Atlanta, 

!  packed  with  independent  third-par- 
j  ty  developers.  In  the  otherwise  stuffy 
Comdex  atmosphere,  the  air  in  those 
booths  was  almost  giddy  almost 
:  evocative  of  1976. 

Desktop  publishing  was  the  big  j 
thing  at  Comdex  this  year,  with  laser 
printers  and  document  scanners 
coming  down  in  price.  Phoenix  held 
a  meeting  for  80386  developers  to  dis-  j 
cuss  setting  80386  standards  before  | 
IBM  does  it.  Despite  a  lot  of  talk  that 
copy  protection  is  going  the  way  of 
King  George,  the  Tories  of  Lotus  seem 
unconcerned;  meanwhile,  Central 
Point  Software,  purveyor  of  guns  to 
the  rebels,  is  looking  into  supplying  ! 
;  armor  to  the  redcoats. 

Michael  Svvaine  j 
editor-in-chief 
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C  COMPILERS:  Benchmarking  C  Compilers  30 

j  by  Richard  Relph,  Steve  liahn,  Fred  Viles 
I  It's  said  that  in  the  high-stakes  poker  palaces  of  San  Jose, 

I  California,  lowball  games  have  been  known  to  run  for 
|  w'eeks,  the  players  coming  and  going  without  affecting  the 
game.  Since  we  published  our  first  extensive  comparative 
|  review  of  C  compilers  for  MS-DOS  last  year,  several  players 
{  have  cashed  in  their  chips  and  moved  on,  but  new 
j  players  such  as  IBM — have  arrived.  The  review  team  has 
again  wielded  its  collection  of  surgical  benchmarks,  each 
designed  to  measure  a  particular  aspect  of  compiler 
performance,  and  it's  added  a  typical-performance 
!  benchmark,  the  dhrystone. 


COLUMNS 


C  CHEST:  An  AVL  Tree  Database  Package  20 

j  by  Allen  Hoi ub 

Allen  presents  a  solution  to  the  problems  that  arise  when 
von  insert  a  sorted  list  of  keys  into  a  binary  tree. 

16-BIT  SOFTWARE  TOOLBOX:  Forth  and  the  VMS  70 

j  by  bn  v  Duncan 

Ray’s  source  code  for  the  PC- Forth  interface  he  introduced 
in  July 

STRUCTURED  PROGRAMMING:  Generic  Routines  in  116 
Ada  and  Modula-2,  Pascal  Iterators 

!  Namir  Clement  Shammas 

Namir  shows  how  to  get  around  the  limitations  of  data 
typing.  He  describes  routines  that  handle  different-size 
1  arrays  w  ith  the  same  data  types  and  then  explains  routines 
that  handle  different  data  types.  Namir  also  takes  a  look  at 
a  new  extended  for  loop  in  a  Pascal  compiler. 
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by  Michael  Swaine 

About  the  Lover 

Tom  Upton  did  t  lie  cover  photog¬ 
raphy  I'he  hand  belongs  to  Jill 
A.  Meniketti. 

This  Issue 

In  our  second  annual  review  of  C 
compilers  for  MS-DOS  we  im¬ 
prove  and  expand  the'  process 
we  used  last  August.  This  year, 
we  present  in-depth  evaluations 
and  comparisons  of  17  compil¬ 
ers.  Allen  Hoiuh  continues  his 
discussion  of  binary  trees.  In 
Structured  Programming,  Namir 
Shammas  shows  how  to  use*  ge¬ 
neric  routines  in  Modula-2  and 
Ada  to  avoid  reinventing  the 
wheel  for  different  data  ty|x?s. 


Next  Issue 

The  draftsman's  spline,  used  to 
draw  curves,  is  a  rapidly  disap¬ 
pearing  tool,  lo  our  algorithm  is¬ 
sue,  Ian  I  .  Ashdown  develops  a 
mathematical  mode!  of  the  draft¬ 
ing  tool.  Ian  shows  how  to  use? 
this  model  to  develop  a  program 
that  can  interpolate  a  smooth 
curve  between  a  set  of  given 
points. 
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It  looks  like  the  re¬ 
sults  are  starling  to 
come  in. 


I’his  month's  issue  is 

dominated 
jj^V.  view 

B  y*  for  MS-tXiS.  lu  all, 

teen  companies  sub- 
■  Bj  mitted  compilers  for 

I  I  ’*le  de,a‘let*  bench- 

I  ■  marking.  They  are: 

C  Ware  Corp.,  P.O.  Box  C,  Sunnyvale, 
CA  94087;  (408)  720-9696 
Computer  Innovations,  980  Shrews¬ 
bury  A vc.,  Tinton  Falls,  NJ  07724;  (201) 
542-5920 

Dalalight,  11557  8th  Ave.  NE,  Seattle, 
WA  98125;  (206)  367-1803 
Ecosoft  Inc.,  6413  N.  College  Ave.,  In¬ 
dianapolis,  IN  46220,  (317)  255-6476 
IBM,  1000  N.W.  51st  St.,  Boca  Baton,  FL 
33432;  (305)  998-2000 
Lattice,  P.O.  Box  3072,  Glen  Ellyn,  1L 
60138;  (312)  858-7950 
Manx  Software  Systems,  P.O.  Box  55, 
Shrewsbury,  NJ  07701;  (800)  221-0440 
Mark  Williams  Co.,  1430  W. 
Wrightwood  Ave.,  Chicago,  IE  60614; 
(312)  472-6659 

MetaWare,  412  Liberty  St.,  Santa 
Cruz,  CA  95060;  (408)  429-6382 
Microsoft,  16011  N.E.  36th  Way.,  P.O. 
Box  97017,  Redmond,  WA  98073-9717; 
(206)  882-8080 

Mix  Software,  21 16  E.  Arapaho,  Ste.  363, 
Richardson,  l'X  75081;  (214) 783-600 1 
Software  Toolworks  15233  Ventura 
Blvd.,  Ste.  1118,  Sherman  Oaks,  CA 
91403;  (818)  986-4885 
Whitesmiths  Ltd,,  97  Lowell  Kd.,  Con¬ 
cord,  MA  02174,(800)225-1030 
Wizard  Systems  Software,  11  Willow 
Ct.,  Arlington,  MA  02174;  (617)  641- 
2379 

WordTech  Systems  Inc.,  21  Aharinda 
Rd. ,  Or  inda,  CA  94563 ;  (4 15)  254-0900 


message,  "Good  eve-  I  1m 
ning  from  Captain  I 
Midnight.  S  12.95  a  HL  Hi 
month?  No  way.  Showtime  Movie 
Channel  Beware.” 

Or  maybe  you  weren’t  surprised. 
Wasn't  it  inevitable  that  satellite  tele¬ 
vision  would  get  its  own  Captain 
Crunch? 

Apparently,  Captain  Midnight's 
beef  is  that  HBO  has  begun  scram¬ 
bling  its  broadcasts  in  response  to  the 
increasing  use  of  dish  antennas  that 
allow  the  user  to  receive  satellite 
broadcasts  such  as  hbo’s  without 
paying.  The  $12.95  the  Captain  re¬ 
ferred  to  is  HBO  s  monthly  charge  for 
descrambler  boxes. 

The  Showtime  Movie  Channel  was 
threatened  because  Showtime  is  con¬ 
sidering  using  a  similar  scrambling 
scheme. 

What  the  Captain  has  done,  accord¬ 
ing  to  a  repor  t  in  the  British  journal 
New  Scientist,  is  prove  that  “it  is  tech¬ 
nically  possible  for  third  parties  to  hi¬ 
jack  a  broadcast  satellite  and  hold  the 
cable  industry  to  ransom.”  And  if 
such  third  parties  only  operate  in 
brief  bursts,  they  may  be  extremely 
hard  to  track  down. 

Science  fiction  writer  and  telecom¬ 
munications  expert  Arthur  C.  Clarke 
did  some  projections  over  20  years 
ago  and  found  that  the  amount  of 
power  available  to  the  average  indi¬ 
vidual,  extrapolated  from  past  fig¬ 
ures,  will  go  asymptotic  before  the 
year  2000.  Because  infinite  power  is 
meaningless,  Clark  concluded  that 
we'd  just  have  to  wait  and  see  how 
much  power  would  be  available  to 
whom  and  what  would  be  done  with 
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Seeing  C  in  'S3 

"The  buzz  is  that  C  is  the  answer  to  our 
prayers,  an  expressive  notation  that  com¬ 
piles  to  efficient  code.”--  D.E.  Cartesi,  I >10, 
November  1983. 

I'm  switching  from  a  language  that  I 
deeply  like  (Pascal!  to  one  that  I'm  uncom¬ 
fortable  with  (C)  simply  because  it  is  a  tet¬ 
ter  choice. "'  Peter  Norton,  PC,  September 
1983. 

‘  C  .  . .  I  don't  expect  it  ever  to  become  a 
highly  popular  language." — Jerry  Pour- 
nelle.  Byte,  August  1983. 

F1ME  Well  Grounded 

In  a  few  months.  A  T&T  will  surely  no¬ 
tice  lhat  the  Unix  PC  [built  by  Convergent 
Technologies!  is  not  selling,  bet  us  assume 
that  AT&T  succeeds  in  stopping  produc¬ 
tion  after  only  SO, 000  Unix  PC 'a  have  been 
built.  Of  that  50,000  about  10,000  will  have 
teen  sold.  AT&T  will  purchase  8,500  itself, 
the  recently  divested  operating  companies, 
many  of  which  have  not  yet  wised  up,  will 
buy  1,483  units,  and  the  rest  of  the  world 
will  buy  17." — Hal  llardenbergh  (a.k.a, 
FNE 1,  (H  ack  Grounded,  June  1985. 

"last  year,  Convergent  shipped  some 
40,000  to  50,000  of  the  Unix  PC  units.  But 
AT&T  has  only  sold  10,000  .  .  .  and  many  of 
those  were  sold  to  AT&T's  own  divisions 
AT&T  has  said  that  the  Unix  PC ...  is 
ahead  of  its  time.' — Bnenton  II.  Schlender, 
Wall  Street  Journal,  May  30,  1989. 

10  Years  Ago  in  DDJ 

This  bus  structure  as  defined  by  MIT'S 
has  become  a  de  facto'  standard.” — IX 
Denney  anil  J.  Broom,  DDJ,  August.  1376'. 

"The  time  for  floppies  is  just  about  now 
Gary  Kildall  is  .  hoping  to  be  able  to  offer 
a  controller  in  the  neighborhood  of 
$350."  -Jim  Warren,  DDJ,  August  1976. 

"One  of  the  features  of  NCC  '77  will  be 
presentation  of  papers  pertaining  to  per¬ 
sonal  computing  A  milestone  for  personal 
computing!'' — Harold  A.  Mauch,  DDJ,  Au¬ 
gust  1976. 

"Although  these  routines  are  for  the 
6502  .  . .  I  they  could  be  modified!  for  most 
of  the  traditional  microprocessors  relative¬ 
ly  easily.  (Theyl  were  done  by  Steve  Woz 
niak."  Jim  Warren,  DDJ,  August  1976. 

'"There  are  some  tentative  rumors  being 
passed  about  concerning  a  Computer 
Fa  ire  ...  bet  us  know  if  the  prospect 

.  interests  you."  Jim  Warren,  DDJ,  Au¬ 
gust  1976. 

'. . .  the  8080  sets  the  parity  flag  on  teth 
logical  and  arithmetic  operations.  Since  Bill 
Gate's  [sic]  Altaic  BASIC  uses  tin's  8080  ec¬ 
centricity  . .  .  Altaic  BASIC  will  not  run  on  a 
Z80 .“-—Jim  Warren,  DDJ,  August  1976. 

"Three  groups  (have!  boards  or  micro¬ 
computers  based  on  /.ilog's  hot  new  m-p, 
the  Z80:  the  Digital  Group,  TDb,  and  Cro- 
MomCo.” — Jim  Warren,  DDJ,  August  1976. 


;md  never  need  debug- 
' 'Sbl-  ging  of  any  sort.  Yet  1 
r  '--Mi  (sin  walk  into  almost 

“  djk  -  any  programming 
shop  and  find  coders 
who  won't  write  a 
/  i  wH  bug-free  20-line  func- 

1  thS  tion  'n  Pascal  on  the 

I  i  TB  f'rsl  try.  These  are  peo- 
I  Jm  pie  who  know  how  to 
B  m  program — they  just 
m  »  don’t  bother  to  do  it 
right  the  first  time. 

I  invite  you  to  respond.  This  is  a  dif¬ 
ficult  and  emotional  issue.  Let’s  get  it 
out  in  the  open  where  it  can  he  solved. 


A  last-minute  addi-  BBBafc'  r/Ax 

month's  C  compiler  re-  EpgT 
view:  Mark  Williams 
Company  tells  ns  that  Slfcrv  aH 

it  has  released  Version  nH 

4.0  of  its  compiler.  The  Wi.  f\ 

new  version  has  been  \  \ 

substantially  im-  ■IL  \ \ 
proved  over  Version  H  \  \\ 
3.0.12,  which  is  includ-  K  \ 
ed  in  our  review,  im-  wt 
provements  include  the  ability  to 
generate  BOMable  code,  larger  mem¬ 
ory  models,  80286  support,  and  the 
ability  to  link  with  the  Microsoft  and 
Lattice  libraries. 


This  month's  hint  for  writers  has  to 
do  with  "puff  pieces” — articles  that 
are  little  more  than  (usually  glow'ing) 
descriptions  of  products  available 
from  the  company  for  which  the  au¬ 
thor  works.  Editorial  ethics  (and  the 
focus  of  the  magazine)  require  that 
we  restrict  articles  to  programming 
techniques,  rather  than  glorifying 
specific  products.  Here's  how  to  turn 
a  puff  piece  into  a  useful  article:  First, 
don’t  even  mention  the  product  until 
the  end,  where  you  can  safely  sav 
that  the  techniques  demonstrated  in 
the  article  are  used  in  your  product. 
Spend  most  of  the  article  explaining 
techniques  lhat  will  be  useful  to  the 
reader  whether  or  not  he  or  she 
owns  your  product.  Most  important, 
include  a  self-contained  sample  pro¬ 
gram,  (which  does  not  use  or  require 
your  product)  that  demonstrates 
clearly  how  the  reader  can  profit 
from  your  advice.  Be  sure  to  explain 
in  the  article  w'hat  the  demonstration 
program  does  and  how  it  does  it.  Re¬ 
member  that  DDJ  is  not  a  textbook. 
Our  readers  are  often  bored  by  reit¬ 
erations  of  well-known  techniques. 
Your  material  should  be  new,  techni¬ 
cally  sound,  and  interesting  to  ad¬ 
vanced  programmers. 


I've  been  hearing  about  a  "soft¬ 
ware  gap"  that  allegedly  threatens  to 
become  a  major  barrier  to  continued 
progress  in  computer  programming. 
An  article  by  John  Paul  Newport  Jr. 
in  the  April  28  issue  of  Fortune  maga¬ 
zine  revealed  some  interesting  infor¬ 
mation.  In  1984,  for  example,  data 
processing  departments  at  125  sur¬ 
veyed  companies  took  an  average  of 
27  months  to  deliver  programs  re¬ 
quested  by  other  departments.  The 
article  mentions  a  study  that  found 
that  75  percent  of  the  programs  re¬ 
quested  within  companies  are  never 
used  either  because  they  are  never 
completed  or  because  they  are  out¬ 
dated  when  they're  delivered. 
What's  going  on? 

Some  people  think  that  the  prob¬ 
lem  is  related  to  the  size  and  com¬ 
plexity  of  the  programs  we  re  build¬ 
ing  these  days.  I  disagree— it’s 
simpler  than  that. 

The  problem  is  the  simple  sloppi¬ 
ness  of  many  of  today's  "profession¬ 
al"  programmers.  It's  not  that  most 
programmers  don’t  know'  about 
structured  design  or  self-document¬ 
ing  code.  Rather,  they  just  don't  seem 
to  care.  1  have  known  programmers 
who  could  write  entire  operating 
system  kernels  (hundreds  of  lines  of 
source  code)  in  one  pass,  in  assembly 
code,  that  run  perfectly  the  first  time 
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Lost  at  C 

Dear  DDJ, 

I  have  been  an  avid  sup¬ 
porter  of  DDJ  for  years.  It 
has  always  been  a  good 
source  of  programming 
ideas  but  I  find  it  less  and 
less  useful  because  of  the 
increasing  emphasis  and 
use  of  C. 

I  have  no  inherent  objec¬ 
tion  to  C — its  only  problem 
is  that  it  is  essentially  un¬ 
readable  to  users  of  other 
languages.  By  printing  list¬ 
ings  in  C,  you  limit  their 
utility — for  example,  I 
would  dearly  have  liked  to 
be  able  to  use  some  of  the 
algorithms  given  in  the  ar¬ 
ticle  by  Joe  Marasco  in  the 
March  1986  issue.  It  is  a  top¬ 
ic  of  great  importance  to 
me,  but  they  were 
unintelligible. 

Several  years  ago,  I  be¬ 
came  convinced  that  I 
ought  to  move  from  FOR¬ 
TRAN  into  the  world  of 
structured  languages.  The 
two  obvious  candidates 
were  C  and  Pascal.  I  spent  a 
few  months  reading  about 
both  of  them  and  using 
them.  My  conclusion  was 
that  there  were  no  intrin¬ 
sic  advantages  of  one  over 
the  other,  but  even  for  a 
neophyte  such  as  myself, 
Pascal  was  so  much  easier 
to  read.  To  me,  the  com¬ 
mon  criticism  that  it  is 
wordy  is  a  validation  of  its 
readability.  I  decided  to  use 
it  from  then  on — a  decision 
I’ve  never  regretted. 

I’m  a  scientist  first  and  a 
programmer  last,  however. 
Over  the  years,  my  recol¬ 


lection  of  C  has  dimmed, 
and  I  can  no  longer  recall 
the  meaning  of  those  funny 
+  +  and  other  symbols. 
Hence,  my  complaint  to 
you. 

I  don't  suggest  that  pro¬ 
grammers  constrain  them¬ 
selves  to  Pascal.  I  do  suggest 
that  C  is  particularly  un¬ 
readable,  however,  and  I 
would  like  to  ask  you  to 
urge  authors  to  describe  al¬ 
gorithms  in  a  way  that 
would  allow  non-C  users  to 
make  use  of  them.  Of 
course,  I  have  no  objection 
to  listings  in  C  (as  well,  but 
not  alone)  because  I'm  sure 
that  many  find  them 
useful. 

J.  A.  Koehler 
Institute  of  Space  and 
Atmospheric  Studies 
Univ.  of  Saskatchewan 
Saskatchewan,  Canada 


C  Chest 

Dear  DDJ, 

I  have  some  comments 
about  some  of  the  things 
Allen  Holub  has  said  about 
his  MS-DOS  shell  and  about 
Microsoft  C.  In  addition, 
I'm  in  the  process  of  hack¬ 
ing  at  this  shell,  and  I’d  like 
to  explain  some  of  the  en¬ 
hancements  I've  added 
and  intend  to  add. 

First  of  all,  I've  been  using 
Microsoft  C,  Version  3.0,  for 
quite  a  while,  and  I  tend  to 
agree  with  most  of  Allen's 
comments  and  criticisms  of 
it.  I  especially  agree  with 
his  assessment  of  Micro¬ 
soft's  support  policy.  I,  too, 
have  found  that  they  are 
generally  uncooperative 
about  giving  support  to  peo¬ 
ple  who  ask  questions  that 
go  deeper  than  those  that  a 
relatively  high-level  user 


would  ask.  The  firm  seems 
to  not  care  about  giving  this 
support  to  anyone  who 
buys  less  than  a  hundred  or 
so  copies  of  its  software. 
This  infuriates  me. 

With  regard  to  their  Ver¬ 
sion  3.0  C  compiler,  Allen 
seemed  to  overlook  a  use¬ 
ful  feature  (that's  not  hard 
to  do  given  the  organiza¬ 
tion  of  the  manual).  There 
is  a  function  called  _se- 
targv (  ),  which  every  pro¬ 
gram  calls  to  parse  its  com¬ 
mand-line  arguments.  By 
putting  Allen's  reargvf  ) 
function  inside  a  routine 
with  this  name  and  then 
replacing  the  setargvf  ) 
function  with  this  newly 
created  one  in  the  standard 
library  the  user  can  take 
advantage  of  the  com¬ 
mand-line  argument  ex¬ 
pansion  scheme  without 
explicitly  calling  reargvf ). 
This  is  almost  as  good  as 
putting  the  call  to  reargvf ) 
into  the  root  module. 

Previous  to  getting  Al¬ 
len's  shell,  I  had  already 
written  my  own  _se- 
targvf )  routine,  which  ex¬ 
panded  my  command-line 
arguments  in  a  similar  way 
as  reargvf )  does.  So  all  I 
have  to  do  is  insert  a  call  to 
reargvf  )  at  the  top  of  my 
existing  routine  and  exit  if  it 
works.  If  it  doesn't,  that 
means  that  the  CMDLINE  en¬ 
vironment  variable  wasn't 
found.  I  can  then  fairly 
safely  assume  that  the  shell 
isn't  running  and  go  ahead 
and  do  my  own  expansion. 

Lloyd  Zusman 

Master  Byte  Software 

127  Wilder  Ave. 

Los  Gatos,  CA  95030 

Allen  Holub  replies: 

The  setargvf  )  function  is 
mentioned  (once)  in  the 
manual,  but  no  details  are 
given  about  how  it  works. 
The  routine  is  called  from 
the  start-up  (or  root)  mod- 
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ule  to  initialize  argv  and 
argc.  I  called  Microsoft  and 
was  told  that  it  takes  no  ar¬ 
guments  but  must  set  the 

global  variables _ argv 

and  _ argc  to  the  values 

that  will  be  passed  to 
main(  ).  This  is  all  fine  and 
dandy,  but  when  1  tried  to 
access  the  environment 
[with  getenv(  )]  I  received 
an  error  message.  As  it  ap¬ 
pears  that  Mr.  Zusman  has 
gotten  it  working,  I  seem  to 
have  given  up  too  easily. 

Let  Your  Fingers  Do 
the  Talking 

Dear  DDJ, 

I  read  the  May  1986  inter¬ 
view  with  Jef  Raskin  with 
interest — also,  the  Edlin  ar¬ 
ticle — but  the  tops  this 
month  was  your  Viewpoint 
on  voice  input  and  output. 

You  missed  one  thing, 
however.  The  big  short¬ 
coming  of  voice  out  is 
speed.  A  man  just  cannot 
listen  as  fast  as  he  can  read. 
And  if  a  person  did  not 
need  speed  he  would  not 
use  a  computer.  I  once  got 
the  idea  that  I  would  devel¬ 
op  a  system  to  get  informa¬ 
tion  out  of  a  digital  system 
via  audio,  which  would  be 
as  fast  as  by  visual  means. 
The  project  failed  miser¬ 
ably.  I  learned  a  lot  about 
the  shortcomings  of  the  au¬ 
ditory  system.  That  was  all. 
My  conclusion  was  that  the 
ear-voice  system  was  de¬ 
veloped  in  unison  and  that 
when  you  tried  to  work  ei¬ 
ther  with  a  computer 
you’re  headed  for  trouble. 
Voice  systems  can  be  used 
in  applications  in  which 
the  eye  must  be  otherwise 
engaged.  That’s  on  the  out¬ 
put  side.  I  never  worked  on 
the  input  side. 

My  company  does  a  cou¬ 
ple  of  things  on  the  input 
side  that  might  interest 
you.  First,  we  enter  code 
on  a  code  sheet  using  hex 


characters.  We  then  read 
that  code  column  with  a 
photoreader,  which  can  be 
built  for  about  $40.  Then 
we  also  use  a  Combo  Key¬ 
board,  which  is  ten  keys 
placed  so  they  fall  natural¬ 
ly  under  the  fingertips. 
The  ASCII  code  can  be  gen¬ 
erated  directly  by  pressing 
the  keys  in  combinations, 
much  as  a  piano  is  played. 
Ten  keys  permit  the  gener¬ 
ation  of  1,023  characters. 
We  use  only  eight  of  the 
keys  to  input  code,  which 
cuts  us  to  256  characters. 
We  also  use  a  one-hander 
with  six  keys,  which  in¬ 
puts  63  characters  in  basic 
mode.  We  pull  a  trick  or 
two  to  input  191.  The  chief 
advantage  of  the  key¬ 
boards  is  that  you  never 
need  to  move  your  eyes  to 
the  board. 

R.  O.  Whitaker 

Computer  Compatible 
Inst.  Co. 

4719  Squire  Dr. 

Indianapolis,  IN  46241 

The  Right  to 
Optimize 

Dear  DDJ, 

I've  been  intrigued  with 
DDJ' s  continuing  saga  of  in¬ 
teger  square  roots.  Because 
most  of  the  recent  debate 
(The  Right  to  Assemble  by 
Richard  Campbell,  March 
1986)  has  centered  on 
whether  the  68000  or  32032 
is  best  suited  for  this  task,  I 
thought  you  might  appreci¬ 
ate  seeing  how  we  poor 
slobs  shackled  to  8086s  han¬ 
dle  the  problem.  Actually, 
integer  square  roots  are 
fairly  important  to  me  be¬ 
cause  I  work  with  digitized 
gamma-ray  spectra  where 
estimates  of  error  are  inti¬ 
mately  tied  to  counting  sta¬ 
tistics.  The  8087  will  blaze 
through  square  roots,  but  I 
can’t  assume  my  programs 
will  be  run  on  machines 
with  8087s,  so  I’ve  been  on 
the  lookout  for  fast  8086 
routines. 

Listing  One,  page  81,  is 


written  as  a  function  for 
DeSmet  C  and  uses  De- 
Smet’s  asm88  mnemonics; 
code  for  Intel  and  Micro¬ 
soft  assemblers  should  be 
very  similar.  As  with 
Campbell’s  320XX  code,  the 
underlying  principle  is 
Newton's  method,  and  half 
the  game  is  picking  an  ap¬ 
propriate  initial  estimate. 
Like  the  68000,  the  8086  is 
sluggish  on  divides  (ap¬ 
proximately  150-160  clocks 
each),  so  you  might  expect 
Campbell’s  320XX  code  to 
vastly  outperform  the 
8086.  An  8-MHz  8086,  how¬ 
ever,  averages  only  172 
milliseconds  per  32-bit 
square  root  (based  on  "in 
vivo"  timings,  to  use  Camp¬ 
bell’s  phrase),  which  seems 
reasonably  competitive 
with  Campbell’s  result  of 
183  microseconds  for  a  6- 
MHz  16032.  Note,  Campbell 
states  that  his  320XX  func¬ 
tion  took  an  average  of 
only  7  shifts,  but  that's  be¬ 
cause  he  restricted  his  test 
program  to  integers  be¬ 
tween  0  and  60,000;  for  the 
full  range  of  32-bit  num¬ 
bers,  the  average  would  be 
15  shifts,  and  the  16032 
would  be  substantially 
slower.  The  80286  does  di¬ 
vides  using  temporary  reg¬ 
isters  (22  clocks)  and  should 
be  much  faster  than  the 
8086,  taking  less  than  100 
microseconds.  I’ve  tried 
other  methods  to  get  a  bet¬ 
ter  estimate  before  enter¬ 
ing  the  refine  loop,  includ¬ 
ing  faster  versions  of  the 
guessl,  guess2  conver¬ 
gence  method  used  by 
Campbell;  oddly,  these  bet¬ 
ter  initial  estimates  only 
speed  up  the  8086  by  about 
10  percent  and  can  actually 
slow  down  the  80286.  On 
the  80286,  the  extra  logic  is 
slower  than  extra  divides. 

I  initially  wrote  an  8086 
version  of  Jim  Cathey's 
68000  code  (May  1985,  DDJ), 
but  it  was  comparatively 
slow,  averaging  about  250 
microseconds;  I've  en¬ 


closed  the  8086  version  of 
this  bit-shifting  method 
[Listing  Two,  page  81],  and 
to  say  the  least,  it  is  opaque 
compared  to  the  68000 
code.  Adding  up  the  execu¬ 
tion  clocks  for  the  8086  sug¬ 
gests  that  the  routine 
should  average  only  150 
microseconds  at  8  MHz; 
however,  short  8086  in¬ 
structions  such  as  shl  a?c,  1 
(2  clocks)  execute  faster 
than  they  can  be  fetched, 
and  the  processor  is  con¬ 
stantly  stopping  to  refill 
the  prefetch  queue.  Hence, 
Campbell’s  advice  about 
using  "in  vivo”  timings 
proves  very  appropriate. 
In  addition,  the  paucity  of 
registers  in  the  8086  means 
that  even  sp  has  to  be  used 
to  avoid  storing  intermedi¬ 
ate  results  in  memory.  The 
80286  has  a  much  faster 
fetch  rate  and  would  tend 
to  keep  the  queue  filled,  ex¬ 
cept  after  branching.  The 
need  to  use  all  the  registers 
would  be  relaxed  in  the 
80286  because  memory  ref¬ 
erences  can  be  almost  as 
fast  as  register-register  op¬ 
erations.  For  statistical  de¬ 
cision  making,  I  rarely 
need  to  calculate  accurate 
square  roots,  and  I  use  a 
function  that  returns  an 
approximation  (correct  to 
within  10  percent)  in  30  mi¬ 
croseconds.  Still,  I'd  appre¬ 
ciate  hearing  about  faster 
8086  routines. 

Without  doubt,  the 
320XX  and  68000  are  much 
easier  to  program  than  are 
the  8086  and  80286,  but  it  is 
often  surprising  how  well 
the  Intel  chips  do  when  a 
modest  amount  of  thought 
goes  into  the  code.  I  dis¬ 
agree  with  Campbell’s  bias 
against  using  low-level,  bit- 
and  byte-oriented  tricks; 
sometimes  these  methods 
are  the  fastest  and  cleanest, 
and  who  is  to  say  which 
approach  is  more  "ratio¬ 
nal"?  Cathey’s  bit-shifting 
68000  code  reflects  the 
square  root  method  most 
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people  learn  in  seventh- 
grade  algebra  and  proba¬ 
bly  seems  much  more  intu¬ 
itive  to  those  who  stayed 
awake  in  class. 

H.  W.  Stockman 

6807  Prairie  Rd.  NE,  #405 

Albuquerque,  NM  87109 

Dear  DDJ, 

Will  we  ever  see  the  last 
word  on  square  roots?  Al¬ 
though  I  do  agree  with  Mr. 
Campbell  [The  Right  to  As¬ 
semble,  March  1986]  that 
the  bit-level  mashing  that  is 
necessary  for  8-bit  proces¬ 
sors  is  undesirable,  it  is  not 
lightly  dispensed  with  as  I 
have  found  (not  to  mention 
how  interesting  it  is  to  see 
how  much  better  it  comes 
out  on  the  better  processor). 
The  square  root  routine 
that  I  actually  use  is  much 
better,  although  quite  a  bit 
larger  [Listing  Three,  page 
82].  My  real  routine  is  bro¬ 
ken  into  three  parts — a  part 
for  arguments  no  larger 
than  a  single  word,  a  part 
for  arguments  larger  than  a 
single  word  (with  two  of 
the  loops  unrolled  so  that  a 
quick  word-oriented  loop 
can  be  used  when  there  is 
no  danger  of  overflow),  and 
a  special  routine  that  han¬ 
dles  particularly  small  ar¬ 
guments  that  is  used  when 
it  would  be  quicker  than 
the  normal  word  routine.  It 
should  be  noted  that  this 
program  yields  correct  re¬ 
sults  over  the  entire  range 
of  arguments  from  0  to 
SFFFFFFFF,  which  I  believe 
cannot  be  said  for  Mr. 
Campbell’s  routine  if  the 
:  NS32000  processor  handles 
|  „;FFFFFFFF^$FFFF  like  the 
68000  does  (overflow,  with 
no  result).  This  may  be  of  no 
significance  to  most  users, 
but  it  was  of  importance  to 
me  because  of  the  way  I 
originally  used  the  routine. 

What  I  find  interesting 
about  the  shift-based  rou¬ 


tine  is  that  it  is  of  no  more 
complexity  than  a  divide 
routine,  and  it  does  not  de¬ 
pend  upon  converging  to  a 
solution.  As  a  hardware- 
oriented  kind  of  guy,  I  can 
see  how  when  microcoded 
it  could  calculate  a  square 
root  in  about  the  same  time 
as  a  divide.  This  simplicity 
is  what  attracted  me  to  the 
algorithm  in  the  first  place. 
To  me,  this  algorithm  has 
the  same  sort  of  elegance  as 
Bresenham's  algorithm  for 
line  drawing  and  CORDIC 
for  coordinate  rotation. 

As  my  C  compiler  spits 
out  a  subroutine  call  for 
the  division  rather  than  us¬ 
ing  the  DIVU  instruction,  I 
hand-coded  a  version  of 
Mr.  Campbell’s  routine  for 
the  68000  [Listing  Four, 
page  85].  For  cycle-shavers 
even  more  diligent  than 
myself,  I  think  there  is  still 
some  room  for  trimming, 
but  I  lost  interest  in  trying 
further.  This  version  also 
attempts  to  cover  the  full 
range  of  arguments,  al¬ 
though  I  cannot  vouch  that 
it  does  it  successfully.  I 
spot-checked  a  few  of  the 
large  troublemakers,  and  it 
did  those  correctly. 

The  results  of  comparing 
these  two  routines  were 
most  instructive.  Mr.  Camp¬ 
bell  is  correct  in  his  feeling 
that  the  shift-based  routine 
is  slower  than  Newton’s 
method  if  there  is  a  hard¬ 
ware  divide  of  the  requisite 
size  available.  I  have  found, 
however,  (on  the  68000  at 
least)  that  if  you  only  need 
the  square  root  of  a  word¬ 
sized  number,  the  shift- 
based  routine  runs  faster 
than  Newton’s  method!  My 
version  of  Mr.  Campbell's 
routine  takes  an  average  of 
854  cycles  to  calculate  each 
of  the  first  65,535  square 
roots  (that’s  seven  seconds 
total  to  you  and  me).  My 
shift-based  routine  takes  an 
average  of  610  cycles  to  do 
the  same  thing  (5  seconds). 
For  the  first  500,000  roots, 


the  Newton's  method  rou¬ 
tine  averages  992  cycles  (62 
seconds)  vs.  1,104  cycles  (69 
seconds)  for  my  routine. 
This  is  not  too  much  worse 
than  Newton’s  method. 
What  is  interesting  to  note 
is  that  both  the  best-  and 
worst-case  timings  for  the 
shift-based  routine  are  bet¬ 
ter  than  Newton's  method, 
but  the  average  favors 
Newton’s  method.  This  is 
almost  entirely  because  of 
the  quality  of  the  initial 
guess  calculated  by  Mr. 
Campbell's  routine.  New¬ 
ton’s  method  is  lousy  as  a 
root-guesser  unless  the  ini¬ 
tial  guess  is  close — then  it  is 
excellent. 

As  far  as  instruction 
pipelines  and  their  effect 
on  cycle  counting  goes,  the 
68000  also  has  a  one-word 
look  ahead,  but  the  cycle 
counts  listed  by  Motorola 
supposedly  include  this 
time,  so  accurate  counts 
are  possible.  This  is  not  pos¬ 
sible  on  the  68020,  though. 
Because  Motorola  hedges  a 
little  when  listing  divide 
clock  times,  the  counts  list¬ 
ed  for  Newton’s  method 
may  be  off  a  little.  I  think  a 
version  of  the  shifting  rou¬ 
tine  for  the  NS32000  may 
be  more  efficiently  coded 
using  the  add/addc  style  of 
rotating  two  bits  out  of  the 
argument  into  the  trial  reg¬ 
ister.  This  might  reduce  the 
discrepancy  between  Mr. 
Campbell's  two  versions 
and  my  two  versions.  I  can¬ 
not  say,  though,  as  I  am  un¬ 
familiar  with  the  NS32000 
at  that  level  of  detail. 

I  must  say  that  I  am 
pleased  with  the  amount 
of  thought  that  my  submis¬ 
sion  has  spawned.  Perhaps 
one  of  the  poor  souls  af¬ 
flicted  with  the  8086  could 
whomp  up  the  two  rou¬ 
tines  and  see  how  they 
compare. 

Jim  Cathey 

ISC  Systems  Corp. 

TAF-C8 

Spokane,  WA  99220 


Faster  Random 
Numbers 

Dear  DDJ, 

The  pseudorandom  num¬ 
ber  generator  given  in  the 
November  1985  16-Bit  Soft¬ 
ware  Toolbox  may  be  too 
slow  for  some  applications. 
The  enclosed  routine  was 
inspired  by  the  article  "A 
Fast  Method  of  Generating 
Digital  Random  Numbers” 
by  Rader,  Rabiner,  and 
Schafer  in  the  November 
1970,  Bell  System  Technical 
Journal  and  is  essentially 
shift  register  feedback. 

Two  data  registers  of  the 
68000  should  be  dedicated 
to  the  routine  because  the 
overhead  of  subroutine 
calling  is  too  slow.  These 
two  registers  contain  the 
seed  numbers,  and  their 
concatenation  constitutes  a 
64-bit  shift  register.  The  fol¬ 
lowing  four  instructions 
constitute  the  generator: 

EXG  D6,D7 

ROLL  #3,D7 

SUBQ.W  #7,D7 

EOR.W  D6,D7 

The  EXG  instruction  acts  as 
a  32-bit  rotate;  the  BOL  in¬ 
struction  acts  as  a  partial 
rotate;  the  SUBCJ  instruction 
avoids  the  pitfall  of  all  ze¬ 
ros;  the  EOft  instruction 
mixes  the  bits.  Each  time 
the  sequence  is  performed, 
a  new  seed  is  generated 
and  the  low  byte  or  low 
word  of  D7  is  available  as  a 
random  number.  At  8 
megahertz,  the  time  re¬ 
quired  is  3.5  microseconds, 
so  it  is  almost  a  hundred 
times  faster  than  the  earli¬ 
er  routine. 

Lawrence  Mertz 

287  Fairfield  Ct. 

Palo  Alto,  CA  94306 

DDJ 

(Listings  begin  on  page  81.) 
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Not  too  long  ago  Byte  ran 
an  article  entitled  “Easy  C" 
by  Pete  Orlin  and  John 
Heath  (vol.  11,  no.  5,  May 
1985).  Because  the  miscon¬ 
ceptions  in  the  article  are 
representative  of  a  class  of 
mistakes  often  made  by 
people  who  discuss  the 
language,  I  feel  obliged  to 
comment. 

The  article  opined  that 
the  “confusing  notation 
and  the  unfriendly  look” 
of  C  made  it  difficult  to 
learn  and  difficult  to  pro¬ 
gram.  The  authors'  solu¬ 
tion  was  to  use  the  macro 
preprocessor  to  change  the 
look  of  the  language,  to 
make  a  program  "more  un¬ 
derstandable."  For  exam¬ 
ple,  they  suggested 
changing: 

switch!  *s ) 

{ 

case  ’x’: 

except  =  1; 
break; 
case  'n': 

number  =  1; 
break; 
default: 

printfC.  .  .”); 
argc  =  0; 
break 


into: 

CASE!  *s  ) 

CASEOF('x') 
except  =  1; 
ENDCOF 
CASEOF('n') 
number  =  1; 
ENDCOF 


by  Allen  Holub 


DEFCASE 
printfC.  . 
argc  =  0 
ENDCOF 
ENDCASE 

or  changing: 


(c  >=  ’a’  &&  c  <=  'z’l 

into: 

(c  GE  'a'  AND  c  LE  ’x’) 

by  using  macros  such  as: 

^define  GE  >  = 

^define  LE  <  = 

'('define  AND  &,&, 

^define  INC  +  + 

^define  FOR(e)  {  for  (e) 

{  ^define  ENDFOR  ; } } 
^define  CASE(e)  { switch  (e)  { 
^define  ENDCASE } } 


You  get  the  idea. 

I'm  reminded  of  COBOL.  I 
don’t  know  any  program¬ 
mers  who  actually  like  the 
COBOL  language  (though 
several  of  them  are  used  to 
it  at  this  point  and  so 
wouldn’t  change  without 
an  argument).  The  main 
objection  is  that  everything 
is  done  with  words,  so  you 
can’t  skim  through  a  pro¬ 
gram.  It’s  difficult  to  see  a 
program's  structure  at  a 
glance,  and  you  actually 
have  to  read  every  word 
for  the  program  to  make 
sense.  As  a  consequence, 
COBOL  programs  are  diffi¬ 
cult  to  write,  they  take  a 
long  time  to  debug,  and 
they  are  hard  to  maintain. 

COBOL  was  originally 
sold  to  managers  because, 
in  theory,  it  would  give 
them  control  over  their 
programmers.  Control  is 
the  operative  word  here. 
Because  the  language  uses 
an  English-like  syntax,  the 
theory  was  that  managers 
would  be  able  to  read  the 
programs  and  thus  keep 
tabs  on  what  the  program¬ 
mers  were  doing.  There’d 
be  no  "confusing”  symbols 
such  as  the  .NE.  or  .GT. 
used  in  FORTRAN.  There'd 
be  no  terse  constructs  (such 


as  the  DO  loop)  that  the 
manager  couldn't  under¬ 
stand.  Because  the  manag¬ 
er  could  read  the  code,  he 
or  she  could  tell  when  a 
programmer  was  goofing 
off.  How  could  it  possibly 
take  that  long  to  write  a 
simple  computer  program 
anyway?  Somebody  must 
be  cheating. 

Unfortunately,  comput¬ 
er  programs  just  do  take  a 
long  time  to  write,  and  CO¬ 
BOL  programs  are  no  more 
readable  than  any  other 
kind  of  program.  Using  En¬ 
glish  words  instead  of 
other  symbols  (words  are 
after  all  just  symbols) 
makes  a  program  no  more 
comprehensible  to  non- 
programmers.  By  the  time 
these  managers  found  out 
that  a  computer  program  is 
not  a  business  plan,  it  was 
too  late.  Enough  code  had 
been  written  in  COBOL  that 
moving  to  another  lan¬ 
guage  wasn't  financially 
feasible.  As  a  consequence 
a  large  body  of  hard-to- 
maintain  COBOL  pro¬ 
grams  are  in  use  today.  No¬ 
body  wins.  The  managers 
still  can’t  read  the  code, 
and  the  programmers 
have  a  harder  time  writing 
it. 

It  bothers  me  to  see  es¬ 
sentially  this  same  argu¬ 
ment  applied  to  C.  I  agree 
that  C  code  can  be  terse  at 
times.  Nonetheless,  Mr.  Or¬ 
lin  and  Mr.  Heath  are  con¬ 
fusing  familiarity  with 
readability.  Just  because 
you  know  another  pro¬ 
gramming  language 
doesn’t  mean  that  every¬ 
one  who  programs  in  C  is 
also  going  to  know  the 
same  language.  Because  I 
don’t  know  the  language 
into  which  the  authors  are 
trying  to  transform  C,  I 
find  their  transformed 
programs  incomprehensi¬ 
ble.  Is  <T=  really  less  un¬ 


derstandable  than  LE?  Is 
switch  less  understandable 
than  CASE? 

To  carry  the  argument  to 
the  logical  extreme,  what  if 
everyone  did  what  the  au¬ 
thors  suggest?  Because  ev¬ 
eryone  is  familiar  with  a 
different  set  of  languages, 
everyone  would  make  up  a 
different  set  of  macros  to 
make  their  code  “more  un¬ 
derstandable.’’  All  pro¬ 
grammers  would  then 
have  their  own  personal 
programming  language. 
You  wouldn’t  be  able  to 
read  anyone's  code  but 
your  own  without  having 
to  learn  a  new  program¬ 
ming  language  first.  By  the 
same  token,  if  you  never 
bothered  to  learn  the  cor¬ 
rect  C  syntax,  you 
wouldn’t  be  able  to  read  a 
program  that  was  written 
in  standard  C.  A  sorry  state 
of  affairs  indeed. 

There  are  other  prob¬ 
lems  here,  too.  For  exam¬ 
ple,  a  lot  of  books  tell  you 
to: 

^define  FALSE  0 
^define  TRUE  1 

so  that  you  can  say: 

if!  subr! )  =  =  TRUE  ) 

Because  any  nonzero  value 
is  true  in  C,  the  if  statement 
can  evaluate  incorrectly 
when  subri )  returns  a  per¬ 
fectly  reasonable  true  val¬ 
ue  that  doesn’t  happen  to 
be  1.  So,  potential  errors 
have  been  introduced. 

The  real  difficulty  here 
stems  from  a  misunder¬ 
standing  of  the  actual  prob¬ 
lem,  and  it’s  a  misunder¬ 
standing  that  extends  to 
topics  other  than  C.  C  is  a 
difficult  language  to  learn, 
as  are  many  branches  of 
computer  science.  The  dif¬ 
ficulty  is  not  caused  by  the 
symbols  that  the  language 
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uses,  however,  but  rather 
by  the  fundamental  struc¬ 
ture  of  the  language  itself: 
the  ways  that  pointers  are 
used  and  so  forth.  Going 
further,  the  structure  of 
the  language  is  in  large 
part  determined  by  the 
structure  of  a  computer.  So 
the  problem  isn't  really  the 
language  but  rather  the 
amount  of  general  knowl¬ 
edge  of  computers  that  you 
must  acquire  before  C  be¬ 
gins  to  make  sense.  You 
have  to  understand  a  lot 
about  how  computers 
work  before  you  can  even 
understand  what  the  C  op¬ 
erators  do,  much  less  how 
to  use  them.  It's  not  that  the 
>  and  >>  operators  look 
alike,  but  that  many  novice 
programmers  don’t  know 
what  an  arithmetic  right 
shift  is.  In  the  C  classes  that 
I  teach  at  U.C.  Berkeley, 


I’ve  noticed  that  assembly- 
language  programmers 
usually  have  little  difficul¬ 
ty  learning  about  pointers 
because  they  understand 
indirect  addressing. 

C  was  developed  in  or¬ 
der  to  write  operating  sys¬ 
tems,  a  task  not  attempted 
by  most  novice  program¬ 
mers.  It  was  never  intend¬ 
ed  to  be  anyone’s  first  lan¬ 
guage,  nor  was  it  intended 
to  be  intelligible  to  unso¬ 
phisticated  programmers. 
In  fact,  the  very  things  that 
would  make  C  intelligible 
to  beginners  would  also 
make  the  language  useless 
for  its  intended  purpose: 
systems  programming.  Try 
to  write  an  operating  sys¬ 
tem  in  BASIC  sometime.  On 
the  other  hand,  languages 
such  as  Pascal  and  its  cous¬ 
ins  were  designed  to  teach 
you  how  to  program  and 


are  excellent  for  this  pur¬ 
pose.  If  you're  new  to  the 
programming  business, 
you  should  be  learning  Pas¬ 
cal  not  C. 

A  well-written  C  pro¬ 
gram  is  a  joy  to  read,  once 
the  syntax  is  familiar.  (How 
long  can  it  take  to  learn 
that  <=  means  less  than 
or  equal?)  The  best  way  to 
learn  C  is  to  learn  Pascal, 
assembly,  and  a  little  bit 
about  computer  architec¬ 
ture  and  hardware  design. 
No  amount  of  beating  your 
head  against  the  language 
will  help  you  if  you  don’t 
have  the  background.  No 
one  can  write  a  good  C  pro¬ 
gram  unless  they  have  the 
background.  If  you're  try¬ 
ing  to  learn  C,  you’re  wast¬ 
ing  your  time  changing  the 
way  the  language  looks.  C 
is  not  easy,  it's  not  for  be¬ 
ginners,  and  no  amount  of 


wishful  thinking  will 
make  it  so.  There  are  no 
shortcuts.  On  the  other 
hand,  the  effort  spent 
learning  the  language,  and 
learning  the  things  you 
need  to  learn  the  language, 
can’t  help  but  make  you  a 
better  programmer. 


DDJ 
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FORUM 


DDJ  ON  LINE 


We  are  now  having  weekly 
real-time  conferences  on 
the  DDJ  Forum.  The  confer¬ 
ences  will  take  place  on  the 
DDJ  Forum  Conference 
channel  30  and  give  readers 
a  chance  to  “chat’'  with  DDJ 
editors,  writers,  and  special 
guests.  To  participate, 
please  check  the  DDJ  Forum 
CO  bulletin  for  conference 
times  and  read  the  CO  help 
file  in  DLO. 

Bluesky 

1321  Sl/C  Chest 
Fm:  Darryl  75206,3074 
To:  Bob  76003,102 
Well ...  I  think  the  Mac  is 
basically  an  idea  before  its 
time.  Now  before  you  and 
every  other  Mac  fan 
scream  at  me  for  this,  let 
me  explain. 

As  I  stated  before,  I  like 
the  ideas  embodied  in  the 
Mac.  I  don't  like  the  Mac  as 
it  now  exists  (emphasis  on 
now).  It  really  needs  (at  the 
very  least)  a  dedicated 
graphics  chip  to  do  hard¬ 
ware  line  drawing,  area 
fills,  and  so  on  and  some 
slots.  Having  much  of  the 
graphics  done  in  hardware 
would  do  wonders  to  speed 
things  up.  It  needs  slots  be¬ 
cause,  in  my  opinion,  slots 
are  used  to  fix  problems 
that  the  manufacturer  (Ap¬ 
ple,  in  this  case)  did  not  an¬ 
ticipate.  If  the  Mac  had 
slots,  adding  to  it  new  and 
useful  capabilities  would  be 
much  cheaper  than  it  is 
now.  Adding  4  megabytes 
RAM  could  cost  only  $150  + 
cost  of  RAM.  Adding  more 
serial  and  parallel  ports 
would  be  much  cheaper. 
(Using  the  SCSI  requires  the 
use  of  more  logic  and,  natu¬ 
rally,  adds  more  to  the 
price  of  the  final  product.) 
The  Mac  could  be  used  for 
cheap  data  acquisition  if  it 
had  slots.  Data  acquisition? 
If  the  Mac  had  slots,  people 
would  be  using  it  for  many 


purposes  for  which  it  is  not 
designed  (I've  heard  the  Ap¬ 
ple  II  is  used  for  videotape 
editing),  and  the  Mac  would 
be  bought  by  many  more 
people. 

However,  such  a  ma¬ 
chine  as  I’ve  just  described 
would  probably  cost  $3,000- 
$4,000,  placing  it  out  of  the 
price  range  of  many  poten¬ 
tial  buyers.  This  is  why  I 
said  it’s  before  its  time. 

Fm:  Bob 
To:  Darryl 

A  slotted  Mac  is  in  develop¬ 
ment,  it  was  held  up  by  the 
original  design  philosophy 
espoused  by  Steve  Jobs  and 
others,  but  it  has  no  such  re¬ 
strictions  on  its  appearance 
now  and  merely  awaits  de¬ 
velopment. 

Fm:  Darryl 

But  is  it  supported  by  Ap¬ 
ple?  If  it's  not,  there  won't 
be  many  compilers  written 
to  take  advantage  of  it. 

The  Sieve  program  is 
really  a  poor  benchmark 
for  the  68881.  The  Sieve  is 
basically  an  integer-only 
program  that  doesn’t  exer¬ 
cise  the  capabilities  of  the 
68881. 

Fm:  Bob 

Yeah,  you're  right  about 
the  Sieve  as  a  test  of  the 
68881.  I  didn’t  have  any 
other  figures  at  my  finger¬ 
tips,  however.  Duane  Max¬ 
well  74075,1666  is  a  princi¬ 
pal  in  a  company  that 
provides  an  020/881  up¬ 
grade  and  can  provide  you 
with  more  details. 

Fm:  Mike  70010,147 
Hey,  the  full-blown  Macin¬ 
tosh  sounds  like  a  good 
time,  but  I’d  set  a  few  bucks 
aside  for  a  Fresnel  lens  to 
put  in  front  of  the  screen. 
1KX1K  on  such  a  small 
screen  could  get  tough. 
Why  not  beg  for  an  Amiga 


with  the  same  resolution 
and  some  Unix  .  .  .  wait  a 
minute,  the  Amiga  has  a 
68000  in  it  like  the  Inte¬ 
gral  ...  I  wonder  if  .  .  .  er, 
uh,  excuse  me,  I  gotta  run. 

Fm:  Darryl 

Oh,  of  course!  If  I  had  a 
screen  resolution  of 
IK  X  IK,  I'd  want  a  14-  to  19- 
inch  screen,  not  a  puny  9- 
incher.  Actually,  I  think 
one  of  the  Mac’s  problems 
is  that  the  68000  is  doing  too 
many  things.  Having  some 
dedicated  graphics  chips  to 
handle  the  graphics  would 
probably  go  a  long  way  to 
solving  some  of  the  speed 
problems.  Also,  does  the 
Mac  have  dedicated  disk- 
controller  chips?  If  it’s  any¬ 
thing  like  the  way  the  disk 
I/O  is  done  on  the  Apple  II, 
then  this  is  another  area 
that  could  be  improved. 

Actually,  if  HP  would 
transform  the  Integral 
from  a  portable  to  a  trans¬ 
portable  (say  Compaq  size) 
and  add  an  HD  and  some 
slots,  then  it  would  be  a 
very  nice  machine.  Of 
course  you're  right;  any 
machine  like  that  would 
cost  about  $10,000. 

Fm:  Mike 

Early  last  year  I  was  on  the 
road  all  the  time  training 
our  customers  how  to  use 
our  controller.  I  got  pretty 
tired  hanging  out  in  Holi¬ 
day  Inn  lounges  and 
thought  a  portable  would 
be  a  fun  thing.  OK,  so  I  drop 
the  bucks,  get  the  IPC,  and  I 
haven't  been  on  the  road 
since,  at  least  no  overnight- 
ers.  The  computer  just  sits 
on  the  desk  at  home  .  .  . 
skip  the  19-inch  monitor, 
maybe  I’ll  go  for  a  projec¬ 
tion  TV. 

Fm:  Darryl 

<grin>  Better  still  how 
about  getting  a  cellular 


phone  and  a  modem — that 
way  you  can  be  (almost) 
anywhere  (in  the  city)  and 
still  be  able  to  access  CIS  or 
whatever  <grin>. 

Fm:  Mike 

OK,  but  you  still  need  a 
screen  of  some  sort.  Most 
LCDs  would  be  miserable  in 
a  car  with  the  limited 
viewing  angle.  ELs 
wouldn’t  be  so  bad,  but 
they  get  dark  (not  sure 
why)  in  bright  sunlight. 
Plasma  displays  would  be 
dangerous  in  an  accident — 
going  though  a  windshield 
would  be  one  thing,  but  go¬ 
ing  through  a  high-voltage 
plasma  display  would  be 
something  else  entirely. 
Can  you  imagine  DDJ  Fo¬ 
rum  bounced  off  the  wind¬ 
shield  in  a  heads-up  cock¬ 
pit  display?  Neither  can  I. 

Fm:  Darryl 

Now  there’s  a  thought.  In¬ 
stall  a  heads-up  display;  a 
cellular  phone  connected 
to  a  modem  that  is  connect¬ 
ed  to  your  CMOS  MicroVAX; 
a  speech  synthesis/recogni¬ 
tion  board;  and  a  CD-ROM  to 
hold  maps  of  the  city,  state, 
and  U.S.  That  way  you  can 
talk  to  CIS  as  you  navigate 
(using  the  heads-up  dis¬ 
play).  Better  still,  add  a  few 
GaAs  Crays,  some  sensors 
(sonar,  radar  detector,  TV 
cameras),  and  a  few  me¬ 
chanical  linkages  here  and 
there  to  control  your  car. 
Now,  all  you'll  have  to  do  is 
get  in  the  car  and  tell  it 
where  to  go.  It  will  do  all 
the  rest — even  speed  when 
there  are  no  police  around. 
(That's  another  reason  why 
you  have  the  radar  detector 
and  vision  system.) 

Of  course,  I  won’t  be  re¬ 
sponsible  if  some  joker 
takes  a  D-Stat  gun  to  the  car. 

Fm:  Mike 

Of  course,  when  the  Cray 
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mobile  needed  a  fill-up, 
you'd  have  to  find  yourself 
a  GaAs  station.  (Sorry.) 

Fm:  Larry  75046,606 
Actually,  I  hear  the  Sun  2/ 
50,  a  diskless  Sun  that  can 
have  a  tape  unit  added  on 
later,  can  be  had  for  ap¬ 
proximately  $7,000 

now  .  .  .  almost  free 
<grin>.  [This  is  not  to  be 
confused  with]  a  $30,000 
Sun  workstation  (which  I 
use  at  work  each  day...). 

Fm:  Mike 

Hey  Darryl,  who  is  this 
guy!  Sitting  in  front  of  a 
Sun  workstation  every 
day  .  .  .  and  getting  paid  for 
it!  Some  guys  get  all  the 
luck!  Then  again,  maybe 
because  it  is  "work,”  it’s 
lost  some  of  its  glamour.  I 
remember,  when  I  was  a 
kid,  I  thought  it  would  be 
great  to  "work"  with  com¬ 
puters  when  I  grew  up. 


I  Now  I’m  (almost)  grown¬ 
up,  and  sometimes  I  just 
don't  feel  like  going  into 
the  office  for  another  day 
of  C.R.T.  (cathode-ray  tan). 
Whaddya  say  Larry,  has  it 
lost  its  glamour?  Is  it  just 
another  day  at  the  office? 
Tell  me  (please)  you  don’t 
enjoy  it! 

Fm:  Larry 

Well,  it  is  interesting.  We 
are  alpha-testing  (pre-al¬ 
pha?)  the  latest  Sun  work¬ 
station  enhancements;  so 
early  I  cannot  even  tell 
you.  Other  than  the  nor¬ 
mal  hassles  of  working  in 
that  early  of  an  environ¬ 
ment,  through  an  OEM,  and 
without  adequate  training, 
it  isn’t  so  bad. 

What  I  like  most  about 
the  whole  thing  is  the  key¬ 
board!  This  is  really 
strange.  The  machines  are 
OK,  but  we  have  been  us¬ 
ing  a  dumb,  vtlOO-emulat- 


ing,  terminal-mode  type 
setup  for  development, 
with  a  keyboard  that  is 
much  better  than  an  IBM 
mishmash  but  strange 
nonetheless.  Now  I  try  a 
Sun  keyboard,  and  it  is  a 
dream.  What  I  find  strange 
is  that,  with  a  setup  like 
this,  Sun  doesn't  have  a 
very  good  setup  with  func¬ 
tion  keys.  They  are  there 
(10  —  20,  I  really  don’t  re¬ 
member  right  now),  but  in 
the  SunTools  environ¬ 
ment — a  desktop  where 
each  window  is  a  pseudo- 
1TY  into  a  Unix  4.2BSD  pro¬ 
cess — I  can  find  no  doc  on 
how  to  take  advantage  of 
the  function  keys.  Rather 
strange  for  a  $50,000  unit! 

Fm:  Mike 

It  doesn't  sound  like  you 
hate  your  job  all  that 
much.  Ultra-new  equip¬ 
ment  is  a  gas  to  work  with, 
exploring  new  frontiers 


and  all  that.  Your  comment 
on  the  keyboard  hits  home. 
It’s  funny  how  one’s  ap¬ 
preciation  for  a  machine, 
be  it  a  $5,000  Integral  or 
$50,000  Sun  workstation,  is 
determined  by  the  friendli¬ 
ness  of  a  $100  keyboard. 
My  brother,  a  serious  pia¬ 
nist,  used  to  complain 
about  piano  keyboards  in 
the  same  way,  and  I  could 
never  quite  fully  under¬ 
stand.  Now  I  do,  the  IBM 
keyboard  may  be  bad,  but 
I’d  trade  the  PC/AT  key¬ 
board  in  the  office  for  this 
sticky,  rubber  HP  key¬ 
board  in  a  minute. 

DDJ 
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An  AVL  Tree  Database  Package 


AVL  Trees 

One  of  the  problems  with  binary 
trees  is  the  degraded  case. 
When  you  insert  a  sorted  list  of  keys 
into  a  binary  tree,  you  get  a  linear 
linked  list.  Not  only  does  it  take  an 
inordinate  amount  of  stack  to  tra¬ 
verse  this  list  but  also  the  search  time 
to  find  a  key  at  the  end  of  the  list  is 
pretty  awful  (statistically  you’d  be 
better  off  searching  a  randomly  or¬ 
dered  linear  list).  One  solution  to  this 
problem  is  the  AVL  balanced  tree,  the 
topic  of  this  month’s  column. 

A  few  terms  first:  The  depth  (or 
height)  of  a  tree  is  the  number  of 
links  that  have  to  be  traversed  to  get 
from  a  tree’s  root  to  the  node  that  is 
farthest  from  the  root.  A  tree  with 
only  one  node  in  it  is  of  depth  0.  A 
perfectly  balanced  tree  is  one  in 
which  the  distance  from  the  root  to 
all  leaves  is  the  same  (by  leaf  I  mean  a 
node  with  no  descendants).  Obvious¬ 
ly,  the  number  of  nodes  in  a  perfectly 
balanced  tree  has  to  be  a  power  of  2 
less  1  (1,  3,  7,  15,  31,  and  so  on).  Also 
the  worst-case  search  time  in  a  per¬ 
fectly  balanced  tree  is  log2(N),  where 
N  is  the  number  of  nodes  rounded  up 
to  the  nearest  power  of  2.  A  perfectly 
balanced  tree  has  the  property  that, 
for  any  node,  the  heights  of  the  two 
subtrees  are  the  same. 

AVL  trees  (named  after  their  inven¬ 
tors  Adelson-Velski  and  Landis)  are  al¬ 
most  perfectly  balanced  trees.  They 
have  the  property  that,  for  any  node 
in  the  tree,  the  heights  of  the  two  sub- 
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trees  will  differ  by  at  most  1.  This  will 
give  you  a  perfectly  balanced  tree 
more  often  than  not,  though  there  are 
AVL  trees  in  which  the  maximum  dif¬ 
ference  in  depth  between  leaves  is  2. 
Figure  1,  right,  for  example,  shows  a 
worst-case  balanced  AVL  tree.  There's 
a  difference  in  depth  of  2  between 


node  0  and  node  12,  but  from  the  per¬ 
spective  of  the  root  (node  4),  there's 
only  a  difference  of  depth  1  between 
its  two  subtrees. 

The  overhead  needed  to  maintain 
this  balance  is  minimal.  A  single,  2-bit 
number  is  needed  in  each  node  and  a 
slight  sacrifice  is  made  at  insert  and 
delete  times.  If  these  times  are  criti¬ 
cal,  you  may  be  better  off  with  a  nor¬ 
mal  binary  tree.  On  the  other  hand, 
the  average-case  search  time  in  an 
AVL  tree  is  guaranteed  to  be  0(log2(N)), 
where  N  is  the  number  of  nodes.  You 
usually  search  a  tree  more  often  than 
you  put  a  node  into  it,  so  AVL  trees  are 
pretty  useful  beasts. 

Figures  2  and  3,  page  22,  illustrate 
how  balance  is  maintained  in  an  AVL 
tree.  There  are  four  possible  ways  to 
introduce  an  imbalance  into  the  tree. 
Of  these,  two  of  them  are  mirror  im¬ 
ages  of  the  other  two,  so  they  aren’t 
shown  in  the  figures.  Figure  2  shows 
the  simplest  case.  The  circles  are 
nodes  in  a  tree,  and  the  rectangles  are 
entire  subtrees,  which  may  be  made 
up  of  any  number  of  nodes.  The  sub¬ 
trees  will  be  balanced,  however.  Fig¬ 
ure  2a  shows  a  new  node  (marked 
with  an  X)  being  added  to  the  subtree 
labeled  alpha,  creating  an  imbalance. 
The  imbalance  is  corrected  in  Figure 
2b.  Note  that  the  subtrees  don’t  have 
to  be  modified  at  all,  only  the  point¬ 
ers  associated  with  nodes  C  and  E 
have  to  be  changed.  For  obvious  rea¬ 
sons,  this  correction  is  called  a  (clock¬ 
wise)  right  rotation,  or  RR  rotation. 
The  mirror  image  is  an  LL  rotation. 

The  harder  case  is  illustrated  in  Fig¬ 
ure  3  (I’ll  look  at  the  rest  of  Figure  2  in 
a  moment).  Here  the  imbalance  is  cre¬ 
ated  by  inserting  either  of  the  X- 


marked  nodes  into  the  beta  or  gamma 
subtrees.  The  problem  is  corrected 
with  a  double  rotation.  First,  the  tree 
rooted  at  B  is  rotated  left  (counter¬ 
clockwise),  making  the  left  pointer  of 
node  F  point  at  node  D.  Next,  the  tree 
rooted  at  node  F  is  rotated  right  (clock¬ 
wise),  bringing  node  D  to  the  top  and 
moving  node  F  to  the  right.  This  final 
situation  is  illustrated  in  Figure  3b.  Be¬ 
cause  I've  done  a  right  followed  by  a 
left  rotation,  this  is  called  a  double  RL 
rotation.  The  mirror  image  is  called  a 
double  LR  rotation. 

Figure  4,  page  24,  shows  a  series  of 
insertions  into  an  AVL  tree.  The  pa¬ 
renthesized  letters  tell  whether  the 
subtrees  are  balanced  (B),  unbalanced 
to  the  left  (L)  or  to  the  right  (R). 

AVL  tree  deletion  is  a  marginally 
harder  problem.  First,  let’s  look  at  de¬ 
letion  from  a  normal  binary  tree,  il¬ 
lustrated  in  Figure  5,  page  26.  Node  D 
is  being  deleted  in  all  three  pictures. 
In  5a  and  5b,  because  there  is  only 
one  child,  the  deletion  is  easy;  all  you 
need  to  do  is  make  the  pointer  in  the 
parent  point  around  the  deleted 
node  to  that  node’s  child. 

Deleting  a  node  that  has  two  de¬ 
scendants  is  harder.  Notice  that  the 
rightmost  node  of  the  left  subtree 
(node  C)  will  always  have  the  largest 
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Figure  1:  A  worst-case  balanced  AVL 
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Node  B  is  inserted,  Balance  is  restored, 

creating  an  imbalance. 


Figure  3:  Double  LR  rotation 
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value  of  any  node  in  that  subtree.  Also 
note  that  all  nodes  in  the  right  subtree 
will  have  values  greater  than  both  the 
node  to  be  deleted  (D)  and  the  right¬ 
most  node  of  the  left  subtree  (C).  You 
can  do  the  delete  in  one  of  two  ways. 
The  pointers  can  be  modified  as 
shown  by  the  dotted  lines  in  the  fig¬ 
ure  (moving  C  to  where  D  used  to  be). 
Alternatively,  you  can  transpose  the 
contents  of  nodes  C  and  D  and  then 
delete  node  C  rather  than  D.  To  do  the 
latter,  you  descend  to  node  C  and  then 
copy  everything  except  the  pointers 
from  node  C  to  node  D,  finally  delet¬ 
ing  node  C  (I'm  actually  using  this  lat¬ 
ter  approach  in  the  AVL  routines). 

Deletions  from  AVL  trees  use  the 
same  procedures  as  are  used  in  a  nor¬ 
mal  tree.  As  you  ascend  back  up  the 
tree  from  the  rightmost  node  of  the 
left  subtree,  however,  you  must  re¬ 
balance  every  node  along  the  way. 
Fortunately,  because  you're  deleting 
a  leaf,  rebalancing  is  only  necessary 
about  one  time  in  five.  A  series  of  AVL 
tree  deletions  are  illustrated  in  Figure 
6,  page  27. 

Using  the  AVL  Package 

Before  looking  at  the  AVL  routines 
per  se,  let’s  look  at  an  application.  I’ve 
designed  the  interface  to  the  AVL  rou¬ 
tines  so  that  the  application  program 
doesn’t  know  that  it’s  using  a  tree  to 
store  data.  It  interfaces  to  a  series  of 
database  routines  that  store  data  in 
unknown  ways.  The  application  can 
insert  objects  into  the  database,  de¬ 
lete  items  from  the  database,  find 
items,  and  print  the  entire  database, 
but  it  has  no  knowledge  about  how 
that  database  is  actually  organized. 
This  way  if  you  write  a  different  set 
of  database  routines  that  don't  use 
AVL  trees,  you  don’t  have  to  modify 
the  application  program  (provided 
that  you  maintain  the  same  interface 
to  the  database  routines  themselves). 
Just  as  the  application  doesn’t  know 
anything  about  the  organization  of 
the  database,  the  AVL  tree  routines 
don't  know  anything  about  how  the 
application  is  using  that  database.  All 
knowledge  about  the  contents  of  the 
nodes  is  passed  to  the  AVL  routines  as 
pointers  to  subroutines. 

Tree.h  (Listing  One,  page  86)  is  a 
header  to  be  included  in  all  applica- 
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tion  programs.  It  contains  nothing 
but  extern  statements,  useful  for 
function  prototyping.  The  TREE  type 
is  actually  a  dummy  type — it’s  used 
like  a  FILE  is  used  by  the  standard  I/O 
routines.  Your  program  doesn't  need 
to  know  anything  about  the  actual 
organization  of  either  a  FILE  or  a 
TREE.  The  LEAF  type  that’s  used  in  the 
extern  statements  must  be  defined  in 
the  application  program  before 
tree.h  is  * included  in  your  program. 
A  LEAF  is  a  structure  that  contains  all 
the  fields  that  your  application  is  in¬ 
terested  in.  The  LEAF  doesn’t  need  to 
know  anything  about  trees,  so  it 
doesn't  need  to  include  pointers  to 
children  and  so  on. 

A  LEAF  is  defined  on  line  3  of  test.c 
(Listing  Two,  page  86).  It  is  a  structure 
that  contains  one  field — an  integer 
key.  Of  course,  a  more  realistic  appli¬ 
cation  would  have  more  fields  in  the 
structure,  but  a  single  key  is  all  that's 
needed  for  my  example.  Skipping 
ahead,  the  maint  )  subroutine  (on 
lines  84  —  105)  gets  a  series  of  com¬ 
mands,  first  from  the  command  line 
and  then  interactively  from  standard 
input.  It  executes  these  commands  by 
calling  docmdl  ).  The  following  com¬ 
mands  are  recognized: 

iN — insert  node  N  into  the  tree 
dN — delete  node  N  from  the  tree 
fN — find  node  N  in  the  tree 
a — delete  the  entire  tree 
q — exit  back  to  the  operating  system 

Docmdt /(lines  37— 80)  illustrates 
how  to  use  all  the  database  routines. 
Docmdt  /  is  passed  two  arguments: 
cmd  is  a  single-letter  command  that 
will  correspond  to  one  of  the  cases  in 
the  switch  on  line  42;  n  is  an  integer 
key  that  is  fetched  by  maint  ). 

The  7'  case  (on  lines  57—68)  illus¬ 
trates  both  the  creation  of  a  node  and 
the  insertion  of  that  node  into  the  da¬ 
tabase.  Memory  for  the  node  is 
fetched  from  talloct  /  (on  line  57).  Tal- 
loct  )  is  used  just  like  malloct  )  is.  It 
returns  a  pointer  to  an  area  of  memo¬ 
ry  of  the  specified  size  or  NULL  if  it 
can’t  get  the  memory.  In  this  case  I’m 
allocating  a  single  LEAF  structure  that 
is  initialized  on  line  61. 

The  new  node  is  inserted  into  the 
database  with  the  insertf  /  call  on  line 
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62.  Insert  is  passed  three  arguments:  a 
pointer  to  the  root  (not  the  contents 
of  the  root),  a  pointer  to  the  node  to 
be  inserted,  and  a  pointer  to  a  com¬ 
parison  function.  This  function  is  de¬ 
fined  on  lines  23—28.  It’s  passed  two 
pointers  to  LEAFS,  and  it  works  like 
strcmpf  )  does,  returning  a  negative 
number  if  the  left  argument  is  less 
than  the  right  argument,  0  if  the  ar¬ 
guments  are  equal,  and  a  positive 
number  if  the  left  argument  is  great¬ 


er.  In  the  case  of  two  structures,  the 
relative  value  is  determined  by  com¬ 
paring  the  key  fields. 

Insert (  )  returns  NULL  on  success, 
and  it  returns  a  pointer  to  a  conflict¬ 
ing  node  if  a  node  having  the  indicat¬ 
ed  key  already  exists  in  the  database. 
In  this  application,  the  new  node  is 
just  discarded  (with  the  tfreef  )  call 
on  line  65)  if  a  conflicting  node  exists. 
In  a  more  sophisticated  application, 
you  might  want  to  update  a  count 
field  in  the  conflicting  node  or  do 
some  other  operation. 

The  ’d’  case  (on  lines  44—47)  deletes 


the  node  having  the  indicated  key 
from  the  database.  Delete (  )  returns  0 
if  the  requested  node  isn’t  in  the  tree. 
Delete (  )  is  passed  three  arguments:  a 
pointer  to  the  root,  the  key  to  be  de¬ 
leted,  and  a  pointer  to  a  comparison 
function  (dcmp).  This  comparison 
function  is  defined  on  lines  29  —  33.  It 
is  passed  delete (  J’s  second  argument 
(that's  all  that  deletef  )  does  with  its 
second  argument — passes  it  to  the 
comparison  function)  and  a  pointer  to 
one  node  in  the  tree.  It  compares  the 
two  arguments  and  returns  a  negative 
number  if  the  key  is  less  than  the 
node,  0  if  the  key  equals  the  node,  and 
a  positive  number  if  the  key  is  greater 
than  the  node  (just  like  strcmpf  ) 
does).  I  could  have  used  the  same  com¬ 
parison  function  used  by  insertf  ) 
here,  but  I  would  have  had  to  create  a 
dummy  LEAF  just  to  put  the  key  in  it 
and  then  pass  a  pointer  to  that  dum¬ 
my  node  to  deletef ). 

The  call  to  freeallf )  (on  line  71)  de¬ 
letes  the  entire  database,  as  compared 
to  a  single  node  in  the  database. 

The  case  does  a  find  function. 
Findf  )  returns  a  pointer  to  a  LEAF  if  a 
structure  having  the  indicated  key  is 
in  the  database;  otherwise  it  returns 
NULL.  Findf  )  is  passed  the  contents  of 
the  root  (unlike  insert  and  delete, 
which  are  passed  pointers  to  the 
root);  its  other  two  arguments  are  the 
same  as  deletef  j’s. 

The  remaining  subroutine  of  inter¬ 
est  is  tprintf  )  (on  line  78).  Tprintf  ) 
prints  out  the  entire  tree  graphically, 
using  a  slightly  modified  version  of 
the  graphic/nordertraversal  routine 
1  looked  at  last  month.  That  is,  it 
prints  the  trees  as  they  are  shown  in 
Figures  4  and  6,  with  lines  showing 
all  the  pointer  relationships  between 
nodes.  Tprintf  )  differs  from  last 
month's  routine  in  two  ways.  First, 
it’s  passed  an  output  stream.  If  that 
stream  is  stdout,  and  stdout  is  not  re¬ 
directed  to  a  file,  then  IBM  box-draw¬ 
ing  graphic  characters  are  used  in¬ 
stead  of  plus  signs  and  dashes.  Next,  it 
is  passed  a  pointer  to  a  print  subrou¬ 
tine  (because  the  database  routines 
don’t  know  anything  about  the  con¬ 
tents  of  a  LEAF,  you  have  to  pass  it  a 
print  routine).  This  routine  (defined 
on  lines  9  —  19)  is  passed  an  output 
stream  and  a  pointer  to  a  LEAF.  It 
should  print  the  node's  contents  if 
that  pointer  is  non-NULL;  otherwise  it 
should  print  as  many  space  charac- 
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ters  as  it  would  use  to  print  these  con¬ 
tents.  That  is,  it  must  always  print  the 
same  number  of  characters.  Some¬ 
times  those  characters  are  the  node's 
contents,  and  sometimes  they’re 
spaces,  depending  on  whether  the 
LEAF  pointer  is  NULL. 

The  AVL  Routines 

The  AVL  tree  functions  are  in  Listings 
Three  through  Eight,  pages  87—102. 
I've  merged  all  these  routines  into  a 
single  library  and  linked  that  library 
with  test.obj.  Listing  Nine,  page  102,  is 
a  makefile  for  creating  both  library 
and  test.exe.  I'm  using  the  Microsoft 
C  compiler  and  Polymake,  but  most 
of  the  commercial  makes  will  work. 

Avl.h  (Listing  Three,  page  87)  is  a 
header  file  used  by  all  the  library 
routines  but  not  by  the  application 
program.  A  tree  node  is  defined  by 
the  HEADER  structure  on  lines  1—8 
and  is  pictured  in  Figure  7,  page  28. 
Tallocl  )  (Listing  Seven,  page  90,  lines 
20—34)  uses  the  same  sort  of  data 
structure  that  mallocl )  uses  to  keep 
track  of  the  free  list.  It  gets  the 
amount  of  memory  that  the  user 
needs  plus  enough  memory  for  a 
HEADER.  So  the  data  space  is  extra 
memory  concatenated  onto  the  end 
of  a  HEADER.  As  you  can  see  in  Figure 
7,  mallocf  )  returns  a  pointer  to  just 
below  the  header  that  it  uses.  Similar¬ 
ly,  tallocl  )  adds  its  own  header  to  this 
memory  and  returns  a  pointer  to  just 
below  that  second  header.  Tfreel  ) 
(on  lines  38—42)  is  passed  the  pointer 
that  tallocl  )  returns.  It  decrements 
that  pointer  to  get  back  the  pointer 
that  mallocl  )  returned. 

In  the  small  model,  a  tallocl  )  HEAD¬ 
ER  uses  6  bytes  (two  pointers  and  an 
int).  The  mallocl  )  header  (if  Micro¬ 
soft's  mallocl )  is  anything  like  the 
one  in  K  &  R)  uses  4  bytes  (one  pointer 
and  one  int ).  So  a  total  of  10  bytes  (in 
addition  to  the  amount  of  memory 
needed  for  the  data  area)  are  re¬ 
quired  as  overhead  in  each  tree  node. 
Note  that,  as  is  the  case  in  mallocl  ), 
the  application  program  doesn’t 
know  (or  care)  anything  about  the 
contents  of  the  HEADER,  so  the  data¬ 
base  routines  can  put  anything  they 
like  up  there  without  affecting  the 
application  program. 

A  HEADER  contains  four  fields:  left 
and  right  are  pointers  to  the  subtrees; 
size  is  the  size  of  the  application  area 
(the  parameter  passed  to  tallocl  ) — it's 


used  by  the  delete  routine).  The  bal 
field  is  used  to  keep  track  of  the  rela¬ 
tive  sizes  of  a  node's  two  subtrees.  In 
most  AVL  routines  the  balance  factor 
is  determined  by  subtracting  the 
height  of  the  left  subtree  from  the 
height  of  the  right  subtree.  Because 
of  the  way  that  AVL  trees  work,  this 
number  will  always  be  —  1,  0,  or  1.  In 
order  to  be  able  to  put  the  balance 
factor  into  a  bit  field,  which  must  be 
an  unsigned  int,  I've  added  1  to  this 
equation,  shifting  the  three  numbers 
up  to  0,  1,  and  2.  Bal  is  0  if  the  left 


subtree  is  larger,  1  if  the  subtrees  are 
the  same  height,  and  2  if  the  right 
subtree  is  larger.  To  make  the  code 
more  readable,  these  three  numbers 
are  ^defined  as  L,  B,  and  B  (left,  bal¬ 
anced,  and  right)  on  lines  12—14  of 
avl.h.  The  remainder  of  the  include 
file  is  extern  statements  for  all  non¬ 
static  (globally  accessible)  subroutines 
in  the  various  tree  files. 

The  tree-printing  routine  ( tprintl )) 
is  in  Listing  Four  (page  87).  One  of  two 
character  sets  is  used  to  print  the  con¬ 
necting  lines.  Graph— chars  (line  38) 
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!  +~  9(B) 

7(B)— 

—  1(B) 

—  3(L)—+ 

—  1(B) 

(f)  Node  2  has  been  deleted. 


♦-10(B)- 

1 

—11(B) 

-+ 

—  9(B) 

—11(B) 
♦—10(B)— + 

!  —  9(B) 

—  6(B) 

7(R)— 

—  3(B) 

—  3(B) 

+ 

(g) 

Node  1  has  been  deleted. 

—  1(B) 

—11(B) 

—  9(B) 


10(L)-+ 

I 
I 

—  3(R)— + 

(h)  Node  7  has  been  deleted. 
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contains  the  IBM  box-drawing  graph¬ 
ic  characters.  Norm^chars  (line  41) 
contains  plus  signs  and  dashes.  Cset 
(line  45)  will  point  to  one  or  the  other 
of  these  sets,  and  the  macros  on  lines 
21  —  26  are  used  to  get  at  a  specific 
string.  There's  one  for  each  of  the 
various  corners  and  tees  that  are 
needed  to  draw  the  tree. 

The  macros  on  lines  28  —  34  are  de¬ 
bugging  diagnostics.  Defining  them  in 
this  way  makes  the  code  cleaner  as 
PAD  and  PH  A  I.  will  expand  to  empty 
strings  if  DEBUG  isn’t  # defined .  This 
way  you  don't  have  to  litter  the  code 
with  #ifdef  DEBUG  statements. 

The  general-purpose,  bit-map  rou¬ 
tines  used  last  month  have  been  re¬ 
placed  by  the  testbitf  )  macro  and  the 
setbit(  )  subroutine  on  lines  52—61. 
They  work  in  the  same  way  as  last 
month’s  routines  do,  but  they're 
smaller. 

The  traversal  routines  are  recur¬ 


sive,  and  as  is  generally  the  case  with 
recursive  routines,  I've  tried  to  mini¬ 
mize  the  size  of  the  stack  frame  by 
putting  as  many  variables  as  possible 
into  global  statics.  Tprintf  )  (lines 
125  — 135)  is  an  access  routine,  initializ¬ 
ing  these  global  variables  and  then 
calling  the  workhorse  function  trav(  ) 
(lines  66  —  121)  to  do  the  work. 
Tprintf  )  decides  which  character  set 
to  use  on  lines  132—133.  If  the  output 
stream  is  stdout  and  this  stream  is  at¬ 
tached  to  a  device  (as  compared  to  a 
file),  graphic  characters  are  used.  So, 
graphic  characters  will  be  used  if 
stdout  is  not  redirected  to  a  file.  Note 
that  isattyf  )  returns  true  if  stdout  is 
assigned  to  any  device,  so  graphics 
will  be  used  if  stdout  is  redirected  to 
the  printer.  I've  used  isattyf  )  because 
it's  easy.  If  you  prefer  you  can  use  DOS 
function  Oy.44  (IOCTL)  to  see  if  the  de¬ 
vice  is  actually  the  console  or  not  (as 
compared  to  a  printer  or  whatever). 

Travf  )  uses  the  same  algorithm  as 
inorderf )  used  last  month;  consult 
last  month’s  column  for  details  of  its 


operation.  The  only  differences  have 
to  do  with  getting  either  the  graphics 
or  normal  characters  printed  at  the 
appropriate  places  (and  the  printing 
is  done  indirectly  through  a  pointer 
to  a  print  subroutine). 

Findf  )  (Listing  Five,  page  89)  does  a 
simple,  recursive  descent  into  the 
tree.  From  find's  point  of  view,  it 
doesn’t  matter  that  the  tree  is  an  AVL 
tree  because  it  doesn’t  need  to  use  ei¬ 
ther  the  size  or  bal  fields  of  the  HEAD¬ 
ER  structure.  Similarly,  freeallf  )  (List¬ 
ing  Six,  page  89)  also  does  a  recursive 
postorder  traversal,  freeing  the  mem¬ 
ory  used  by  the  current  node  after 
freeing  both  the  right  and  left  sub¬ 
trees. 

The  hard-to-do  functions  are  in¬ 
serts  and  deletes.  Insertf  )  is  in  Listing 
Seven,  lines  148  — 166.  As  was  the  case 
in  tprintf ),  insertf  )  is  actually  an  ac¬ 
cess  function  that  initializes  a  few 
static  global  variables  and  then  calls 
the  static  workhorse  function  insf  ), 
on  lines  46  —  144.  The  algorithm  used 
here  (and  in  the  delete  function 
below)  are  straightforward  transla¬ 
tions  of  the  Modula-2  code  in  Algo¬ 
rithms  &  Data  Structures  (Niklaus 
Wirth,  Englewood  Cliffs,  N.J.:  Pren¬ 
tice-Hall,  1986)  pp.  218-227.  I’ve 
cleaned  up  Wirth ’s  code  considera¬ 
bly,  but  the  algorithms  are  the  same. 
(It’s  a  mystery  to  me  how  the  inven¬ 
tor  of  Modula-2  can  write  such  miser¬ 
able  code  in  Modula-2.) 

The  static  variable  h  (declared  on 
line  56)  is  a  little  weird.  It  will  change 
its  value  magically  after  every  recur¬ 
sive  insf  )  call  to  reflect  whether  the 
tree  has  grown  in  depth  as  the  result 
of  an  insert.  In  this  case  a  rebalance  of 
some  sort  is  needed.  Left  subtree  re¬ 
balancing  is  done  on  lines  80—103  and 
right  rebalancing  on  lines  110—140. 
Figures  2c  and  2d  illustrate  how  the 
pointers  are  juggled  to  do  an  RR  rota¬ 
tion.  Figures  3c  and  3d  illustrate  a  dou¬ 
ble  LR  rotation.  The  rebalances  are 
done  as  you  ascend  back  up  the  tree 
from  the  newly  inserted  node. 

The  deletef  )  function  is  in  Listing 
Eight  (page  96).  The  access  function  is 
at  the  end  of  the  file  (lines  220  —  240); 
the  workhorse  function  ( delf  ))  is  on 
lines  165—216.  Delf  )  descends  to  the 
node  to  be  deleted  in  the  usual  way 
on  lines  182—192.  Got— smaller  is  used 
in  the  same  way  as  h  was  used  in  the 
insert  function.  Here,  though,  you’re 
noting  whether  the  tree  has  shrunk 
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rather  than  grown.  The  calls  to  balan¬ 
ce— l(  )  and  balance— r( )  (sources  on 
lines  21-135)  do  a  left  or  right  rebal¬ 
ance  when  appropriate.  These  rou¬ 
tines  use  pretty  much  the  same  code 
that  was  used  in  the  insert  function. 
You  might  want  to  make  insertf )  call 
these  routines  rather  than  using  the 
imbedded  code  if  space  is  tight. 

Once  found,  the  node  is  actually 
deleted  on  lines  194-212.  Dp  points 
at  the  node  to  be  deleted.  The  two 
easy  cases  (pictured  in  Figures  5a  and 
5b)  are  done  on  lines  196  —  204.  The 
hard  case,  in  which  the  current  node 
has  two  children,  is  done  by  de¬ 
scend!  J,  called  on  line  206. 

Descendf  )  (lines  139  —  161)  de¬ 
scends  recursively  to  the  rightmost 
node  of  the  left  subtree  (it’s  passed  a 
pointer  to  the  left  subtree  the  first 
time  it’s  called).  When  it  gets  there, 
descendi )  copies  the  contents  of  that 
node  up  into  the  node  to  be  deleted 
(pointed  to  by  dpp)  and  modifies  dpp 
to  point  at  the  current,  rightmost 
node  (on  line  157).  It  then  ascends  the 
way  it  just  came,  rebalancing  as  it 
goes  up. 

Conclusion 

So  that's  AVL  trees.  The  code  is  obvi¬ 
ously  more  complicated  than  that  for 
simple  binary-tree  routines,  but  the 
complexity  is  worth  it  if  you  need 
fast  access  time  into  the  tree.  Next 
month  I’ll  round  off  my  discussion  of 
trees  by  looking  at  a  directory-tree 
printing  routine  that  graphically 
prints  a  map  of  your  hard  disk’s  di¬ 
rectory  tree. 

Availability 

All  the  code  published  this  month  is 
available  both  on  CompuServe  (type 
go  ddjforum)  and,  for  $25,  on  an  IBM 
PC-compatible  disk  from  Software 
Engineering  Consultants,  P.O.  Box 
5679,  Berkeley,  CA  94705.  The  tree 
routines  from  last  month  are  on  the 
same  disk. 
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BENCHMARKING 
C  COMPUTERS 


by  Richard  Relph,  Steve  Hahn,  and  Fred  Viles 


This  review  is  based  on 
\  the  best  information 
available  as  of  the  arti¬ 
cle  deadline,  May  15. 

J  Harming  Light,  page  8, 

J  which  has  a  later  dead- 
J  line,  contains  updated 
information  received  by  June  1.  The  two  months  between 
|  our  deadline  and  our  August  publication  date  can  be  a  long 
time  in  the  competitive  C  compiler  market,  in  which  an 
adequate  product  may  become  superlative  in  the  neyt  ver¬ 
sion.  We  will  be  publishing  updates  as  o  ften  as  is  necessary 
J  and  will  be  maintaining  even  more  information  on  the  com- 
\  pilers  in  the  DUJ  Electronic  Edition  on  CompuServe.  See  Dl)J 
j  On  Line,  page  18,  for  more  information  about  the  Electronic 
\  Edition.  The  Editorial,  page  6,  contains  a  list  of  the  vendors ' 
addresses  and  phone  numbers. — eds. 

This  is  a  review  of  17  C  compilers  for  MS-DOS  from 
15  different  companies,  its  intent  is  to  provide 
knowledgeable C  programmers  with  insights  into 
each  of  the  products  otherwise  unobtainable  without 
purchasing  the  compiler.  It  is  a  very  detailed  study,  and 
more  casual  C  programmers  may  find  some  of  the  details 
confusing  or  of  little  value.  We  have  therefore  attempted 
to  put  the  generally  interesting  information  at  the  begin¬ 
ning  of  each  major  section,  just  prior  to  a  gradual  (or  rap- 
I  id)  descent  into  the  nitty-gritty. 

The  Reviewers 

j  Any  review  of  this  magnitude  is  clearly  a  difficult  task. 
Were  it  not  for  the  assistance  of  many  people,  including 
the  vendors  themselves,  it  would  have  been  impossible. 


Richard  Helph,  8345  Springdale  Ct.,  Gilroy,  C.A  95020;  Steve 
Hahn,  03  Sheridan  Hd.,  Oakland,  CA  94018;  Ered  Viles,  1854 
Halfpence  Way,  San  Jose,  CA  95132. 


We  would  like  to  thank 
especially  those  who 
worked  Saturdays  and 
evenings  to  review 
documentation  and 
package  compilers. 
These  people  are  Joe 
Marshall,  Peter  Vutz,  Scott  Thomas,  Phil  Freiden,  Stan  Pe¬ 
ters,  Fletcher  Johnson,  and  Don  Hackler.  Other  C-SIG  mem¬ 
bers  also  contributed. 

Last  year  some  of  us  participated  in  the  writing  of  a 
similar  review  (DDJ,  August  1985).  After  the  review  was 
completed,  we  approached  Manx  Software  Systems  in 
order  to  arrange  a  group  buy  of  its  package,  one  of  the 
best  last  year.  As  a  result,  nearly  all  of  this  year's  review¬ 
ers  own  Manx  Aztec  C.  To  counter  this,  and  the  other 
reviewers'  personal  ownership  of  any  given  C  compiler, 
reviewers  were  prohibited  from  making  any  subjective 
comments  regarding  compilers  they  owned.  We  feel  that, 
by  making  these  statements  up  front,  we  will  put  your 
mind  at  ease  regarding  our  objectivity. 

Last,  the  principal  authors  of  this  review  are  profes¬ 
sional  programmers.  We  make  our  living  writing  C  pro¬ 
grams.  Consequently,  this  review  is  geared  toward  pro¬ 
fessional  programmers. 

The  Compilers 

Since  our  last  comparative  review  of  C  compilers,  three 
vendors  have  left  the  marketplace,  five  vendors  have 
products  to  be  reviewed  here  for  the  first  time,  and  all 
others  have  new  versions  or  products.  In  general,  things 
are  not  the  same  as  last  year,  and  some  results  are  surpris¬ 
ing.  Documentation  has  improved  across  the  board,  as  has 
compiler  quality.  Libraries  are  bigger  and  better  than  last 
year. 

Microsoft,  Lattice,  Mark  Williams  Co.,  Ecosoft,  Data- 
light,  and  Wizard  Systems  Software  provided  substantial¬ 
ly  changed  (major  version  number)  compilers  for  review. 


Documentation  has  improved 
across  the  board ,  as  has 
compiler  quality. 
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Manx  and  C  Ware  Corp.  both  added  significant  features  to  j 
their  compilers  with  only  minor  version  number  ' 
changes.  Software  Toolworks  has  added  long  and  float 
support  as  an  add-on  option,  which  we  reviewed.  Only 
Computer  Innovations  has  approximately  the  same  pack¬ 
age  as  last  year.  O-systems,  Control-0  Software,  and  Digital 
Research  have  stopped  marketing  MS-DOS  0  compilers.  ; 
New  to  the  review  this  year  are  Whitesmiths,  MetaWare, 
Word  l  ech  Systems,  Mix  Software,  and  IBM.  Companies 
queried  about  having  their  compilers  reviewed,  but  de¬ 
clining,  were  Supersoft  and  Codeworks,  Telecun  Systems 
could  not  be  located 

All  in  all,  15  companies  provided  compilers  two  of 
them  (Mark  Williams  and  DatalighD  provided  two,  bring¬ 
ing  the  number  of  packages  reviewed  to  17.  Some  ven¬ 
dors  opted  to  send  beta  versions  of  compilers  due  to  be  out 
bv  t he  time  you  read  this.  Beta  testing  gives  a  vendor  a 
chance  to  test  a  product  more  thoroughly  lie  fore  release 
to  the  buying  public.  We  found  bugs  in  all  beta  compilers 
and  reported  them,  both  here  and  to  the  vendor  Unless 
otherwise  noted,  all  bugs  were  expected  to  be  fixed  be¬ 
fore  final  releast!. 

The  tienchmurks 

Results  of  benchmark  tests  of  compilers  have  a  justifiably 
bad  reputation.  All  too  often  performance  figures  are 
cited  out  of  context  or  overgeneralized  into  overall  rat¬ 
ings;  all  too  often  the  tests  are  misapplied,  incorrectly  per¬ 
formed.  or  inadequately  documented.  We  have  attempt¬ 
ed  to  provide  repeatable  measures  of  performance  of  the  j 
compilers  on  tests  chosen  to  detail  the  strengths  and  j 
weaknesses  of  the  individual  compilers. 

We  would  have  liked  to  run  all  the  benchmarks  on  all 
available  machines,  but  this  proved  to  be  impossible.  In¬ 
stead,  we  ran  them  on  an  AT&T  (>300  with  640 K  and  an 
8087,  All  benchmarks  were  run  on  a  HAM  disk,  with  care¬ 
ful  attention  paid  to  the  layout  of  the  storage.  The  AT&T 
has  an  8-MHz  clock  and  a  16-bit  bus.  The  processor  was 
not  the  customary  8086  but  a  NEC  V30.  The  effect  of  using 


the  V30  is  discussed  later, 

This  year,  we  did  manage  to  test  all  the  compilers  for  j 
conformance  to  some  standard.  To  do  so  required  the  use 
of  a  validation  suite,  and  we  were  fortunate  enough  not  to 
have  to  write  one.  The  source  of  the  suite  is  also  a  re-  j 
viewee  (MetaWare),  however,  and  this  should  be  noted. 
We  polled  some  other  compiler  vendors  to  see  if  they  had 
any  objection  to  our  using  a  competitor's  test  suite,  and 
the  only  point  made  was  that  tailing  a  given  test  should  j 
not  be  treated  as  significant  unless  acknowledged  so  by  j 
either  K  &.  K  or  the  failing  compiler's  vendor. 

All  our  execution-time  benchmarks  have  the  same  basic  j 
structure.  Each  test  function  starts  by  initializing  whatever  ! 
it  wants  to,  starting  the  timer,  doing  the  task,  getting  the  j 
current  time  (relative  to  start),  doing  any  wrap-up  chores,  j 
and  returning  the  time.  To  start  the  timer,  we  have  provid¬ 
ed  each  compiler  with  a  time—U  function  and  a  companion  j 
function,  time  j t,  which  returns  the  time  elapsed  since  the  ! 
last  time  A)  call  in  tenths  of  seconds.  The  number  of  times  ; 
that  the  task  is  done  is  controlled  by  a  loop  count  passed  j 
into  the  test  function  from  main. 

Main  is  made  independent  of  the  test  to  be  run  by  hav-  j 
ing  it  reference  an  array  of  structures,  btn,  which  each  j 
source  fill!  that  contains  an  execution  benchmark  con-  j 
tains.  The  structure  has  a  pointer  to  the  function  to  be  ! 
tested,  the  name  of  the  function  (for  reporting  purposes),  j 
thi!  loop  count,  and  a  place  to  keep  the  return  value  (the  j 
execution  time).  Main  steps  through  this  array,  calling  ; 
each  function  in  turn,  passing  it  its  loop  count,  and  saving  1 
the  return  value  in  the  structure.  After  each  function  call,  I 
main  dumps  the  results  for  that  function  to  the  screen.  ] 
When  it  reaches  the  end  of  the  array,  main  opens  a  re-  j 
suits  file  and  writes  the  results  out  so  that  we  can  manipu-  ; 
late  them  later  1  here  is  a  special  version  of  main  for  the  \ 
8087  tests,  which  multiplies  each  loop  count  by  10  before  ; 
passing  it  to  the  test  function. 

When  reviewing  the  results  from  these  benchmarks,  j 
be  sur  e  not  to  add  up  either  total  wins  or  total  execution  | 
time  for  the  whole  set.  To  do  so  would  assume  that  the  j 
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sum  ul  the  contrived  tests  we  have 
thrown  together  represents  a  typi¬ 
cal  program,  which  it  certainly  does 
not.  Instead,  go  through  the  descrip¬ 
tions  of  each  of  the  benchmarks  and 
decide  how  much  each  feature  tested 
is  present  in  your  code. 

The  closest  thing  to  a  typical  pro¬ 
gram  in  this  benchmark  suite  is  the 
dhrvstone.  hut  even  its  results  'see 
I  able  page  -4 1)  must  he  taken  with  a 
large  block  of  salt  The  dhrvstone  as 
presented  here  is  about  20  percent 
dependent  on  how  string  library 
functions  are  implemented.  Meta- 
Wares  compiler,  for  example,  turns 
in  892  dhrvstones  per  second  when 
calling  its  very  fast  'based  on  the  re¬ 
sults  of  string!  string  library  func¬ 
tions.  but  when  dhrvstone  is  recom¬ 
piled  with  Meta  Ware  s  string. h  til*', 
which  maps  the  string  functions  onto 
special  compiler-recognized  func¬ 
tions  for  in-line  code  generation,  its 
compiler  gains  184  dhrvstones  per 
second,  giving  1,070.  Wizard's  com¬ 
piler  is  near  the  bottom  of  the  list  ot 
dhrvstone  contenders  hut  has  excel¬ 
lent  results  in  the  other  compiler 
benchmarks,  the  reason  is  that 
when  we  ran  our  tests.  Wizard  had 
written  its  string  package  in  l'  When 
it  changed  this  to  use  assembly  lan¬ 
guage,  this  compiler,  too,  added 
about  20  percent  to  its  dhrvstone 
score.  This  apparent  flaw  in  the 
benchmark  'when  compared  to  the 
comments  which  claim  no  library 
dependency  at  all'  is  because  dhry¬ 
stone  was  originally  written  in  Ada 


which  allows  string  assignment  and 
comparison  in  the  basic  language. 

Here  are  brief  descriptions  of  the 
benchmarks  we  used  in  this  review: 

•array  tests  the  compiler's  ability  to 
access  arrays  using  conventional  ar¬ 
ray  operations  In  it  we  copy  one 
10 X 10X  10-integer  array  to  another 
using  three  nested  for  loops 
•atox  tests  three  functions  atoi,  atol, 
and  ataf  in  a  single  benchmark  It 
has  21  atoi  calls,  10  alol  calls,  and  8 
atof  calls  Kach  call  passes  a  string 
constant,  some  of  which  have  large 
numbers  of  lead  0s  or  blanks 

•  cpvblk  copies  one  10,000-bvte  file  to 
another  in  1,024-bvte  blocks  using 
/read  and  / write  in  a  simple  while 
loop. 

•epyehr  does  the  same  thing  but  uses 
fgete  an dfputf  Comparing  the  times 
will  tell  you  whether  block  or  char 
actor  I/O  is  faster  for  a  given 
compiler 

•diskio  tests  the  speed  of  /.seek  opera¬ 
tions  inside  a  240k  tilt;  The  test  is 
based  on  a  benchmark  published  by 
Houston.  Broderick,  and  Kent  in  the 
August  1083  issue  of  By/e.  We've 
changed  it  so  lhat  the  file  is  created 
externally  with  a  pattern  in  it  so  that 
data  read  and  written  at  each  posi¬ 
tion  can  be  verified. 

•docl  through  doc  1000  are  used  In 
measure  compiler  speed  Docl  gives 
vou  a  base  for  the  compiler  load  and 
start-up  time  It  consists  of  the  single 
declaration  ini  ,v;.  Doc  1000  is  the  other 
end  a  1,000-line  program.  By  sub¬ 
tracting  docl  compile  time  from  that 
for  doc  1000,  you  obtain  the  time  to 
compile  999  lines  of  source. 

•  libtest  is  the  standard  recursive  Fi¬ 
bonacci  number  generator.  We  pass 
24  into  it  A  good  result  here  means  a 
compiler  generates  good  function  en¬ 
try  and  exit  code  Note  that  til)  does 
not  have  any  locals  and  has  only  one 
argument. 

•  lillser  tests  the  speed  of  screen  out¬ 
put  in  the  absence  of  scrolling.  It  uses 
[Hits  to  write  1,248  characters  per 
loop  to  the  screen,  gradually  lilting  it 

•  We  have  tour  functions  to  test  func¬ 
tion-calling  overhead.  The  functions 
call  another  function  with  zero,  one, 
two,  or  three  parameters.  I  lie  called 
functions  do  nothing  but  return. 
Kach  loop  does  500  function  calls,  and 
we  did  10,000  loops  for  each  function. 

•  to  test  function-return  capabilities, 


we  created  a  function  dfuncret. 
which  returns  a  double'.  The  value  re¬ 
turned  is  U.  The  call  looks  like  ret  = 
\funcl  ret  J;. There  are  1,000  calls  to 
,\func  per  loop.  Dfuncret  is  run  with 
250  loops  in  software  floating-point 
environments  or  with  2,500  loops  in 
8087  environments. 

•  looptst  is  a  simple  test  of  for  loops. 
Kach  loop  does  an  inner  loop  10,000 
times.  We  ran  this  test  with  an  outer 
loop  count  of  500.  The  purpose  of 
looptst  is  to  find  out  about  a  compil¬ 
er's  loop  overhead. 

•  memory  is  our  test  of  the  malloc 
free  function  pair.  For  each  of  500 
outer  loops,  we  malloc  500  50-bvte 
spaces,  free  every  fifth  one,  then 
malloc  100  35-byte  spaces  and  free  all 
the  blocks. 

•  t  he  min  series  arc  tests  to  measure 
library  granularity.  We  have  a  min- 
main  to  provide  a  base  line  number 
for  start-up  code  and  termination 
code.  We  add  calls  to  print)'  in 
minprtf  to  see  what  sort  of  space  pen¬ 
alty  must  be  paid  for  this  frequently 
used  function.  Where  easy,  we  ex¬ 
clude  floating-point  routines  Min- 
puts  replaces  the  print)  with  a  sim¬ 
pler  puts  call  In  see  the  effect  of 
more  explicit  calls  to  fopen,  fgete,  \ 
Iputc,  f'read,  fwrile,  and  fclose,  we  use 
minlin 

•  optimize  is  our  weakest  bench¬ 
mark  It  is  used  to  measure  the  differ¬ 
ences  between  dumb  and  smart  com¬ 
pilers.  Although  a  good  time  here  is 
positive,  the  benchmark  is  extremely 
artificial  and  is  prone  to  being  re¬ 
duced  to  virtually  nothing  by  rela¬ 
tively  simple  optimization  tech¬ 
niques  We  did  make  each  compiler 
provide  assembly-language  output 
for  this  test  so  we  could  compare  the 

v  arious  optimizers.  In  the  future,  the  j 
w  hole  area  of  optimization  should  be 
the  subject  of  a  separate  test  suite  in 
which  each  function  will  test  tor  the 
presence  of  a  specific  optimization. 

•  pointer  is  an  attempt  to  duplicate 
arrays  with  pointers  without  getting 
rid  of  the  three  levels  of  indirection. 
What  we  ended  up  with  is  not  v  ery 
representative,  but  it  does  test  point¬ 
er  dereferencing  fairly  well.  We 
have  the  same  two  10 X  U)X  Ill-inte¬ 
ger  arrays  from  the  array  bench¬ 
mark.  We  add  six  pointers  (three 
each  for  the  source  and  destination 
arrays'  and  set  up  the  first  pointer  to 
actually  move  through  the  array.  A 
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second  pointer  points  at  this,  and  the 
third  points  at  the  second.  Then  the 
body  of  the  inner  loop  looks  like 
*  *  *dp3  =  *  *  *sp3,  and  the  for  state¬ 
ment  moves  sp  1  and  dpi  through  the 
arrays. 

•prtf  is  an  attempt  to  measure  printf 
conversion  efficiency,  but  it  is  mostly 
bound  by  console  I/O  limitations.  Be¬ 
cause  of  this,  the  prtf  results  should 
be  compared  to  the  scroll  results  to 


find  the  overhead  directly  attribut¬ 
able  to  printf  conversions.  The  line 
lengths  are  the  same  in  prtf  and 
scroll. 

•We  think  the  sieve  is  a  useful  bench¬ 
mark,  just  not  one  that  any  reason¬ 
able  C  programmer  would  have  writ¬ 
ten  without  register  variables. 
Therefore,  we  provide  two  ver¬ 
sions — the  standard  sieve,  without 
register  variables,  and  our  rsieve, 
which  has  register  variables  i  and  k. 
We  do  140  iterations  rather  than  the 
normal  10  so  that  our  timer  will  have 


something  fairly  significant  to 
measure. 

•scroll  is  used  to  see  if  any  compilers 
differ  in  the  way  screen  scrolling  af¬ 
fects  them.  It  is  identical  to  the  earlier 
fillscr  except  that  a  new  line  replaces 
the  bare  carriage  return  done  every 
78  characters. 

•We  have  a  series  of  tests  to  see  how 
the  compilers  differ  in  treatment  of 
various  storage  classes.  We  have  a  test 
with  four  automatic  variables,  a  test 
where  the  variables  are  declared  stat¬ 
ic,  a  test  where  all  are  declared  regis¬ 
ter,  and  a  test  where  only  two  are  de¬ 
clared  register.  The  purpose  of  the 
last  test  is  to  see  if  any  compilers  im¬ 
plement  more  than  two  registers.  If 
any  do,  then  regtest  will  be  different 
from  reg2test. 

•To  test  some  basic  string  manipula¬ 
tions,  we  use  our  strings  benchmark. 
For  each  loop,  we  call  strcat  four 
times;  strcpy  twice;  and  strncpy, 
strlen,  strcmp,  and  strncmp  once, 
•tdouble  and  tfloat  are  used  to  mea¬ 
sure  basic  floating-point  speed.  Each 
loop  does  40  adds,  subtracts,  and  mul¬ 
tiplies  and  20  divides.  Both  tdouble 
and  tfloat  do  500  iterations,  so  a  K  &,  R 
compiler  (which  must  convert  floats 
to  doubles  before  doing  any  arith¬ 
metic)  should  be  slower  on  tfloat  than 
on  tdouble.  The  emerging  ANSI  stan¬ 
dard  no  longer  requires  this 
promotion. 

•For  measuring  basic  integer  arith¬ 
metic  speed,  we  have  tint  and  tlong. 
Both  are  identical,  except  that  tlong 
has  all  its  variables  declared  long, 
whereas  tint  uses  integers.  Each  loop 
does  1,500  adds,  1,600  subtracts,  200 
multiplies,  and  200  divides.  Note  that 
tint  does  1,500  loops,  whereas  tlong 
does  only  1,000. 

•trig  does  12  calls  each  loop  to  sin, 
cos,  and  tan  to  measure  the  speed  of 
trigonometric  functions.  Each  func¬ 
tion  is  called  with  constant  .392699 
and  its  multiples  up  through 
5.890486. 

As  mentioned,  we  used  a  machine 
with  a  V30  processor  rather  than  an 
8088  or  8086.  The  effect  of  the  V30  is 
strongest  in  three  areas:  memory  ac¬ 
cess,  multiplication,  and  string  in¬ 
structions.  The  8086  has  several  ad¬ 
dressing  modes  that  vary  from  2  to  15 
clocks  to  compute.  The  V30  has  the 
same  addressing  modes,  but  it  takes 
only  two  clocks  to  compute  all  except 
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Table  and  Figure  Summary 


All  the  tables  and  numbers  can  ap¬ 
pear  overwhelming  at  first,  so  we 
thought  we  should  summarize  the 
main  points,  table  by  table. 

Table  1,  page  36,  indicates  extras 
that  come  with  a  compiler  to  make  it 
a  programming  environment. 

Table  2,  page  36,  presents  our 
memory  models,  which  are  used  to 
provide  bases  of  comparison  for  Ta¬ 
ble  3,  page  38.  Table  3  shows  which 
compilers  have  which  memory  mod¬ 
els,  what  they  call  them,  and  the  op¬ 
tions  to  invoke  them. 

Table  4,  page  41,  the  dhrystone  ta¬ 
ble,  has  some  of  our  most  surprising 
results.  The  "winners”  here  have  to 
be  the  Datalight  products.  Although 
they  do  not  support  register  vari¬ 
ables,  they  produce  the  best  results 
for  no  registers  and  lose  to  Microsoft 
C  and  IBM  C  by  very  little  when  regis¬ 
ters  are  specified.  We  ran  each  com¬ 
piler  with  the  set  of  compiler  options 
indicated  in  the  flags  column.  Usual¬ 
ly  these  flags  told  the  compiler  to  re¬ 
lax  the  aliasing  rules  or  to  generate 
fast,  rather  than  compact,  code.  See 
the  section  in  the  article  on  bench¬ 
marks  for  more  information. 

Table  5,  page  42,  shows  execution 
times  achieved  using  the  small-mem¬ 
ory  model  and  is  the  heart  of  our 
benchmarks.  The  LC  column  repre¬ 
sents  the  loop  counts  of  the  bench¬ 
marks.  The  section  of  the  article  on 
benchmarks  provides  more  informa¬ 
tion  about  the  loop  counts.  There  are 
some  significant  holes  in  Table  5:  Tool¬ 
works  C  could  not  compile  our 
switches  benchmark  even  after  al¬ 
lowing  more  case  label  space.  Eco-C88 
did  not  produce  an  execution  time  for 
cpyblk,  even  though  we  think  it  ran. 
Overall,  the  Datalight  products,  High 
C,  Microsoft  C,  IBM  C,  and  Wizard  C 
win  in  most  of  the  categories.  We  are 
at  a  loss  to  explain  the  difference  be¬ 
tween  Datalight  C  and  Datalight  C  De¬ 
veloper’s  Kit  for  cpychr  and  think  we 
did  something  to  the  latter  to  slow  it 
down.  Wizard  C  is  weak  in  the  library 
area,  presumably  because  much  of  it 
is  implemented  in  C  rather  than  as¬ 
sembly.  Whitesmiths  C  proves  it  has 
three  register  variables  with  a  much 


better  time  on  regtest  than  reg2test. 
Mix  C  produced  the  fastest  time  for 
diskio  but  was  disqualified  because  it 
got  the  wrong  answer.  Microsoft  C 
and  IBM  C  clearly  won  our  switch2 
and  switch3  benchmarks  but  did  so 
by  optimizing  away  the  whole 
switch,  which  was  not  our  intent.  A 
similar  result  on  sieve  and  rsieve  no 
longer  necessarily  means  that  register 
variables  are  not  implemented.  It 
could  mean  (and  does  for  High  C  and 
Wizard  C)  that  a  compiler  places  vari¬ 
ables  in  registers  automatically.  Note 
the  variety  of  ways  to  allocate  memo¬ 
ry  (memory)  and  do  long  arithmetic 
(tlong). 

Table  6,  page  43,  the  floating-point 
execution-time  table,  shows  which 
compilers  implement  which  float¬ 
ing-point  options  and  how  well  they 
do  so.  Float  1, 2,  and  5  are  run  without 
an  8087  at  the  indicated  loop  counts, 
and  float  3, 4,  6,  and  7  are  run  with  an 
8087  at  ten  times  the  indicated  loop 
count.  Also  note  that  Toolworks  C 
does  all  of  its  floating-point  in  single 
precision,  not  double.  Microsoft  C 
and  IBM  C  implement  all  the  floating¬ 
point  options  and  do  so  fairly  well. 
Lattice  C  also  implements  a  large  va¬ 
riety  of  floating-point  options  fairly 
well — especially  float  1,  the  soft¬ 
ware-only  option.  Wizard  C's  use  of 
the  8087  seems  poor  and  may  be  a 
beta-test  problem. 

Table  7,  page  44,  shows  how  the 
memory  models  affect  different 
types  of  code.  The  loop  counts  are  on 
the  line  with  the  name  of  the  bench¬ 
mark.  Pointer  is  most  strongly  affect¬ 
ed  by  the  size  and  type  of  data  point¬ 
ers,  fibtest  shows  minor  changes 
based  on  code  pointer  size,  and  sieve 
shows  virtually  no  change  at  all. 

Table  8,  page  46,  shows  the  compile 
and  link  times.  The  "average”  bench¬ 
mark  is  the  average  compile  and  link 
times  for  all  the  benchmarks  run  for 
time.  (See  Table  5  for  the  list.)  We  com¬ 
piled  docl  through  doclOOO  with,  all 
the  flavors  reported  for  doclOOO,  but 
none  of  the  compilers  reported  any 
significant  diference  between  the  fla¬ 
vors.  The  flavors  are  Min_clt,  mini¬ 
mize  compile  and  link  time;  Min_cs, 


minimize  code  size;  Min_xt,  mini¬ 
mize  execution  time;  and  No_opts,  no 
specific  options.  Here,  Lattice  C  was 
not  able  to  compile  doclOOO  for  three 
flavors  because  we  defined  those  fla¬ 
vors  to  use  in-memory  quad  files, 
which  would  not  fit  for  doclOOO.  Use 
No_opts  when  comparing  across  for 
Lattice  C.  Lattice  C's  link  times  are  at 
an  unfair  advantage  here  because  of 
the  requirement  of  using  LINK  3.0, 
which  is  faster  than  the  linker  used 
by  all  the  other  compilers  that  do  sup¬ 
ply  a  linker.  DeSmet  C  is  a  very  fast 
compiler  with  an  equally  fast  linker. 
Wizard  C  does  not  seem  very  fast  for 
small  programs,  but  large  programs 
compile  much  faster  than  average. 
Note  that  High  C,  the  slowest  for  small 
programs,  is  in  the  top  half  of  the  list 
for  doclOOO. 

The  code-size  table,  Table  9,  page 
48,  is  not  as  varied  as  last  year's.  Hot  C 
produced  the  smallest  code  sizes  uni¬ 
versally.  Note  that  some  compilers’ 

Min _ xt  sizes  are  smaller  than  their 

Min_cs  sizes.  This  is  probably  be¬ 
cause  of  a  difference  in  the  way  that 
function-entry  code  is  handled  and 
the  assumption  that  more  than  one 
function  will  be  linked.  High  C  pro¬ 
duced  large  files  all  the  time  though 
we  did  not  use  all  the  size-reducing 
mechanisms  available. 

Figure  1,  page  50,  represents  the 
execution  times  of  the  pointer  bench¬ 
mark  for  memory  models  2  and  5, 
which  are  the  most  common. 

Figure  2,  page  50,  shows  the  execu¬ 
tion  times  of  the  trig  benchmark  us¬ 
ing  the  fastest  software-only  and 
hardware-assisted  8087  options. 

Figure  3,  page  50,  shows  compiler 
speeds,  including  compile  times  for 
both  docl  and  doclOOO,  using  options 
for  each  compiler  to  minimize  com¬ 
pile  time. 

Figure  4,  page  50,  shows  the  dhry¬ 
stone  execution  times  with  and  with¬ 
out  register  variables. 

The  listings  for  the  benchmarks 
used  for  this  review  begin  on  page 
104. 
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one  mode,  which  takes  three  clocks. 
The  V30  also  has  a  better  shift  mecha¬ 
nism,  resulting  in  multiplies  and 
shifts  going  faster.  The  string  primi¬ 
tives  run  about  twice  as  fast. 

Use  of  the  V30  affects  our  numbers 
but  should  not  change  the  overall  or¬ 
dering  of  results.  Benchmarks  strong¬ 
ly  affected  are  any  that  do  multiplica¬ 
tion  (array,  tint,  tlong,  and  the 
software  floating-point  benchmarks) 
or  string  manipulations  (strings  and 
dhrystone). 

Even  though  the  V30  supports  the 
80186  instruction  set,  we  did  not  in¬ 
struct  any  of  the  compilers  to  use  any 
instruction  set  except  that  of  the 
8086/8087. 

Memory  Models 

Memory  models  are  a  continuing 
source  of  confusion  for  MS-DOS  C 
compiler  users.  Here  we  describe,  in 
our  own  terms,  various  memory 
models  and  their  implementation. 
Then  in  Table  3,  page  38,  we  indicate 
which  compilers  support  which  of 
our  memory  models. 

Intel  provided  the  definition,  in 
general  terms,  of  four  memory  mod¬ 
els — small,  compact,  medium,  and 
large.  The  distinctions  between  the 
models  were  in  the  size  of  each  of 
two  "spaces” — code  space  and  data 
space.  Either  a  space  is  less  than  64K, 
or  it  is  not.  Small  is  small  code  and 
data,  compact  is  small  code  with 
large  data,  medium  is  large  code  but 
small  data,  and  large  is  large  code  and 
large  data.  As  a  variation  of  small,  if 

both  code  and  data  fit  in  a  total  of  64K, 
the  program  is  called  8080  or  tiny 
model. 

For  code  space,  the  definition  is  ad¬ 
equate.  If  all  code  fits  in  64K  (called  a 
segment  when  used  in  8086  con¬ 
texts — 80386  protected  mode  seg¬ 
ments  are  not  limited  to  64K),  you  use 
a  small-code  model.  If  all  your  code 
could  not  fit  in  a  single  segment,  you 
need  a  large-code  model. 

For  data  space,  however,  Intel’s 
standard  is  weak  when  applied  to  C. 
In  C,  there  are  three  subspaces  in  the 
data  space,  all  of  which  must  be  ad¬ 
dressable  by  a  single  pointer  type.  If 
stack  (where  automatics  are  allocat¬ 
ed),  heap  (where  program-directed 
storage  allocation  takes  place),  and 
statics  (including  globals  and  usually 
string  constants)  all  fit  in  the  same 

Extra  Class  Aztec  C86  Data-  Data-  DeSmet  Eco-  HotC  IBM  Lattice  C  Let’s  High  Micro-  Mix  Tool-  White-  Wizard 

C  light  light  C 

C88  C  C  Prog.  C 

C  soft  C  works  smiths  C 

C  Kit 

Sys. 

C  C  C 

DEBUG 

1 

DEBUG  SRCE  1 

1  1 

1  1 

DEBUG  SYM 

2 

DIFF  1  1  1 

1 

EDITOR  3 

11  2  1 

GREP  1  1  1 

1  1 

1 

MAKE  1  1  1 

1  1 

1 

MISC  4  7  7 

5  1  14  3 

7  1  2 

OBJ  LIB  1  1 

11111 

1  2 

OBJ  UTIL  4 

12  14  4 

2  4  4 

PROFILER  1 

3 

SRCE  CNTRL  1 

2 

SRCE  LIB  1 

1  1 

1 

SRCE  LIB  R  1 

1  1 

Table  1:  Extras 


Memory 

Single 

Total 

Total 

Memory 

Model 

Code 

Static 

Object 

Data 

Program 

Model 

Number 

Size 

Size 

Size 

Size 

Size 

Name 

1 

small 

small 

small 

small 

<64K 

tiny 

2 

small 

small 

small 

small 

<128K 

small 

3 

large 

small 

small 

small 

>64K 

large  code 

4 

small 

small 

small 

large 

>64K 

fast  large  data 

5 

large 

small 

small 

large 

>128K 

fast  large 

6 

small 

large 

small 

large 

>64K 

fast  huge  data 

7 

large 

large 

small 

large 

>128K 

fast  huge 

8 

small 

small 

large 

large 

>64K 

slow  large  data 

9 

large 

small 

large 

large 

>128K 

slow  large 

10 

small 

large 

large 

large 

>64K 

slow  huge  data 

1 1  large  large 

Small  means  <64K.  Large  is  >64K. 

large 

large 

>128K 

slow  huge 

Table  2:  Memory  models  and  their  attributes 
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segment,  a  small-data  model  works 
well.  If,  however,  your  total  data  re¬ 
quirements  are  more  than  64K, 
things  get  complicated. 

First,  no  compiler  reviewed  here 
supports  a  stack  size  of  more  than 
64K.  If  you  want  to  allocate  a  large 
array  using  the  auto-storage  class,  or 
need  to  recurse  more  than  64K's 
worth  of  stack  frames,  you  are  out  of 
luck. 

Assuming  you  need  a  large-data 
model,  pointers  to  data  are  4  bytes. 
Given  4-byte  pointers,  there  is  no 
sense  in  restricting  total  heap  space 
to  anything  less  than  all  available 
memory,  and  none  of  these  compil¬ 
ers  do. 

Statics,  or  any  compile-time  allocat¬ 
ed  data,  are  a  dilferent  matter.  Static 
objects  can  be  referenced  directly  by 
name  rather  than  through  pointers 
as  heap  objects  must  be.  If  you  have 
less  than  64K  of  such  objects,  the  com¬ 
piler  can  have  a  segment  register  ( ds 
usually)  always  pointing  at  the  seg¬ 
ment  containing  static  data.  We  call 
this  the  medium-data  model.  If  you 
need  more  than  64K  of  statics,  then 
the  compiler  must  continually  load  a 
segment  register  with  the  address  of 
the  segment  containing  the  particu¬ 
lar  object  referred  to.  This  requires 
two  extra  instructions  ( mov  ay,  seg 
and  mov  ds,  ay)  for  every  direct  ac¬ 
cess  to  a  static  object,  which  is  nor¬ 
mally  a  single  instruction  (mov  ay, 
/yyzzy/).  This  is  the  large-data  model. 

So  far  we  have  described  two  code 
models  (small  and  large)  and  three 
data  models  (small,  medium,  and 
large).  With  the  addition  of  the  tiny 
model,  we  have  a  total  of  seven  mem¬ 
ory  models  so  far.  These  are  enough 
if  you  have  no  single  object  (such  as 
an  array)  larger  than  64K  in  size.  If 
any  object  is  more  than  64K  (such  as 
an  array  of  10,000  doubles,  each  8 
bytes),  additional  problems  arise.  A 
single  8086  segment  is  limited  to  64K, 
so  such  an  array  must  occupy  more 
than  one  whole  segment.  This  means 
that  the  compiler  must  allow  for  the 
adjustment  of  the  segment  part  of  an 
address  as  well  as  the  offset  part.  This 
requires  more  code  than  simple  off¬ 
set  manipulation  needs,  and  this  code 
can  only  be  very  slow. 

Adding  this  variation  to  medium- 
and  large-data  models  for  both  small 
and  large  code  brings  to  11  the  total 
number  of  memory  models.  For  a 


concise  description  of  the  attributes 
of  each  of  our  11  models,  refer  to  Ta¬ 
ble  2,  page  36.  To  see  which  memory 
models  a  compiler  supports,  look  to 
Table  3.  Table  3  lists,  by  compiler  and 
our  memory-model  number,  the 
compiler  options  needed  to  create 
the  model,  the  compiler’s  name  for 
the  model,  and  which  is  the  default. 

Lack  of  support  for  a  particular 
memory  model  may  not  be  fatal  if 
you  have  a  program  needing  that 
model.  All  even-numbered  models 
(models  with  small  code)  can  be  com¬ 


piled  by  a  compiler  supporting  the 
number  plus  1  (the  same  model  with 
large  code).  Models  4  through  7  can 
be  compiled  by  models  8  through  11, 
respectively,  if  you  don’t  mind  the 
extra  overhead  for  20-bit  pointer 
arithmetic  everywhere.  Models  6,  7, 
10,  and  11  can  be  used  in  place  of 
models  4,  5,  8,  and  9,  respectively, 
with  a  small  penalty  for  accessing 
global  data  items.  The  Wizard  com¬ 
piler,  for  example,  can  compile  and 
run  a  program  needing  less  than  64K 
of  code  and  more  than  64K  of  statics, 


Dr.  Dobb’s  Journal,  August  1986 


37 

551 


C  COMPILERS 


but  it  must  use  a  model  allowing 
more  than  64K  of  code. 

To  increase  the  performance  of  a 
program  that  has  one  or  two  large  ob¬ 
jects,  with  everything  else  able  to  fit 


in  a  smaller  data  model,  some  com¬ 
piler  vendors  implement  what  is 
known  as  mixed-model  program¬ 
ming.  With  mixed-model  program¬ 
ming,  a  small-model  program  can  de¬ 
clare  a  pointer  to  be  a  far  pointer — 
that  is,  a  4-byte  pointer.  IBM,  Micro¬ 
soft,  Whitesmiths,  and  Wizard  all  im¬ 


plement  some  form  of  mixed-memo¬ 
ry-model  support.  Whitesmiths’ 
compiler  can  never  automatically 
deal  with  objects  larger  than  64K. 
Wizard’s  can  but  on  a  source-file-by¬ 
source-file  basis — that  is,  all  far  point¬ 
ers  in  a  module  are  manipulated  us¬ 
ing  the  same  rules  about  the 


# 

Aztec  C 

C86 

Datalight  C 

1  -o 

tiny 

—me  tiny 

2 

small 

small 

—ms  small 

3  +lc 

large  code 

4  -4-Id 

large  data 

5  +1 

large 

-b 

large 

# 

Datalight  Kit 

DeSmet  C 

Eco-C88 

1  -me 

com 

2  -ms 

s 

small 

small 

3  -mp 

p 

4  -md 

D 

5  —ml 

L 

-b 

large 

# 

1 

2 

High  C 

Hot  C 

IBM  C 

small 

small 

—AS  small 

3 

medium 

—AM  medium 

4 

compact 

5 

big 

-b 

large 

6 

7 

large 

— AL  large 

8 

9 

10 

11 

—  AH  huge 

# 

1 

2  -mS 

Lattice  C 

Microsoft  C 

C  Programming  System 

S 

-AS 

small 

— vsmall  small 

3  -mP 

P 

-AM 

medium 

4  —  mD 

-s  D 

5  — mL 

6 

—  s  L 

-AC 

compact 

— vlarge  large 

7 

8  —  mD 

D 

-AL 

large 

9  — mL 
10 

11 

L 

-AH 

huge 

# 

1 

2 

Lets’  C 

Mix  C 

Toolworks  C 

small 

small 

#  Whitesmiths  C 

Wizard  C 

Our  Model  Name 

1  —  dcom  8080 

— mtf 

tiny  16 

tiny 

2  —  dmods  s 

— msf 

small  16 

small 

3  -dmodp  p 

— mmf 

medium  16 

large  code 

4  —  dmodd  d 

— mef 

compact  1 6 

fast  large  data 

5  —  dmodf  f 

— mlf 

large  1 6 

fast  large 

6 

fast  huge  data 

7 

—  mhf 

huge  16 

fast  huge 

8 

—  me 

compact  20 

slow  large  data 

9 

—  ml 

large  20 

slow  large 

10 

slow  huge  data 

11 

—  mh 

huge  20 

slow  huge 

Table  3:  Support  for  memory  models 
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(continued  from  page  38) 


maximum  size  of  a  single  object.  IBM 
and  Microsoft  offer  two  different 
kinds  of  far  pointers— far  and  huge. 
Far  implies  less  than  64K  per  object, 
and  huge  implies  more  than  64K. 

To  test  memory-model  perfor¬ 
mance,  we  ran  array,  pointer,  sieve, 
fibtest,  and  memory  under  all  the 
available  memory  models.  We  list  the 
results  produced  in  these  tests  in  Ta¬ 
ble  5,  page  42. 


Floating-Point  Options 

Almost  as  complicated  as  memory 
models,  floating-point  options  are  an¬ 
other  point  of  distinction  between 
various  compiler  vendors.  Programs 
that  use  floating  point  can  be  created 
in  five  different  ways. 

The  fastest,  smallest  option  is  to 
have  in-line  8087  instructions  with¬ 
out  the  presence  of  an  emulation  li¬ 
brary  to  handle  the  machine  without 
an  8087. 

Option  2  is  to  put  8087  instructions 
in-line  and  use  an  emulation  library 


in  case  the  machine  doesn’t  have  a 
real  8087.  In  reality,  this  option  does 
not  actually  put  8087  instructions  in¬ 
line.  Where  8087  instructions  belong, 
software  interrupts  are  placed  in¬ 
stead.  When  the  interrupt  occurs,  if 
an  8087  is  present,  the  interrupt  in¬ 
struction  is  replaced  by  the  actual  in¬ 
struction  and  executed. 

Next,  where  floating-point  opera¬ 
tions  are  needed,  calls  are  made  to  a 
library.  The  kind  of  library  linked  in 
determines  which  of  the  last  three 
floating-point  options  is  in  use. 

The  library  may  require  the  pres¬ 
ence  of  an  8087  to  execute.  Or  it  may 
be  a  "sensing”  library,  testing  a  word 
set  at  start-up  indicating  the  presence 
or  absence  of  an  8087  and  branching 
to  or  around  8087  instructions.  Final¬ 
ly,  it  could  be  a  pure  software  library, 
which  would  probably  be  faster  than 
an  emulation  library  on  a  non-8087- 
equipped  machine  but  slower  than  a 
library  using  an  8087. 

We  ran  dfuncret,  prtf,  tfloat, 
tdouble,  and  trig  using  all  the  sup¬ 
ported  8087  modes  for  each  compil¬ 
er.  Results  from  these  benchmarks 
are  shown  in  Table  6,  page  43. 

Compiler-Specific  Comments 

The  raw  data  are  only  part  of  the  sto¬ 
ry.  In  the  following,  we  attempt  to 
summarize  the  important  remaining 
facts  and  observations  about  each 
compiler. 

C86 

Computer  Innovations  is  one  of  the 
old  names  in  MS-DOS  C  compilers.  It 
has  been  marketing  its  C86  C  compil¬ 
er  almost  as  long  as  has  Lattice.  The 
compiler  package  does  not  seem 
much  changed  from  last  year,  and 
we  are  told  that  a  major  enhance¬ 
ment  is  due  soon. 

The  compiler  provides  for  small/ 
small-  and  large/large-memory-mod- 
el  programming.  (A  large-code/ 
small-data  model  was  in  beta  test  but 
was  not  reviewed.)  It  provides  8087 
support  via  an  option  to  generate  in¬ 
line  8087  code  and  a  separate  library 
(good),  but  there  is  no  way  to  build  a 
program  that  will  use  an  8087  but 
also  run  without  one  (bad).  There  is 
an  option  to  generate  code  for  an 
80186  or  80286  processor.  Full  source 
code  for  the  libraries  is  provided  in 
archive  form  (along  with  an  archive 
maintenance  program).  There  is 


Dr.  Dobb's  Journal,  August  1986 


40 

553 


even  an  access  library  for  TopView 
included  in  the  package — something 
no  other  vendor  provides  (if  anybody 
cares). 

Installing  this  compiler  is  a  pain, 
mainly  because  all  the  distribution 
files  come  in  a  compressed  format  (all 
four  disks’  worth).  You  have  to  un¬ 
squeeze  everything  before  you  do 
anything  else,  an  unpleasant  opera¬ 
tion  on  a  dual-floppy  machine.  The 
unsqueeze  program  did  not  detect  a 
full  target  disk  at  one  point.  Comput¬ 
er  Innovations  supplies  a  library  that 
will  work  with  all  DOS  versions,  in¬ 
cluding  1.0,  and  a  separate  (and  pref¬ 
erable)  library  that  requires  DOS  2.0 
or  later.  We  used  that  one,  as  will 
most  users. 

Computer  Innovations  is  the  only 
vendor  besides  Software  Toolworks 
that  does  not  provide  a  driver  pro¬ 
gram  at  least  for  the  compile/assem¬ 
ble  process.  Each  pass  of  the  compil¬ 
er  (there  are  four)  must  be  invoked 
separately  from  the  command  line  or 
from  a  batch  file.  All  options  are  giv¬ 
en  to  the  first  pass.  There  is  an  unusu¬ 
al  optimization  option  that  lets  you 
specify  how  many  hundreds  of  bytes 
of  code  space  per  switch  statement 
can  be  spent  building  a  jump  table, 
compared  to  the  space  a  linear 
search  would  take.  We  used  -j5  as  a 
reasonable  trade-off  for  the  execu¬ 
tion-time  benchmarks. 

The  documentation  consists  of 
about  330  8.5  X  11-inch  pages  in  a  rea¬ 
sonable  binder  (larger  than  IBM  size). 
It  includes  an  extremely  detailed  ta¬ 
ble  of  contents  that  doubles  as  a  quick 
reference  for  the  library,  and  it  also 
has  a  lengthy  index  and  a  glossary 
section.  The  library  documentation  is 
the  best  part  of  the  manual.  It  is  clear 
and  well  organized,  with  one  func¬ 
tion  per  page  and  in  alphabetical  or¬ 
der,  and  includes  a  fair  number  of  ex¬ 
amples.  The  rest  of  the  manual  seems 
to  be  a  hodgepodge  of  technical  in¬ 
formation  presented  in  bits  and 
snatches,  with  poor  overall  organiza¬ 
tion.  There  is  no  language  refer¬ 
ence — you  are  directed  to  K  &  R  for 
that.  Worse  yet,  there  is  not  enough 
information  about  implementation- 
specific  details  such  as  whether  chars 
signs  extend  when  promoted  to  infs. 
One  page  of  information  appears  un¬ 
der  the  heading  "Language  informa¬ 
tion,"  and  a  few  other  tidbits  are  scat¬ 
tered  about,  and  that's  it.  Our 


impression  is  that  this  package  is 
aimed  at  the  hobbyist/hacker 
community. 

According  to  the  read. me  file,  sev¬ 
eral  bugs  have  been  fixed  in  the  last 
few  releases  of  the  compiler.  There 


are  still  a  couple  left,  though.  For  in¬ 
stance,  the  compiler  will  be  fooled  by 
what  looks  like  an  opening  comment 
delimiter  inside  a  quoted  string  un¬ 
less  it  is  escaped.  In  other  words, 
printff  /*-”);  gives  a  compiler  er- 


Without  With 

Registers  Registers 


Compiler  Name 

Time 

Rating 

Time 

Rating 

Flags 

Aztec  C 

53.7 

931 

50.8 

984 

+  a  +F 

C86 

91.9 

544 

91.9 

544 

-j5 

Datalight  C 

44.7 

1118 

44.9 

1113 

none 

Datalight  Kit 

44.8 

1116 

44.7 

1118 

none 

DeSmet 

61.3 

813 

61.3 

813 

none 

Eco— C88 

60.3 

829 

60.3 

829 

none 

High  C 

54.0 

925 

54.0 

925 

none 

Hot  C 

62.7 

797 

57.0 

877 

none 

IBM  C 

46.7 

1070 

44.6 

1121 

—  Oat  —  Gs 

Lattice  C 

62.7 

797 

62.6 

798 

—ms  — cw 

Mix  C 

607.4 

82 

607.4 

82 

none 

Microsoft  C 

46.6 

1072 

44.4 

1126 

—  Oat  -Gs 

C  Prog.  System 

85.8 

582 

80.6 

620 

none 

Let’s  C 

85.9 

582 

80.6 

620 

none 

Toolworks  C 

CNC 

CNC 

typedef 

Whitesmiths  C 

97.1 

514 

93.2 

536 

none 

Wizard  C 

63.8 

783 

63.6 

786 

—a  — G  — o— z 

Table  4:  Dhrystone  results 
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ror,  but  printff  \/*  J;  works 
fine.  The  documentation  warns  you, 
though.  Also,  we  got  a  meaningless 
error  message  when  we  attempted  a 
static  function  declaration  (not  defi¬ 
nition).  The  declaration  static  int 
funcOf  );  produced  the  error  message 
"get  size  error  for  103.” 

DeSmet  C 

C  Ware  Corp.  has  been  around  for 
quite  a  while  now,  and  its  DeSmet  C 
development  package  has  attracted 
many  devoted  fans  over  the  years. 
This  is  because  it  has  always  provid¬ 
ed  a  fairly  complete  implementation 
of  C  along  with  a  source-level  debug¬ 
ger  and  several  other  goodies  for  an 
affordable  price.  It  includes  a  text 
editor  (becoming  more  common)  as 
well  as  an  execution  profiler 
(uncommon). 


The  latest  upgrade  to  the  DeSmet  C 
compiler  adds  support  for  large/ 
large-memory-model  programming 
and  the  8087  chip.  We  tested  a  beta 
version  of  this  release,  but  we  did  not 
receive  the  corresponding  upgraded 
documentation. 

DeSmet  C  uses  its  own  object  for¬ 
mat;  Microsoft  object-format  support 
is  available  as  an  extra-cost  option. 
Overlays  are  supported  in  the  small- 
memory  model.  The  compiler  sup¬ 
ports  enum  and  structure  assignment 
and  pass/return. 

The  large-model  version  of  the 
compiler  comes  on  three  disks.  It  has 
no  installation  guide  except  for  a  dis¬ 
cussion  of  CONFIG.SYS  and  the  use  of 
RAM  disks  (a  RAM-disk  driver  comes 
with  the  package).  There  is  a  lot  of 
extra  stuff  on  the  distribution  disks, 
so  the  compiler,  assembler,  linker, 
and  libraries  can  fit  easily  on  one 
disk.  It  has  support  for  an  8087  on  a 
take-it-or-leave-it  basis,  and  it  has  a 


software-only  library  and  an  8087- 
only  library.  The  installation  guide 
tells  you  to  pick  the  one  you  want 
(both  contain  all  the  other  functions 
as  well  as  the  floating-point  func¬ 
tions),  name  it  cstdio.s,  and  delete  the 
other  one.  You  can  tell  the  linker 
(bind)  to  search  a  specific  library  by 
name,  but  it  automatically  scans 
cstdio.s  in  any  case. 

The  manual  comes  in  an  IBM-size, 
D-ring  binder  with  pages  somewhat 
wider  than  usual.  The  writing  style  is 
terse,  and  it  is  sometimes  difficult  to 
find  the  information  you  are  looking 
for.  It  has  no  index  but  has  a  reason¬ 
able  table  of  contents.  Pages  are  num¬ 
bered  by  section,  making  it  easier  to 
insert  updates  but  harder  to  flip  to  a 
desired  page. 

The  documentation  has  no  lan¬ 
guage  reference,  but  it  has  a  brief 
summary  of  differences  from  the  K 
&  R  standard.  If  you  buy  this  pack¬ 
age,  you  will  need  some  other  book  to 


Benchmark 

LC 

Aztec 

C 

C86 

Data- 

light 

C 

Data- 

light 

Kit 

DeSmet 

C 

Eco- 

C88 

Hot  C 

IBM 

C 

Lattice 

C 

c 

Prog. 

Sys. 

Let’s 

C 

High 

C 

Micro¬ 

soft 

C 

Mix 

C 

Tool¬ 

works 

C 

White¬ 

smiths 

C 

Wizard 

C 

array 

1500 

37.2 

78.9 

53.1 

53.1 

78.2 

78.0 

61.8 

37.9 

54.9 

82.7 

82.6 

35.1 

37.9 

121.0 

142.0 

71.0 

59.3 

autotst 

150 

45.2 

47.8 

47.8 

47.7 

47.8 

47.7 

55.7 

45.2 

47.7 

47.7 

47.7 

36.9 

45.2 

83.5 

66.6 

47.0 

33.3 

cpyblk 

15 

21.0 

40.5 

23.0 

23.7 

2.9 

— 

25.3 

5.7 

41.8 

19.4 

19.7 

8.3 

5.2 

28.2 

87.4 

12.9 

27.2 

cpychr 

15 

15.4 

15.3 

13.0 

13.7 

51.9 

26.3 

22.8 

17.7 

37.4 

22.6 

23.0 

76.6 

17.3 

46.7 

54.6 

35.9 

18.9 

diskio 

350 

9.0 

7.8 

24.1 

24.0 

7.2 

8.4 

6.2 

9.6 

8.6 

7.5 

7.5 

9.0 

9.6 

1.4 

8.8 

18.3 

8.2 

fibtest 

18 

34.1 

33.7 

30.3 

30.3 

31.9 

32.1 

42.9 

37.0 

34.3 

39.3 

39.4 

38.3 

37.1 

178.9 

38.3 

40.2 

35.2 

fillscr 

12 

32.1 

16.7 

28.8 

28.8 

14.7 

19.3 

30.1 

13.0 

32.3 

13.8 

13.7 

13.0 

12.9 

45.1 

35.4 

13.6 

29.1 

funcovO 

10000 

47.3 

47.6 

29.8 

29.9 

46.4 

29.9 

59.9 

45.9 

46.5 

72.5 

72.6 

49.4 

45.8 

477.6 

34.3 

58.3 

31.0 

funcovl 

10000 

71.4 

71.7 

65.9 

65.9 

68.6 

68.6 

94.4 

68.5 

68.2 

95.3 

95.2 

65.9 

68.5 

499.8 

46.7 

81.4 

54.1 

funcov2 

10000 

85.2 

85.3 

81.9 

81.8 

83.2 

82.1 

108.6 

82.0 

80.9 

109.6 

109.7 

79.5 

82.1 

521.5 

60.9 

100.8 

62.0 

funcov3 

10000 

98.4 

99.3 

96.5 

96.4 

99.6 

97.1 

128.0 

96.8 

99.8 

124.6 

124.6 

95.4 

96.7 

544.0 

81.0 

109.8 

79.1 

looptst 

500 

36.7 

38.8 

38.9 

39.0 

39.8 

39.0 

45.7 

36.7 

41.0 

38.9 

38.9 

17.5 

25.8 

60.8 

43.6 

38.9 

15.4 

memory 

500 

45.3 

188.9 

56.7 

56.7 

186.4 

170.4 

59.6 

32.0 

295.6 

1211.0 

1211.0 

384.5 

31.4 

259.6 

401.7 

109.4 

77.6 

optimize 

100 

17.7 

20.1 

15.5 

15.5 

21.7 

20.9 

24.7 

14.4 

7.8 

20.4 

20.5 

9.1 

10.8 

27.9 

20.3 

20.7 

9.3 

pointer 

1500 

31.0 

40.7 

38.7 

38.7 

39.5 

38.7 

38.8 

31.0 

38.7 

43.5 

43.6 

33.0 

30.9 

93.0 

71.1 

42.4 

30.7 

reg2test 

150 

34.8 

47.7 

47.7 

47.7 

47.7 

47.7 

38.6 

33.3 

47.7 

35.9 

35.9 

38.1 

33.3 

84.8 

66.5 

36.5 

33.3 

regtest 

150 

33.6 

47.8 

47.7 

47.8 

47.8 

47.7 

38.5 

33.3 

47.8 

35.9 

35.9 

36.8 

33.3 

84.8 

66.5 

30.0 

33.4 

rsieve 

140 

36.8 

67.7 

60.1 

60.0 

63.2 

64.1 

37.4 

34.6 

59.8 

36.7 

36.7 

37.0 

34.6 

110.1 

68.2 

37.4 

34.3 

scroll 

12 

48.0 

32.5 

44.7 

44.9 

30.6 

35.2 

46.1 

29.0 

47.9 

29.7 

30.0 

29.3 

29.2 

45.3 

51.1 

29.8 

44.6 

sieve 

140 

61.2 

67.7 

60.0 

60.0 

63.2 

64.1 

71.3 

60.2 

59.9 

63.2 

63.2 

37.1 

60.1 

96.2 

86.8 

68.1 

44.4 

stattst 

150 

49.6 

64.1 

50.6 

50.7 

61.9 

53.3 

49.6 

49.6 

53.3 

53.3 

53.3 

53.1 

49.6 

100.6 

82.3 

52.6 

46.4 

strings 

1000 

5.8 

10.9 

3.8 

3.8 

9.2 

13.8 

7.7 

4.1 

10.2 

15.7 

15.7 

4.2 

3.9 

152.1 

36.1 

15.1 

8.9 

switch  1 

1000 

8.6 

14.0 

5.7 

5.8 

10.0 

35.5 

8.5 

7.1 

6.2 

5.9 

6.0 

5.5 

7.1 

85.6 

- 

13.8 

6.3 

switch2 

1000 

8.5 

8.8 

5.6 

5.7 

8.0 

8.3 

7.6 

3.9 

6.1 

5.8 

5.8 

5.2 

3.8 

18.6 

- 

13.5 

4.8 

switch3 

1000 

17.1 

11.9 

11.5 

11.6 

44.8 

12.0 

11.3 

3.7 

31.7 

27.0 

27.0 

8.1 

3.7 

30.6 

- 

28.7 

24.8 

tint 

1500 

15.2 

16.8 

14.6 

14.7 

16.3 

16.1 

18.6 

14.5 

16.3 

15.1 

15.1 

14.4 

14.5 

23.2 

27.9 

15.1 

14.0 

tlong 

1000 

75.8 

129.6 

49.6 

49.5 

100.6 

158.4 

66.5 

52.9 

58.0 

114.6 

114.5 

55.8 

50.3 

147.7 

167.2 

54.6 

82.5 

Winners 

0 

0 

5 

4 

1 

1 

1 

5 

1 

0 

0 

5 

6 

0 

2 

1 

9 

10% 

6 

0 

3 

4 

2 

1 

2 

8 

0 

6 

6 

5 

7 

0 

1 

5 

2 

Total 

6 

0 

8 

8 

3 

2 

3 

13 

1 

6 

6 

10 

13 

0 

3 

6 

11 

Boldfaced  entries  represent  the  top  scores  for  each  benchmark.  Italicized  entries  came  within  10%  of  the  top  score.  The  three  rows  at  the  bottom  summarize  the  number  of  winning  and 
runner-up  scores  for  each  compiler. 
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go  with  it.  The  library  reference  is 
organized  by  category,  with  the  cate¬ 
gory  name  in  LARGE  type  at  the  top 
of  each  page.  An  alphabetical  list  of 
functions  at  the  front  tells  you  what 
category  name  to  look  under  for  the 
function  definition.  Several  functions 
are  defined  on  each  page,  a  la  Unix, 
with  a  usage  summary  that  takes 
some  getting  used  to  even  if  you  like 
Unix  documentation. 


Datalight  C 

Datalight  distributes  two  versions  of 
its  C  compiler.  The  personal  version, 
called  the  Datalight  C  compiler,  sup¬ 
ports  only  the  small/small-memory 
model  and  does  not  include  source 
code  for  the  library.  Support  for  an 
8087  is  provided,  via  a  sensing  li¬ 
brary.  It  has  been  completely  rewrit¬ 
ten  since  last  year. 

The  entire  package  is  distributed 


on  one  sealed  disk,  and  the  license 
agreement  is  visible  on  the  outside  of 
the  package.  The  agreement  is  short 
and  reasonable,  requiring  only  that 
the  package  not  be  used  by  more 
than  one  person  at  a  time.  We  think 
that  means  you  can  take  it  with  you 
to  work,  and  install  it  on  your  new 
computer,  without  violating  your 
agreement.  This  type  of  agreement  is 
starting  to  show  up  more  often,  re- 


Benchmark 

LC 

Aztec 

C86 

Data- 

Data- 

DeSmet 

Eco- 

Hot  C 

IBM 

Lattice 

C 

Let’s 

High 

Micro- 

Mix 

Tool- 

White- 

Wizard 

C 

light 

light 

C 

C88 

C 

C 

Prog. 

C 

C 

soft 

C 

works 

smiths 

C 

C 

Kit 

Sys. 

C 

C 

C 

atox 

100 

Float_1 

31.3 

22.6 

— 

— 

17.1 

— 

— 

3.5 

55.4 

19.8 

19.8 

— 

3.3 

- 

12.8 

12.3 

- 

Float_2 

32.1 

— 

130.9 

130.9 

— 

6.0 

1590.0 

4.1 

55.3 

— 

- 

9.8 

4.2 

- 

— 

— 

7.9 

Float_3 

45.0 

— 

128.6 

128.6 

— 

— 

83.7 

21.4 

565.4 

— 

— 

40.6 

21.3 

— 

— 

— 

49.5 

Float_4 

44.1 

— 

— 

— 

21.4 

— 

83.7 

21.5 

565.4 

— 

— 

— 

21.3 

— 

121.6 

— 

— 

Float_5 

— 

— 

— 

— 

— 

— 

— 

4.2 

— 

— 

— 

— 

4.2 

— 

— 

- 

— 

Float_6 

— 

- 

— 

— 

— 

— 

— 

21.5 

565.7 

— 

— 

— 

21.3 

— 

— 

— 

— 

Float_7 

— 

35.6 

— 

— 

— 

— 

— 

21.4 

565.7 

68.9 

— 

33.9 

21.4 

— 

- 

33.2 

49.6 

dfuncret 

250 

Float_1 

56.5 

51.1 

— 

— 

54.7 

— 

— 

24.3 

6.2 

12.2 

12.2 

— 

24.3 

48.4 

5.8 

14.2 

— 

Float_2 

62.2 

— 

6.4 

6.4 

— 

9.5 

325.7 

85.4 

6.3 

— 

— 

11.3 

86.4 

— 

— 

— 

19.4 

Float_3 

367.6 

— 

63.9 

63.9 

— 

— 

98.7 

15.9 

62.8 

— 

— 

113.6 

158.6 

— 

— 

— 

193.4 

Float_4 

298.0 

— 

— 

— 

234.8 

— 

98.8 

15.8 

62.7 

_ 

— 

— 

158.7 

— 

58.1 

— 

— 

Float_5 

— 

— 

— 

— 

— 

— 

— 

82.9 

— 

— 

— 

— 

83.7 

— 

— 

— 

— 

Float_6 

_ 

— 

— 

— 

— 

— 

— 

125.3 

236.1 

— 

_ 

— 

125.3 

— 

— 

— 

— 

Float_7 

— 

243.8 

— 

— 

— 

— 

_ 

125.2 

236.1 

116.1 

— 

113.6 

125.2 

— 

— 

129.5 

147.1 

prtf 

12 

Float_1 

49.3 

46.3 

— 

- 

34.5 

— 

— 

29.6 

56.4 

32.3 

32.5 

— 

29.8 

56.6 

52.2 

37.1 

— 

Float_2 

49.5 

— 

— 

— 

— 

35.2 

85.1 

29.7 

56.1 

— 

— 

35.7 

29.9 

— 

_ 

— 

49.5 

Float_3 

477.5 

— 

— 

— 

— 

— 

472.1 

292.5 

564.9 

— 

_ 

333.2 

295.5 

— 

_ 

— 

481.0 

Float_4 

477.8 

— 

— 

— 

321.3 

— 

472.0 

292.8 

565.5 

— 

— 

— 

295.4 

— 

518.9 

— 

— 

Float_5 

- 

— 

— 

— 

— 

— 

— 

29.8 

— 

— 

— 

— 

29.8 

— 

— 

— 

— 

Float_6 

— 

— 

— 

— 

— 

— 

— 

292.4 

564.4 

— 

— 

— 

295.4 

— 

— 

— 

— 

Float_7 

— 

351.9 

— 

— 

— 

— 

— 

292.4 

565.6 

308.1 

— 

326.8 

295.6 

— 

— 

313.8 

481.5 

tdouble 

500 

Float_1 

41.8 

86.6 

— 

— 

39.4 

— 

— 

21.3 

32.7 

17.2 

17.2 

— 

21.3 

98.8 

8.9 

118.0 

— 

Float_2 

43.7 

— 

36.8 

36.8 

— 

5.8 

396.2 

49.6 

33.4 

— 

— 

56.4 

50.1 

— 

— 

— 

31.6 

Float_3 

70.6 

— 

47.2 

47.2 

— 

— 

27.5 

35.3 

53.6 

— 

— 

209.6 

35.7 

— 

— 

— 

75.3 

Float_4 

60.5 

— 

— 

— 

50.8 

— 

27.5 

35.2 

53.7 

— 

— 

— 

35.7 

— 

47.4 

— 

_ 

Float_5 

— 

— 

— 

— 

— 

— 

— 

50.1 

— 

— 

— 

— 

50.6 

— 

-- 

Float_6 

— 

— 

— 

— 

— 

— 

— 

27.2 

27.8 

— 

— 

— 

27.2 

— 

_ 

— 

— 

Float_7 

— 

29.1 

— 

— 

— 

— 

— 

27.2 

27.8 

26.8 

— 

26.9 

27.2 

_ 

— 

29.1 

29.1 

tfloat 

500 

Float_1 

41.7 

90.8 

— 

— 

57.2 

— 

— 

11.9 

46.2 

19.2 

19.1 

— 

12.0 

100.4 

8.9 

117.6 

— 

Float_2 

43.5 

- 

64.3 

64.3 

— 

11.2 

337.7 

44.8 

46.7 

— 

— 

46.2 

45.1 

— 

— 

38.4 

Float_3 

67.1 

— 

114.3 

114.3 

— 

— 

24.8 

34.9 

114.0 

— 

_ 

212.8 

34.6 

— 

— 

— 

136.3 

Float_4 

56.8 

- 

— 

— 

48.1 

— 

— 

34.9 

114.0 

— 

— 

— 

34.6 

— 

47.4 

— 

— 

Float_5 

— 

— 

— 

— 

— 

— 

— 

45.1 

— 

— 

— 

— 

45.5 

— 

— 

— 

— 

Float_6 

— 

- 

— 

— 

— 

— 

— 

24.1 

30.5 

— 

— 

— 

24.1 

— 

— 

— 

— 

Float_7 

— 

26.4 

— 

— 

— 

— 

— 

24.1 

28.0 

23.8 

— 

24.2 

24.1 

— 

— 

26.9 

150.4 

trig 

100 

Float_1 

44.7 

72.1 

- 

— 

47.5 

— 

- 

26.7 

10.4 

24.5 

24.5 

— 

26.7 

148.8 

17.4 

104.6 

F!oat_2 

46.2 

- 

53.4 

53.4 

— 

7.9 

650.5 

41.5 

42.6 

— 

— 

47.2 

42.2 

— 

— 

42.8 

Float_3 

98.5 

— 

98.3 

98.3 

— 

— 

56.7 

16.4 

15.8 

— 

— 

17.9 

16.4 

— 

_ 

— 

154.1 

Float_4 

81.8 

- 

— 

— 

63.1 

— 

— 

16.4 

15.8 

— 

— 

— 

16.4 

92.7 

— 

Float_5 

- 

— 

— 

— 

— 

_ 

— 

41.5 

— 

— 

— 

— 

42.2 

— 

— 

— 

— 

Float_6 

- 

— 

— 

— 

— 

— 

— 

16.0 

17.0 

— 

— 

— 

15.9 

— 

— 

— 

— 

Float_7 

13.8 

15.9 

16.9 

9.7 

11.3 

15.9 

25.6 

154.1 

Table  G:  Floating-point  EXE  time 
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placing  the  ridiculously  restrictive  li¬ 
censes  people  are  used  to  ignoring. 
This  trend  should  be  encouraged. 

Batch  files  are  provided  to  auto¬ 
mate  hard-disk  and  floppy-disk  in¬ 
stallation,  but  they  are  hardly  neces¬ 
sary  with  such  a  small  package.  The 
documentation  includes  sample  ses¬ 
sions  and  describes  all  environment 
variables  used.  Source  code  is  includ¬ 
ed  for  a  few  Unix-type  utility  pro¬ 


grams — most  notably  fgrep  and 
diff — and  a  simple  make  utility  is  also 
included  (executable  only). 

Datalight  gives  you  the  same  man¬ 
ual  regardless  of  which  version  of 
[  the  compiler  you  buy.  Thus,  if  you 
buy  the  personal  version,  you  should 
be  prepared  to  ignore  references 
throughout  the  manual  to  features 
you  don’t  actually  have.  The  quantity 
of  documentation  is  below  average 
(210  IBM-size  pages),  but  the  quality  is 
good.  The  material  is  readable  and 
covers  the  compiler’s  features  well 


for  the  most  part.  The  manual  has 
sections  describing  the  compiler’s  op¬ 
timization  strategies  and  aliasing  as¬ 
sumptions  (so  you  can  write  faster 
code),  and  implementation-defined 
behavior  is  documented.  It  has  a  table 
of  contents  and  an  index. 

A  bug  prevented  compilation  of 
the  prtf  benchmark.  The  version  of 
the  compiler  we  received  cannot 
compile  a  code  fragment  such  as: 

float  f; 
foo(  -f,  f,  -f ); 


Benchmark  LC 

Aztec 

C 

C86 

Data¬ 

light 

C 

Data¬ 

light 

Kit 

DeSmet 

C 

Eco- 

C88 

Hot  C 

IBM 

C 

Lattice 

C 

C 

Prog. 

Sys. 

Let’s 

C 

High 

C 

Micro¬ 

soft 

C 

Mix 

C 

Tool¬ 

works 

C 

White¬ 

smiths 

C 

Wizard 

C 

array  1 500 

MemMdl_2 

37.2 

78.9 

53.1 

53.1 

78.2 

78.0 

61.8 

37.9 

54.9 

82.7 

82.6 

35.1 

37.9 

121.0 

142.0 

71.0 

59.3 

MemMdl_3 

37.3 

- 

- 

53.1 

— 

_ 

— 

38.0 

54.8 

— 

_ 

49.0 

38.0 

— 

67.4 

59.3 

MemMdl_4 

40.6 

— 

- 

60.6 

— 

— 

— 

_ 

54.8 

_ 

— 

49.0 

— 

— 

_ 

82.6 

59.4 

MemMdl_5 

40.6 

103.2 

- 

60.6 

— 

— 

— 

— 

54.8 

102.2 

— 

49.0 

— 

— 

_ 

87.6 

59.3 

MemMdl_7 

- 

- 

— 

— 

— 

— 

— 

37.9 

— 

— 

_ 

49.0 

37.9 

— 

— 

— 

59.4 

MemMdl_8 

- 

— 

— 

— 

- 

— 

— 

- 

54.8 

— 

_ 

— 

— 

— 

— 

— 

251.0 

MemMdl_9 

- 

— 

— 

— 

— 

— 

— 

— 

54.8 

— 

— 

— 

— 

_ 

_ 

— 

277.8 

MemMdl-1 1 

_ 

— 

— 

— 

- 

— 

— 

37.9 

— 

— 

— 

— 

38.0 

— 

— 

— 

278.9 

fibtest  1 8 

MemMdl_2 

34.1 

33.7 

30.3 

30.3 

31.9 

32.1 

42.9 

37.0 

34.3 

39.3 

39.4 

38.3 

37.1 

178.9 

38.3 

40.2 

35.2 

MemMdl_3 

37.2 

- 

_ 

33.5 

— 

— 

— 

40.2 

37.9 

— 

— 

39.3 

40.2 

— 

— 

39.3 

39.4 

MemMdl_4 

34.1 

- 

— 

30.8 

— 

— 

— 

— 

34.4 

— 

— 

35.3 

— 

— 

— 

40.2 

35.3 

MemMdl_5 

37.2 

36.4 

— 

33.8 

— 

— 

— 

— 

37.9 

43.0 

— 

39.3 

— 

— 

_ 

39.3 

39.4 

MemMdl_7 

- 

- 

- 

- 

_ 

— 

— 

40.1 

— 

— 

— 

45.4 

40.2 

— 

— 

_ 

45.2 

MemMdl._8 

- 

— 

— 

— 

— 

— 

— 

— 

34.4 

— 

— 

— 

— 

— 

— 

— 

35.2 

MemMdl_9 

— 

— 

— 

— 

— 

— 

— 

— 

38.0 

— 

— 

— 

_ 

— 

— 

— 

39.4 

MemMdL.1 1 

— 

— 

— 

— 

— 

— 

— 

40.2 

— 

— 

— 

— 

40.1 

_ 

— 

— 

45.2 

memory  500 

MemMdl_2 

45.3 

188.9 

56.7 

56.7 

186.4 

170.4 

59.6 

32.0 

295.6 

1211.0 

1211.0 

384.5 

31.4 

259.6 

401.7 

109.4 

77.6 

MemMdl_3 

46.8 

- 

— 

57.3 

— 

- 

- 

32.8 

306.9 

— 

— 

408.9 

32.6 

— 

— 

103.5 

79.8 

MemMdl_4 

122.3 

- 

— 

138.5 

_ 

— 

— 

— 

1011.3 

_ 

— 

419.7 

— 

— 

— 

_ 

1028.3 

MemMdl_5 

125.3 

1288.9 

— 

145.0 

— 

_ 

— 

- 

1064.3 

2108.1 

— 

434.3 

— 

— 

— 

— 

1050.5 

MemMdl_7 

_ 

- 

— 

— 

- 

— 

— 

37.2 

— 

— 

— 

445.0 

37.7 

_ 

— 

— 

322.0 

MemMdl_8 

_ 

- 

— 

— 

— 

— 

— 

— 

1051.4 

— 

— 

— 

— 

— 

_ 

— 

1079.2 

MemMdl_9 

- 

— 

_ 

— 

— 

— 

— 

— 

1102.3 

— 

_ 

— 

— 

_ 

_ 

— 

1107.2 

MemMdL1 1 

- 

— 

- 

- 

— 

- 

- 

44.2 

— 

_ 

— 

— 

44.2 

— 

— 

— 

376.6 

pointer  1 500 

MemMdl_2 

31.0 

40.7 

38.7 

38.7 

39.5 

38.7 

38.8 

31.0 

38.7 

43.5 

43.6 

33.0 

30.9 

93.0 

71.1 

42.4 

30.7 

MemMdl_3 

30.9 

- 

— 

38.7 

— 

— 

— 

31.0 

38.7 

— 

_ 

37.6 

31.0 

— 

_ 

41.2 

30.7 

MemMdl_4 

46.5 

— 

— 

62.0 

— 

— 

— 

- 

60.3 

— 

— 

48.6 

— 

— 

— 

68.3 

54.2 

MemMdl_5 

46.4 

— 

— 

61.9 

— 

— 

— 

— 

60.3 

75.9 

— 

48.6 

— 

— 

_ 

69.8 

54.2 

MemMdl_7 

- 

— 

— 

— 

— 

— 

— 

49.0 

— 

— 

— 

48.7 

49.1 

— 

— 

— 

54.1 

MemMdl_8 

- 

- 

- 

— 

— 

— 

— 

— 

185.8 

— 

— 

— 

— 

— 

— 

— 

267.1 

MemMdl_9 

- 

- 

- 

— 

— 

— 

— 

— 

191.7 

— 

_ 

— 

_ 

_ 

— 

— 

278.6 

MemMdl-1 1 

— 

— 

- 

— 

— 

— 

— 

81.3 

— 

— 

— 

— 

81.3 

— 

— 

— 

275.9 

sieve  1 40 

MemMdl— 2 

61.2 

67.7 

60.0 

60.0 

63.2 

64.1 

71.3 

60.2 

59.9 

63.2 

63.2 

37.1 

60.1 

96.2 

86.8 

68.1 

44.4 

MemMdl_3 

61.2 

- 

— 

60.0 

— 

— 

— 

60.2 

59.9 

— 

— 

59.3 

60.2 

— 

— 

67.5 

44.4 

MemMdl_4 

61.1 

- 

— 

59.5 

— 

— 

— 

— 

59.9 

— 

_ 

59.2 

— 

— 

— 

75.1 

44.4 

MemMdl_5 

61.2 

110.0 

- 

59.5 

- 

- 

— 

— 

59.9 

76.5 

_ 

59.2 

— 

— 

— 

75.5 

44.3 

MemMdl_7 

- 

- 

— 

— 

— 

— 

— 

60.1 

— 

— 

— 

59.2 

60.2 

— 

— 

— 

44.4 

MemMdl_8 

— 

— 

— 

— 

— 

— 

— 

— 

59.9 

— 

— 

— 

— 

— 

— 

— 

45.5 

MemMdl_9 

— 

- 

— 

— 

— 

— 

— 

— 

59.9 

_ 

— 

— 

_ 

— 

_ 

— 

45.5 

MemMdl-1 1 

60.2 

60.1 

45.7 

Table  7:  Memory-model  EXE  time 
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(continued  from  page  44) 


Our  guess  is  that  the  cause  is  a  prob¬ 
lem  with  common  subexpression 
elimination  combined  with  float/ 
double  conversion. 

Overall,  this  is  a  very  good  compiler 
for  a  very  good  price.  The  only  reason 
we  do  not  recommend  it  is  that  we 
think  you’d  rather  spend  the  few  ex¬ 
tra  dollars  for  the  developer’s  version. 
The  extra  goodies  make  the  total  bang 
for  the  buck  impossible  to  beat. 

Datalight  C  Developer’s  Kit 

This  version  of  Datalight’s  compiler, 
new  since  last  year,  is  called  the  Data¬ 
light  C  Developer’s  Kit.  It  provides 
support  for  large-model  program¬ 
ming  (four  models  in  all).  The  com¬ 
ments  for  the  personal  version  apply 
equally  to  the  developer's  version,  so 
we  won’t  repeat  them  here.  The  de¬ 
veloper’s  package  is  indistinguishable 
from  the  personal  version  except  that 
it  includes  two  extra  disks  containing 
the  Iarge-memory-model  library  files 
and  source  code  for  the  library. 

We  did  notice  two  problems  with 
the  documentation  when  using  the 
developer's  version.  First  (and  trivial), 
the  file  names  for  the  various  large- 
model  start-up  object  files  were  listed 
incorrectly  (cc??.obj  instead  of  c??.obj). 
Second  (and  more  irritating),  we  could 
not  find  any  mention  of  how  to  run 
the  compiler  in  any  of  the  large-mod- 
el  modes.  We  found  the  information 
in  the  usage  summary  the  driver  pro¬ 
gram  prints  out  when  it  is  run  with  no 
arguments. 


Because  it  is  the  same  compiler,  it  is 
no  surprise  that  the  developer’s  ver¬ 
sion  contained  the  same  bug  we 
found  in  the  personal  version. 

Reviewing  this  compiler  was  quite 
a  surprise  for  us.  For  such  a  low 
price,  we  were  expecting  a  "light¬ 
weight”  compiler.  What  we  got  was 
a  package  that  is  as  good  as  or  better 
than  most  of  the  "heavyweights." 
Datalight  C  implements  a  complete  C 
language.  It  also  compiles  quickly, 
doesn't  take  up  much  disk  space,  and 
looks  impressive  in  the  benchmarks. 
About  the  only  things  we  could  ask 
for  are  a  source-level  debugger  and  a 
more  extensive  library. 

Eco-CSS 

Ecosoft  started  out  marketing  a  C 
compiler  for  Z80-based  CP/M  ma¬ 
chines.  A  little  over  a  year  ago,  it  start¬ 
ed  selling  an  8086  compiler  for  MS- 
DOS  systems  at  a  significantly  lower 
price.  It  is  now  up  to  Release  3.0  of 
that  compiler,  and  it  also  offers  a  low- 
cost  program  editor  to  go  with  it. 
Source  for  the  run-time  library  is  also 
available  at  extra  cost. 

The  Eco-C88  compiler  does  not  al¬ 
low  for  programming  in  large-mem¬ 
ory  models,  but  it  does  include  a  sens¬ 
ing  library  that  can  automatically 
detect  and  use  an  8087.  Bit  fields  are 
not  supported,  but  void,  enum,  struc¬ 
ture  assignment,  structure  pass/re¬ 
turn,  and  function  prototyping  are 
all  supported. 

Eco-C88  comes  on  two  disks  plus  an 
optional  third  containing  CED,  the 
program  editor.  The  disks  and  the 
manual  come  in  shrink-wrap,  with 


no  license  visible  on  the  package.  An 
install  program  automates  installing 
the  package  on  hard-  or  floppy-disk 
systems.  A  cc  driver  program  with 
source  code  is  included. 

The  documentation  is  poor  as  far  as 
packaging  and  technical  information 
goes.  There  is  no  detailed  list  of  what 
is  provided,  not  even  in  the  read. me 
file.  The  manual  lists  a  -r  option  for  cc 
as  "Assemble  with  8087  flag  on,” 
with  no  explanation  of  what  that 
might  mean.  There  are  no  options  to 
control  optimization  strategies.  Nest¬ 
ed  comments  are  allowed  unless  a 
-nn  option  is  supplied.  A  -pn  option 
sets  the  "pickiness”  level  of  the  com¬ 
piler,  which  can  lead  to  warnings  for 
a  large  number  of  common  usage  er¬ 
rors  (a  la  the  Unix  lint  utility). 

The  manual  is  an  IBM-size,  172- 
page  paperback  book  and  includes 
sections  on  the  optional  CED  editor.  It 
does  not  attempt  to  be  a  teaching  tool. 
In  fact,  Ecosoft  recommends  (and 
will  sell  you)  Purdum's  C  Program¬ 
ming  Guide,  and  the  manual  some¬ 
times  refers  you  to  that  book.  The  sec¬ 
tion  covering  the  library  needs  to  be 
expanded.  The  descriptions  of  each 
function  are  too  brief,  and  there  are 
almost  no  examples. 

Ecosoft  claims  the  current  compil¬ 
er  has  no  known  bugs.  It  promises  a 
free  compiler  to  any  registered  user 
who  sends  the  company  written  doc¬ 
umentation  of  an  actual  bug. 

IBM  C 

IBM  has  finally  released  a  C  compiler 
for  its  Personal  Computer.  Like  much 
IBM  PC  software,  IBM  did  not  write 
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the  compiler  in-house.  Instead,  it  li¬ 
censed  a  version  of  Microsoft  C  and 
repackaged  it  under  its  own  label. 
The  IBM  C  compiler  is  Microsoft  C, 
Version  3.0,  with  support  for  a  new 
memory  model — huge — which  al¬ 
lows  a  single  declared  object  to  be 
larger  than  64K.  It  also  has  a  better 
library. 

As  those  of  you  who  read  last  year’s 
review  already  know,  this  is  an  excel¬ 
lent  compiler.  It  directly  supports 
four  memory  models  and  has  lan¬ 
guage  support  for  mixed-model  pro¬ 
gramming  (for  example,  you  can  dy¬ 
namically  allocate  a  200K  object  and 
manipulate  it  via  explicitly  declared 
huge  pointers  in  an  otherwise  small/ 


small  program).  It  has  five  floating¬ 
point  options,  including  in-line  8087 
code  with  a  sensing  library  and  a  fast¬ 
er  but  less  accurate  software-only  li¬ 
brary.  There  is  an  option  to  generate 
code  for  an  80186  or  80286  and  all 
kinds  of  options  to  control  optimiza¬ 
tion  strategies.  It  also  has  a  symbolic 
(not  source-level)  debugger  and  a 
make  utility.  No  source  code  is  avail¬ 
able  for  the  run-time  library, 
however. 

The  IBM  package  is  professional. 
The  compiler  comes  on  four  disks. 
The  manual  covering  compiler  in¬ 
stallation  and  use  is  complete. 

The  documentation  is  top-notch  in 
almost  every  category.  Three  man¬ 
uals  are  provided  in  two  IBM-size 
(surprise!),  D-ring  binders  with  slip- 
cases.  One  binder  contains  the  li¬ 


brary  reference  manual,  and  the 
other  contains  a  manual  on  using  the 
package  and  a  smaller,  language  ref¬ 
erence  manual.  The  manuals  docu¬ 
ment  IBM  C  in  great  detail — the  only 
things  missing  are  a  hand-holding  tu¬ 
torial  on  C  and  information  about 
where  IBM  C  differs  from  the  K  &  R 
standard.  Extensions  include  void, 
enum,  structure  and  union  pass/re¬ 
turn,  and  function  prototyping. 

The  language  reference  is  com¬ 
plete  and  readable,  though  it  is  a  ref¬ 
erence  document  and  not  a  tutorial. 
The  library  reference  is  a  joy — one 
function  per  page,  alphabetical  or¬ 
der,  cross-reference,  large  table  of 
contents  and  index,  good  use  of  large 
typefaces,  boldface  and  italic  print — 
the  works.  The  production  values 
(paper  stock,  ink,  and  so  on)  are  also 
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excellent  throughout. 

IBM  C  is  very  good,  but  Microsoft 
has  not  been  sitting  still. 

Lattice  C 

Lattice  was  the  first  company  to  re¬ 
lease  a  quality  C  compiler  for  MS-DOS 
systems,  and  it  quickly  established 
market  leadership  and  a  reputation 
as  the  compiler  of  choice.  In  last 
year's  review,  we  found  that  Lattice 
C  had  not  kept  pace  with  its  competi¬ 
tors  and  no  longer  deserved  its  billing 
as  the  compiler  to  beat.  Lattice  has 
since  released  a  new,  upgraded  ver¬ 
sion  of  its  compiler  and  has  made  sig¬ 
nificant  improvements. 

Lattice  C,  Version  3.0,  supports  a  to¬ 
tal  of  six  memory  models  and  four 
floating-point-support  options.  It  can 
generate  code  for  80186  and  80286 
processors.  The  company  also  offers 
|  a  source-level  debugger  called  C- 
(  Sprite  as  a  separate  product. 

The  compiler  comes  on  four  disks 
|  and  includes  batch  files  for  hard-disk 
and  floppy-disk  installation,  though 
you  may  decide  to  delete  some  of  the 
subdirectories  created  on  a  hard  disk 
if  you  don’t  need  all  memory  models 
available  at  all  times.  Using  the  com- 
J  piler  is  complicated  because  usage  in- 
|  formation  is  in  three  places:  the  basic 
j  manual,  which  applies  to  Version 
2.15;  the  Version  3.0  Technical  Bulle- 
|  tin;  and  the  read. me  file.  Lattice  has 
added,  removed,  or  changed  numer- 
j  ous  options,  so  you  have  to  read  ev- 
J  erything  carefully  to  build  up  a  pic- 
j  ture  of  current  reality. 

We  had  a  serious  problem  regard¬ 
ing  the  linker.  The  Technical  Bulletin 
warns  that  MS-DOS  LINK,  Version  3.0 
or  later,  may  be  required  in  certain 
cases.  Careful  reading  led  us  to  be¬ 
lieve  that  the  warning  did  not  apply 
to  what  we  would  be  doing,  and  then 
the  read,  me  file  claimed  the  problem 
was  resolved  in  any  case — LINK,  Ver¬ 
sion  2.0  or  later,  should  work  in  all 
cases.  We  therefore  tried  to  use  the 
version  of  LINK  (2.2)  that  came  with 
our  computer,  as  we  did  with  all 
compilers  that  did  not  supply  their 
own  linker.  It  did  not  work,  no  mat¬ 
ter  what  memory  model  we  tried. 
The  usual  symptom  was  "write  fault 
error  writing  device  PRN”  followed 
by  a  system  crash.  We  were  not  redi¬ 
recting  output.  LINK  3.01  worked 
fine,  so  that  is  what  we  used,  but  it 
gave  Lattice  an  unfair  advantage  as 


3.01  is  faster. 

An  environment  variable  (IN¬ 
CLUDE)  is  supported  to  specify  a 
search  path  for  include  files.  In  fact, 
using  it  is  mandatory  if  you  use  angle 
brackets  to  delimit  the  include  file 
name,  as  is  commonly  done  for 
stdio.h.  Lattice  C  does  not  search  the 
current  directory,  or  even  directories 
specified  with  the  -i  option,  automati¬ 
cally — no  INCLUDEee,  no  findee. 

An  option  is  available  to  force 
j  word  alignment  for  all  data  types  ex¬ 
cept  char  and  struct.  We  used  this  op¬ 
tion  because  non-word-aligned 
fetches  are  less  efficient  on  8086  (or 
better)  machines.  We  think  word 
alignment  should  be  the  default. 

An  option  has  been  added  to  cause 
the  intermediate  (quad)  file  in  memo¬ 
ry  to  speed  up  compile  time.  We  used 
this  option  for  all  but  doclOOO.c — ap¬ 
parently  we  ran  out  of  memory  after 
600-650  lines,  resulting  in  an  "inter¬ 
mediate  file  error.” 

The  documentation  consists  of  two 
IBM-size,  spiral-bound  manuals.  This 
is  a  change  from  last  year,  when  Lat¬ 
tice  supplied  the  normal  D-ring  bind¬ 
er  and  slipcase.  At  least  one  of  our 
reviewers  prefers  the  spiral-bound 
approach  because  it  takes  less  space 
and  lies  flat,  but  update  pages  cannot 
be  inserted. 

The  first  manual  is  the  reference 
for  Lattice  C,  Version  2.15,  and  the 
second  (almost  as  big  as  the  first)  is  a 
technical  bulletin  describing  the 
changes  for  Version  3.0.  The  produc¬ 
tion  quality  (use  of  typefaces,  color, 
and  so  on)  is  excellent  in  the  first 
manual,  less  so  in  the  second.  Also, 
the  library  reference  is  split  between 
the  two.  You  start  with  the  Technical 
Bulletin,  which  may  point  you  back  at 
the  2.15  manual.  The  2.15  manual  in¬ 
cludes  a  table  of  contents,  index,  and 
a  separate  index  for  library  func¬ 
tions.  The  Technical  Bulletin  has  a 
I  brief  table  of  contents  and  an  updat¬ 
ed  function  index. 

The  2.15  manual  contains  a  brief 
summary  of  the  language  definition 
as  well  as  a  list  of  differences  from  K 
&  R;  it’s  well  done  but  will  not  take 
j  the  place  of  a  language  reference 
manual.  The  library  reference  is  in 
the  Unix  style,  with  several  functions 
sometimes  described  together  and  no 
examples,  but  the  amount  of  infor¬ 
mation  is  good  and  the  function  in¬ 
dex  makes  lookup  easy  (except  for 


needing  the  two  manuals).  Cross-ref¬ 
erences  and  warnings  are  included 
where  appropriate,  as  well  as  an  in¬ 
dication  of  how  portable  you  can  ex-  j 
pect  the  function  to  be.  Overall,  we 
would  rate  the  documentation  very 
highly  if  the  current  two  manuals 
were  replaced  with  a  single  volume 
specifically  for  the  new  release  and 
up  to  the  standard  set  by  the  2.15 
manual  for  production  values. 

Although  Version  3.0  represents  a 
significant  improvement  for  Lattice, 
the  other  vendors  have  not  stood  still 
either  and  we  still  cannot  rate  this 
compiler  in  the  top  few.  It  should  be  | 
noted,  however,  that  Lattice  provides 
compilers  for  the  same  language  for 
minicomputers  and  mainframes  as 
[  well  as  for  many  other  microcom- 
j  puters.  Also,  Lattice  still  eniovs  more 
third-party  support  for  add-on  librar¬ 
ies  and  utilities  than  any  other  ven¬ 
dor,  although  that  gap  is  narrowing. 
These  considerations  will  probably 
be  important  for  some  users. 

Manx  Aztec  C 

Manx  Software  Systems  got  its  start 
selling  a  very  good  8080  compiler  for 
CP/M  systems  at  a  reasonable  price. 

It  has  since  moved  that  compiler  to 
j  MS-DOS  machines,  Apple  IIs,  the  Mac¬ 
intosh,  and  most  recently  the 
Commodore  Amiga  and  the  Atari  ST 
machines.  It  has  made  many  en¬ 
hancements  and  upgrades  along  the 
!  way,  but  the  same  basic  language  is 
available  on  all  those  machines  from 
the  same  vendor.  For  MS-DOS  ma¬ 
chines,  the  company  markets  several 
different  packages  with  different 
bundles  of  goodies.  We  reviewed  the 
Commercial  package,  which  comes 
with  everything,  including  full 
source  code  for  the  run-time  library. 
We  reviewed  Version  3.30C  of  the 
compiler  while  it  was  still  in  beta  test. 

This  is  a  big  package.  The  latest  re¬ 
lease  includes  a  new  source-level  de- 
|  bugger  and  an  execution-time  profil¬ 
er.  Also  included  are  a  full-screen 
editor  similar  to  the  Unix  vi  editor,  a 
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Figure  1:  Execution  times  of  pointer  benchmark 
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■■■■  Compile  time  for  1000-line  source  file  (DOC1000) 


Figure  3:  Compile  initialization  overhead 
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Figure  3:  Execution  times  of  trig  benchmark 


Figure  4:  Use  of  register  variables  with  dhrystone 
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fairly  powerful  make  utility,  extra  li¬ 
braries  for  MS-DOS  screen  and  graph¬ 
ics  functions,  a  CP/M-86  library,  and 
other  utility  programs  familiar  to 
Unix  fans.  The  compiler  supports 
four  memory  models  and  four  float¬ 
ing-point-support  options  and  can 
generate  80186  or  80286  code.  It  sup¬ 
ports  the  full  K  &,  R  language  plus 
void,  enum,  and  structure  assignment. 

The  Commercial  version  is  distrib¬ 
uted  on  four  disks,  but  the  compiler, 
assembler,  linker,  and  libraries  for  all 
memory  models  will  fit  on  two  disks 
with  room  left  over.  Aztec  C  uses  its 
own  object  format,  but  a  utility  is  pro¬ 
vided  to  convert  to  Microsoft  format 
if  desired.  The  installation  notes  con¬ 
centrate  on  floppy-disk  installation 
and  there  is  no  batch  file  for  automat¬ 
ing  the  process,  but  installation  is  not 
too  difficult. 

Aztec  C  supports  environment 
variables  specifying  the  search  path 
for  include  files  and  libraries.  If  no 
INCLUDE  environment  variable  is  set, 
the  compiler  scans  the  current  direc¬ 
tory  for  include  files  enclosed  in  an¬ 
gle  brackets,  which  is  nice  of  it.  Manx 
includes  an  older,  nonoptimizing 
version  of  the  compiler,  which  it 
claims  will  compile  faster  than  the 
full  optimizing  version. 

New  with  this  version  is  a  driver 
program  that  can  handle  wildcards 
on  the  command  line  and  can  run  the 
linker  automatically.  Previously,  the 
compiler  would  invoke  the  assem¬ 
bler,  but  you  had  to  run  the  linker 
separately. 

The  documentation  has  been  ex¬ 
panded  and  improved  since  our  last 
review,  and  it  now  has  an  index.  The 
manual  consists  of  more  than  630 
pages  in  an  IBM-size,  D-ring  binder 
with  slipcase.  It  is  organized  as 
named  sections  that  desperately 
need  index  tabs  for  quick  flipping. 
The  overall  table  of  contents  at  the 
front  covers  all  sections  in  detail  ex¬ 
cept  the  various  library  sections. 
Each  section  has  its  own  table  of  con¬ 
tents  as  well.  The  index  is  fairly  com¬ 
plete  but  would  be  easier  to  read  if  it 
were  better  formatted.  Page  refer¬ 
ences  are  to  “section  name. page 
number.”  This  is  where  the  index 
tabs  would  come  in  handy — it’s  not 
easy  to  find  your  40-page  section  in 


the  middle  of  600-odd  other  pages. 
The  index  starts  off  with  a  list  of  how 
the  sections  are  ordered,  but  that  is 
not  much  help  (especially  if  you  have 
reshuffled  them  to  put  all  the  library 
sections  together). 

There  is  a  lot  of  material  here  de¬ 
scribing  the  compiler,  assembler,  and 
linker  and  technical  information 
such  as  memory  layout,  building 
overlay  programs,  and  ROMable 
code.  An  excellent  section  (25  pages) 
on  compiler  error  messages  has  a 
paragraph  describing  each  error,  of¬ 
ten  with  examples! 

No  language  reference  is  included; 
you  will  need  K  &  R  or  some  other 
book.  A  good  section  describes  imple¬ 
mentation-specific  information  and 
differences  from  K  &  R.  There  is  also 
a  section  called  "style,”  which  con¬ 
tains  some  good  advice  on  C  philoso¬ 
phy  and  programming  practices. 
This  is  an  unusual  touch. 

The  library  sections  are  organized 
a  la  Unix,  with  several  related  func¬ 
tions  on  a  page.  The  function  descrip¬ 
tions  are  typically  terse,  but  there  are 
sometimes  examples.  The  typefaces 
and  use  of  boldface,  italics,  and  in¬ 
dentation  are  good.  The  new  index  is 
the  easiest  way  to  find  a  function  you 
know  the  name  of;  otherwise  it  may 
take  you  a  while. 

C  Programming  System 

Mark  Williams  Co.  has  been  around 
for  quite  a  while  and  has  established 
a  good  reputation  for  its  Unix-like  op¬ 
erating  system  and  its  C  compiler. 
The  C  Programming  System  compil¬ 
er  is  in  the  "heavyweight”  class  and 
is  priced  accordingly.  It  includes  sev¬ 
eral  8087  support  options  and  large/ 
large-memory-model  support.  It 
comes  with  a  full  source-level  debug¬ 
ger,  two  editors  (including  full  source 
code  for  MicroEMACS — an  EMACS 
subset),  and  several  utility  programs. 
CSD,  the  source-level  debugger,  is 
powerful  but  can  be  used  only  with 
the  Mark  Williams  object  format, 
which  in  turn  can  be  used  only  for 
small/small-model  programming. 

C  Programming  System  comes 
with  a  total  of  five  disks  and  two  IBM- 
size  manuals  in  the  usual  D-ring  bind¬ 
ers  with  slipcases.  The  manual  sec¬ 
tion  on  installing  the  compiler 
applies  to  the  company's  Let's  C, 
which  is  a  little  disconcerting.  The  re¬ 
lease  notes  in  front  of  the  manual 


cover  installation  of  C  Programming 
System.  Although  a  list  of  files  on  the 
distribution  disks  is  given,  the  list 
does  not  describe  what  each  file  is. 

A  large  number  of  compiler  op¬ 
tions  are  available  to  turn  on  (or  off) 
various  categories  of  warning  mes¬ 
sages,  which  can  prove  useful.  There 
are  no  options  for  controlling  compil¬ 
er  optimization  strategies  as  there  are 
in  most  heavyweight  compilers. 
There  is  an  option  that  causes  a  dif¬ 
ferent  version  of  the  start-up  and  exit 
code  to  be  linked  in  that  can  produce 
smaller  .exe  files  if  you  don't  need 
the  standard  I/O  package.  The  com¬ 
piler  also  has  options  that  cause  it  to 
generate  code  specifically  for  80186 
and  80286  processors. 

The  documentation  is  professional 
and  includes  a  good  table  of  contents 
and  an  index.  The  language  refer¬ 
ence  material  is  simply  a  list  of  differ¬ 
ences  from  K  &  R.  The  library  refer¬ 
ence  is  complete  but  perhaps  a  little 
too  concise  and  does  not  include 
examples. 

The  manuals  do  have  some  confus¬ 
ing  inconsistencies.  The  release 
notes,  for  instance,  indicate  that 
MASM  (the  Microsoft  assembler) 
should  be  on  your  program  disk  if 
you  want  to  use  Microsoft  object  for¬ 
mat,  but  it  is  not  clear  why.  We  did 
not  need  MASM  to  compile  and  run 
any  of  the  benchmarks.  The  section 
on  the  assembler  claims  that  the 
large  model  will  be  discussed,  but  it 
isn’t.  The  assembler  option  to  gener¬ 
ate  Microsoft  object  format  is  de¬ 
scribed  as  causing  small-model  object 
to  be  generated  (?!). 

Mark  Williams’  C  Programming 
System  has  little  to  recommend  it 
over  its  competitors  and  its  debugger 
is  no  longer  unique. 

Let’s  C  with  CSD 

Mark  Williams’  Let's  C  package,  new 
since  last  year,  is  a  stripped-down 
version  of  the  company's  established 
C  Programming  System.  Let’s  C  in¬ 
cludes  the  same  compiler  but  with 
support  for  Microsoft  object  format 
and  8087  floating-point  coprocessors 
removed.  Because  you  are  restricted 
to  Mark  Williams  object  format,  you 
can  program  only  in  the  small/small- 
memory  model  with  Let’s  C.  Also  re¬ 
moved  from  the  Let’s  C  package  are 
the  make  utility,  ed  editor,  and  m4 
macro  processor.  Not  removed  from 


53 

562 


Dr.  Dobb's  Journal,  August  1986 


C  COMPILERS 

(continued  from  page  52) 


the  Let's  C  package  is  MicroEMACS,  a 
subset  of  the  EMACS  full-screen  edi¬ 
tor  with  full  source  code.  Let’s  C  can 
generate  the  same  large  set  of  warn¬ 
ing  messages  as  the  full  C  Program¬ 
ming  System  package  and  supports 
the  same  facilities  for  minimizing 
.exe  file  size. 

The  Mark  Williams  source-level 
debugger  CSD  works  with  Let’s  C,  but 
it  is  an  option  that  doubles  the  cost  of 
the  package.  The  Let’s  C  package 
with  the  CSD  option  includes  three 
disks  and  two  manuals.  Unlike  C  Pro¬ 
gramming  System,  the  compiler  and 
debugger  manuals  are  spiral-bound, 
making  it  impossible  to  insert  update 
pages.  The  contents  of  the  manuals 
appear  to  be  the  same  as  the  larger 
slipcase  versions  that  come  with  C 
Programming  System.  Both  use  shad¬ 
ing  to  mark  text  that  does  not  apply  to 
Let’s  C.  The  spiral-bound  CSD  manual 
that  comes  with  Let’s  C  covers  only 
CSD,  not  the  other  utility  programs 
that  are  not  included  with  Let’s  C. 
Other  than  that,  and  the  physical 
packaging,  the  Let’s  C  documentation 
is  the  same  as  that  for  the  full  C  Pro¬ 
gramming  System  package. 

High  C 

MetaWare  is  new  to  the  MS-DOS  C 
compiler  marketplace  this  year,  but 
it  is  not  without  experience  in  pro¬ 
viding  high-quality  compilers.  The 
principals  of  MetaWare  are  well 
known  and  respected  in  computer 
language  circles. 

High  C  is  large.  It  comes  on  seven 
disks  and  provides  an  installation 
batch  file  whose  use  is  virtually  man¬ 
datory.  The  compiler  itself  is  a  single 
.exe  file  of  more  than  520K  (the  com¬ 
piler  will  run  on  320K  machines  be¬ 
cause  much  of  the  .exe  file  is  over¬ 
lays),  so  do  not  buy  High  C  if  you  do 
not  have  lots  of  disk  space  (about  2 
megabytes)  left  on  a  hard  disk. 

High  C  supports  five  memory  mod¬ 
els  and  can  be  directed  to  use  a  sens¬ 
ing  8087  library  or  in-line  8087  code. 
It  supports  almost  the  entire  emerg¬ 
ing  ANSI  standard,  and  MetaWare 
can  change  the  language  almost  as 
fast  as  ANSI  can  generate  new  drafts. 
The  compiler  produces  excellent  di¬ 
agnostic  messages,  detecting  many 
less  than  desirable  code  features 
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without  complaining  about  too  many 
intended  code  sequences.  Pragmas 
are  supported  by  High  C  in  a  big  way. 
With  them  you  can  change  the  seg¬ 
ment,  group,  and/or  class  of  any  ob¬ 
ject;  select  the  default  calling  conven¬ 
tion;  specify  how  values  are  to  be 
returned;  enable  automatic  register 
allocation  or  disable  registers  alto¬ 
gether;  turn  on  or  off  any  optimiza¬ 
tion;  and  generally  control  your  com¬ 
pilation  in  any  desirable  way  at  any 
point  in  your  source  code.  The  flexi¬ 
bility  is  daunting  at  times,  but  we 
think  we  would  rather  make  these 
decisions  than  not. 

The  documentation  for  High  C  con¬ 
sists  of  about  720  pages  in  a  single 
IBM-size,  D-ring  binder.  That’s  a  lot  of 
pages,  but  they  are  separated  into 
three  major  and  three  minor  sections 
by  labeled  index  tabs.  The  three  mi¬ 
nor  sections  are  the  release  notes,  the 
license/warranty  section,  and  an  in¬ 
stallation  guide.  The  three  major  sec¬ 
tions  are  the  Programmer's  Guide  (us¬ 
age  and  technical  information),  the 
Library  Reference,  and  the  Language 
Reference.  Each  of  the  major  sections 
has  a  complete  table  of  contents,  in¬ 
dex,  and  a  request  for  user  feedback. 
All  the  indexes  are  the  permuted 
type  found  in  some  Unix  documenta¬ 
tion,  and  instructions  are  included  on 
how  to  use  one.  Although  some  pre¬ 
fer  this  type  of  index  (including  one 
reviewer),  some  of  us  feel  a  normal 
index  is  easier  to  use.  The  index  refer¬ 
ences  are  to  section  numbers,  not 
page  numbers.  This  can  be  more  pre¬ 
cise  (pointing  at  a  paragraph  instead 
of  a  page),  but  it  makes  it  harder  to 
flip  to  the  right  spot. 

The  production  quality  is  variable. 
The  Language  Reference  is  still  in 
dot-matrix  format  and  is  hard  to  read 
in  places,  though  the  feedback  re¬ 
quest  states  that  a  typeset  version  is  in 
the  works.  The  Programmer’s  Guide 
and  Library  Reference  are  typeset, 
but  all  three  sections  suffer  from  too 
little  white  space  for  good  readabili¬ 
ty.  Also,  the  choice  of  type  styles  and 
sizes  is  often  strange,  further  degrad¬ 
ing  readability.  This  is  especially  true 
in  the  Library  Reference. 

As  far  as  content  goes,  there  is  an 
immense  amount  of  information 
here,  as  you  could  guess  with  720 


pages  and  almost  no  white  space  on 
the  average  page.  This  is  a  big,  com¬ 
plex  product  geared  toward  profes¬ 
sional  programmers  who  are  already 
quite  familiar  with  C,  and  such  peo¬ 
ple  will  find  all  they  could  want  in 
this  manual.  Average  users  will  prob¬ 
ably  find  it  heavy  going  and  will  be  in 
for  some  frustration. 

The  Language  Reference  is  actual¬ 
ly  a  precise,  formal  definition  of  the  C 
language  as  implemented  by 
MetaWare.  It  is  complete  and  unam¬ 
biguous,  but  if  you  are  not  familiar 
with  formal  notation  and  context- 
free  grammars,  you  may  find  it  diffi¬ 
cult  to  understand.  The  Library  Ref¬ 
erence  is  organized  along  the  same 
lines  as  in  the  emerging  ANSI  stan¬ 
dard,  with  functions  grouped  accord¬ 
ing  to  type  and  types  grouped  by  a 
standard  header  file.  Within  each 
group  functions  are  described  one  at 
a  time  and  in  alphabetical  order,  but 
there  are  many  groups  so  you  will 
need  to  learn  to  use  the  index.  There 
are  examples  and  "cautions”  and 
"system  dependencies”  sections 
where  appropriate.  In  terms  of  con¬ 
tent,  this  is  excellent  documentation. 
Overall,  you  are  probably  either  go¬ 
ing  to  love  this  manual  or  hate  it. 

Microsoft  C 

Microsoft  is  not  like  most  vendors, 
which  are  almost  continually  releas¬ 
ing  minor  revisions  to  their  products. 
Microsoft  doesn’t  take  many  steps, 
but  the  ones  it  takes  are  big  ones.  Last 
year,  just  before  we  started  working 
on  our  review,  it  discontinued  mar¬ 
keting  a  repackaged  Lattice  compiler 
and  released  its  own  product.  In  one 
step  it  went  from  also-ran  status  to 
supplying  the  most  professional 
package  with  perhaps  the  best  C 
compiler  available.  For  the  next  year 
it  released  no  updates,  unless  you 
count  the  IBM  version,  which  added 
the  huge-memory  model.  Now,  just 
barely  in  time  for  this  year’s  review, 
comes  a  beta  copy  of  the  upcoming 
Microsoft  C,  Version  4.0,  and  it  is  an¬ 
other  big  step. 

Compared  to  Version  3.0  (and 
IBM’s),  the  new  package  features  fast¬ 
er  compile  time;  improved  code 
generation;  more  memory  models; 
various  language  and  library  en¬ 
hancements;  and  a  mouse-driven, 
full-windowing,  source-level  debug¬ 
ger  that  puts  the  rest  to  shame.  If  it 


were  not  beyond  the  scope  of  this  re¬ 
view,  we  could  go  on  for  some  time 
about  the  new  debugger.  Suffice  to 
say  that,  although  the  basic  capabili¬ 
ties  provided  are  similar  to  other  full- 
function  source  debuggers,  the  user 
interface  is  a  dream  come  true. 

Like  its  predecessor,  the  Microsoft 
C,  Version  4.0,  package  concentrates 
on  the  compiler  itself.  A  powerful 
version  of  the  make  utility  is  provid¬ 
ed,  and  of  course  that  marvelous  de¬ 
bugger,  but  that  is  about  it  as  far  as 
goodies  go.  It  has  no  editor,  no  Unix 
tools,  and  no  special-purpose  librar¬ 
ies,  and  only  source  code  for  the  start¬ 
up  code  is  included.  The  compiler 
supports  the  full  K  &,  R  definition  of 
C,  plus  void,  enum,  signed,  structure 
and  union  assignment,  structure  and 
union  pass/return,  and  function 
prototyping  (but  not  completely). 
Additional  keywords  are  optionally 
supported  for  mixed-model  pro¬ 
gramming  and  alternate  function¬ 
calling  conventions.  The  package  has 
full  support  (compiler  and  library) 
for  five  memory  models  and  partial 
support  (compiler  only)  for  a  total  of 
18  memory-model  variations!  There 
are  also  seven  floating-point-support 
options,  including  an  alternate  soft- 
ware-only  library  that  sacrifices  pre¬ 
cision  for  speed. 

This  is  a  large  package.  It  comes  on 
seven  disks,  of  which  five  disks  are 
required  to  hold  the  compiler,  linker, 
and  all  the  libraries.  The  other  two 
are  for  the  start-up  sources  and  the 
debugger.  There  are  no  batch  files  to 
automate  the  installation  process,  but 
separate  sections  in  the  User's  Guide 
give  step-by-step  instructions  for  a 
"quick”  hard-disk  or  floppy-disk  in¬ 
stallation.  A  huge  amount  of  setup, 
usage,  and  technical  information  is 
provided.  It  is  well  written,  but  it 
takes  a  while  to  wade  through.  You 
can  choose  between  two  driver  pro¬ 
grams — MSC  and  CL,  which  is  de¬ 
signed  to  work  more  like  Unix  driv¬ 
ers  do.  We  preferred  CL,  but  both 
support  a  vast  number  of  options  tak¬ 
ing  several  pages  to  list  in  the  summa¬ 
ry  sections  provided.  There  are 
many  options  controlling  optimiza¬ 
tion  strategy,  and  there  is  an  option  to 
tell  the  compiler  to  do  a  simple  syn¬ 
tax  check  rather  than  a  full  com¬ 
pile — very  nice! 

We  received  a  preproduction  copy 
of  the  documentation  printed  on 
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8.5X  11-inch  paper,  but  it  is  a  good  bet 
that  the  final  package  will  follow  the 
pattern  of  Version  3.0’s  and  now 
IBM's.  The  organization  and  content 
is  an  improvement  in  some  ways 
over  the  IBM  package,  although  it  is 
similar  except  for  the  addition  of  a 
fourth  manual  documenting  Code¬ 
View,  the  source  debugger.  The  final 
package  will  come  in  three  binders. 
One  of  the  improvements  is  the  addi¬ 
tion  of  several  appendices  in  the 
User's  Guide  with  information  on 
converting  from  earlier  versions, 
writing  portable  code,  and  a  summa¬ 
ry  of  differences  from  K  &  R. 

Assuming  production  values  in  the 
final  package  are  in  line  with  past 
practice  at  Microsoft,  the  documenta¬ 
tion  once  again  gets  the  highest  rat¬ 
ing.  The  only  fault  we  can  find  is 
with  the  User's  Guide.  Although  it 
contains  a  huge  amount  of  good  in¬ 
formation,  well  organized  and  writ¬ 
ten,  it  has  some  gaps.  For  instance,  it 
gives  an  actual  example  of  code  that 
will  misbehave  if  you  tell  the  compil¬ 
er  you  won't  do  aliasing  (an  optimiza¬ 
tion  option)  and  then  you  do — it  does 
not  give  a  complete  list  of  the  aliasing 
assumptions  made  by  the  compiler. 
Is  it  safe  to  point  at  a  named  array  (a 
common  practice)  and  access  it  both 
ways  or  not? 

Mix  C,  ASM  Utility,  Mix  Editor 

Mix  Software  is  a  relative  newcomer 
to  the  C  compiler  market.  It  has  a 
very-low-cost  and  fairly  complete 
product.  Mix  C  does  not  generate  as¬ 
sembler  code  and  does  not  use  Micro¬ 
soft  object  format.  The  extra-cost  ASM 
utility  can  be  used  to  convert  .OBJ  files 
to  .MIX  format.  Mix  C  can  generate 
only  .COM  files,  so  program/data  size 
is  even  more  restricted  than  with 
other  small/small  compilers. 

We  received  the  Mix  C  compiler 
with  the  extra-cost  ASM  utility  and 
Mix  Editor,  so  our  package  included 
three  disks  and  two  books.  Two  disks 
and  the  thick  (about  440  pages)  book 
make  up  the  compiler  and  ASM  utili¬ 
ty,  and  the  third  disk  and  100-page 
manual  are  for  the  editor. 

The  manuals  are  not  the  usual  IBM- 
size  binders.  Both  are  8.5  X  11-inch, 
bound  books,  so  updates  are  strictly 
in  the  form  of  read. me  files.  Techni¬ 


cal  information  about  the  compiler  is 
almost  nonexistent,  and  you  have  to 
use  DEBUG  to  change  various  compil¬ 
er  option  defaults.  The  compiler 
manual  is  separated  into  five  sec¬ 
tions,  each  with  its  own  table  of  con¬ 
tents.  The  first  section,  Getting  Start¬ 
ed,  tells  you  how  to  set  up  your  disks 
and  compile  and  execute  your  first  C 
program.  The  second  section  is  a 
large,  well-written  tutorial  to  intro¬ 
duce  fledgling  C  programmers  to  the 
language.  The  third  section  is  a  com¬ 
plete  reference  manual  for  C,  and  the 
fourth  documents  the  supplied  li¬ 
brary  functions.  The  last  section  doc¬ 
uments  the  use  of  the  C  compiler, 
linker,  and  other  tools  provided  with 
the  package.  The  second,  third,  and 
fourth  sections  have  their  own  in¬ 
dexes,  but  the  whole  book  has  no 
global  table  of  contents  or  index. 

Mix  seems  to  be  targeting  this  pack¬ 
age  at  newcomers  to  C  who  will  buy 
the  book  and  get  the  compiler  to  boot. 
From  that  standpoint,  the  documen¬ 
tation  is  very  good.  The  tutorial  and 
reference  sections  are  well  written, 
with  lots  of  examples  and  an  appro¬ 
priate  level  of  verbiage.  A  few  of  the 
library  functions  are  documented  in 
the  language  reference  section  and 
can  therefore  be  difficult  to  find.  Mix 
C  is  probably  a  good  choice  for  some¬ 
one  who  wants  to  learn  about  C  with¬ 
out  spending  much  money. 

Toolworks  C  with  Mathpak 

Software  Toolworks  has  been  mar¬ 
keting  several  low-cost  tools  and  utili¬ 
ties,  including  a  subset  C  compiler, 
for  a  long  time.  It  has  recently  ad¬ 
dressed  a  major  shortcoming  of  its  C 
compiler  by  making  available  an  op¬ 
tional  Mathpak  package  that  adds 
support  for  the  long  and  float  data 
types.  This  is  what  we  reviewed. 

Even  with  the  Mathpak,  Toolworks 
C  is  a  subset  compiler.  Bit  fields  and 
typedef  are  not  supported,  declara¬ 
tions  are  not  allowed  in  nested  blocks 
(only  at  the  start  of  a  function),  double 
precision  ( double  is  a  synonym  for 
float)  is  not  supported,  and  the  pre¬ 
processor  does  not  support  #line  or 
* define  macros  with  arguments.  Also, 
function  calls  must  have  exactly  the 
same  number  of  arguments  as  the 
function  definition  (printf  and  scanf 
are  the  only  exceptions).  Of  these,  the 
lack  of  typedef  and  parameterized 
macros  are  the  most  serious  omis¬ 


sions.  The  Mathpak  does  include  sup¬ 
port  for  an  8087,  although  not  via  a 
sensing  library.  There  are  some  brief 
notes  on  how  to  modify  the  package 
to  merge  the  software-only  and  8087- 
only  libraries  to  form  a  sensing  li¬ 
brary,  but  they  are  for  hackers  only — 
for  instance,  you  are  left  on  your  own 
in  figuring  out  how  to  do  the  actual 
sensing.  Full  source  code  is  provided 
for  all  libraries. 

The  Toolworks  compiler  is  a 
throwback  to  the  old  days:  It  comes 
packaged  in  a  Ziplock  bag!  The  com¬ 
piler  takes  up  two  disks,  and  the  op¬ 
tional  Mathpak  takes  up  another 
two.  The  installed  package  does  not 
take  much  disk  space,  however.  You 
have  to  install  the  compiler  first  and 
then  do  the  Mathpak  installation  pro¬ 
cedure,  which  modifies  the  installed 
compiler  and  replaces  the  library.  It 
is  actually  easier  than  it  sounds. 

There  is  no  driver  program  for  the 
compiler.  Each  pass  must  be  run  sep¬ 
arately  from  the  command  line  or 
from  a  batch  file.  Several  compiler 
options  are  available  to  control  such 
things  as  when  string  constants  are 
generated,  the  size  of  the  switch/case 
table,  string  space,  * define  table 
space,  and  so  on.  Toolworks  C  over¬ 
laps  identical  strings  by  default,  but 
you  can  override  this.  There  is  an  op¬ 
tion  that  causes  an  execution-time 
profile  to  be  generated  when  the  pro¬ 
gram  is  run.  The  option  to  specify  an 
include-file  search  path  is  mandatory 
if  you  enclose  the  file  name  in  angle 
brackets  on  your  * include  directive 
or  the  file  will  not  be  found.  Tool¬ 
works  C  also  has  a  program  to  config¬ 
ure  the  compiler  to  make  a  specified 
set  of  options  the  default. 

The  documentation  consists  of 
8.5  X  11-inch  sheets  stapled  together 
and  folded  to  fit  in  that  Ziplock  bag. 
The  compiler  manual  has  75  pages 
and  includes  a  table  of  contents  and 
an  index,  which  also  indexes  the  li¬ 
brary  functions.  The  23-page  Math¬ 
pak  manual  has  a  table  of  contents 
but  no  index  (hardly  necessary  here). 
There  is  a  very  brief  language  sum¬ 
mary,  obviously  not  intended  as  a 
learning  aid.  Likewise,  the  library 
function  reference  is  very  brief,  not 
even  adequate  in  our  opinion.  The 
documentation  contains  an  unusual¬ 
ly  large  amount  of  technical  informa¬ 
tion,  indicating  that  this  package  is 
aimed  at  the  technically  minded. 
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Even  at  this  low  price,  there  is  no 
longer  any  reason  to  accept  a  subset 
compiler.  There  are  now  several  full 
compilers  to  choose  from  at  similar 
prices. 

Whitesmiths  C 

Whitesmiths  has  probably  been 
around  longer  than  any  other  com¬ 
piler  vendor  mentioned  here.  It  pro¬ 
vides  its  compiler  for  many  different 
machine/operating  system  combina¬ 
tions.  At  $1,000  it  is  the  most  expen¬ 
sive  compiler  we  reviewed.  The  lan¬ 
guage  supported  is  as  close  or  closer 
to  the  ANSI  standard  (depending  on 
which  one  you  read)  than  any  other 
compiler's.  It  supports  three  separate 
libraries — ANSI,  extended  ANSI  (the 
extensions  are  very  useful),  and 
Whitesmiths.  Whitesmiths  C  sup¬ 
ports  some  pretty  useful  "space  mod¬ 
ifiers.”  In  addition  to  the  standard 
near  and  far,  it  also  supports  a  port 
address  space  for  letting  variables 
point  at  I/O  ports.  The  major  missing 
features  have  got  to  be  excellent  code 
quality  and  a  speedy  library. 

The  documentation  is  complete  and 
includes  a  language  reference  man¬ 
ual.  The  three  libraries  are  described 
on  separate  library  pages  so  you 
won't  be  looking  at  a  function  that  is 
not  available  in  your  library.  Al¬ 
though  the  documentation  is  clearly 
sectioned  so  that  common  sections 
can  be  used  "as  is”  for  other  variations 
of  the  compiler,  this  is  not  the  impedi¬ 
ment  to  usefulness  that  it  could  be. 
The  manual  does  include  a  style  guide 
with  specific  suggestions  on  how  to 
write  portable  code.  Portable  code  has 
got  to  be  Whitesmiths  best  point,  sup¬ 
porting  C  for  CP/M,  VAXs,  PDP-lls, 
68000s,  and  IBM  mainframes. 

Source-level  debugging  is  provided 
for  in  a  unique  way.  You  compile 
your  source  for  debug,  and  when  you 
link  it,  the  source-level  debugger  is 
linked  in.  When  you  run  the  pro¬ 
gram,  the  debugger  is  invoked. 

Wizard  C 

Wizard  Software  Systems  was  a  new¬ 
comer  to  the  MS-DOS  C  compiler  mar¬ 
ket  when  our  review  appeared  last 
year,  but  its  compiler  was  neverthe¬ 
less  one  of  the  top  four  contenders.  Its 
strongest  point  was  its  extensive  er¬ 


ror  checking  and  lint  feature.  This 
year  we  received  a  beta-test  copy  of 
Wizard  C,  Version  3.0,  a  significantly 
enhanced  compiler.  Added  are  sev¬ 
eral  features  from  the  emerging  ANSI 
standard,  support  for  mixed-model 
programming,  and  an  improved  op¬ 
timizer  that  includes  an  algorithm 
that  automatically  allocates  register 
variables  if  you  do  not. 

Wizard  C,  Version  3.0,  supports  pro¬ 
gramming  in  nine  memory  models, 
with  three  floating-point-support  op¬ 
tions.  It  can  generate  code  for  80186 
and  80286  processors.  Code  generated 
for  the  80286  expects  to  be  run  in  the 
protected  mode  and  takes  full  advan¬ 
tage  of  32-bit  addressing,  so  it  cannot 
run  under  current  versions  of  MS- 
DOS.  In  addition  to  a  large  range  of 
optional  warning  messages,  the  Wiz¬ 
ard  compiler  offers  a  lint  mode  of 
compilation  that  performs  full  cross¬ 
checking  of  multiple  source  files.  The 
full  K  &.  R  language  is  implemented, 
plus  void,  enum,  signed,  const,  vola¬ 
tile,  structure  and  union  assignment, 
structure  and  union  pass/return, 
function  prototyping,  and  several 
other  ANSI  features. 

The  Wizard  C  compiler  comes  on 
four  disks  and  includes  the  source 
code  for  the  library.  The  compiler  it¬ 
self  is  four  passes,  but  a  cc  driver  pro¬ 
gram  is  supplied  that  accepts  wild¬ 
card  file  names  and  runs  all  passes 
plus  the  linker.  As  with  most  ven¬ 
dors,  Wizard  uses  the  Microsoft  ob¬ 
ject  format  and  linker.  The  compiler 
has  no  assembler  as  such,  although 
in-line  assembly  code  is  allowed — if 
you  want  to  link  to  separate  assem¬ 
bler  routines  or  do  in-line  assemby, 
you  will  need  your  own  Microsoft- 
compatible  assembler.  There  are  no 
batch  files  to  automate  the  installa¬ 
tion  process,  but  the  manual  on  pack¬ 
age  installation  and  usage  includes 
sections  describing  floppy-  and  hard¬ 
disk  setup. 

The  compiler  is  documented  in  a 
separate  manual  with  its  own  table  of 
contents  and  index.  The  copy  we  re¬ 
ceived  was  complete  and  well  orga¬ 
nized  and  included  a  quick-reference 
chart  listing  all  available  options  in 
one  place.  A  lot  of  options  are  avail¬ 
able — we  used  eight  on  the  command 
that  tries  to  generate  minimal  compile 
times.  There  are  four  optimization  op¬ 
tions,  one  of  which  specifies  that  the 
more  efficient  PL/M  calling  conven¬ 


tions  be  used  for  all  functions  not  tak¬ 
ing  a  variable  number  of  arguments. 

You  can  build  a  configuration  file 
that  contains  your  most  frequently 
used  command-line  options.  Toggle 
options  turned  on  in  the  configura¬ 
tion  file  can  be  turned  back  off  for  an 
individual  compile  by  repeating 
them  on  the  command  line.  The  con¬ 
figuration  file  may  be  in  the  current 
directory  or  in  any  directory  on  the 
DOS  path.  This  seems  like  a  more  flex¬ 
ible  and  powerful  approach  than  the 
use  of  environment  variables. 

The  documentation  for  Wizard  C 
consists  of  three  separate  manuals, 
typewritten  on  8.5  X  11-inch  paper, 
in  a  1-inch  ring  binder.  The  manuals 
we  received,  like  the  compiler,  were 
at  the  beta-test  stage,  and  we  found 
some  rough  edges.  The  1-inch  binder 
is  a  little  too  small  for  the  400  pages  it 
contains,  so  the  pages  tend  to  bind 
when  you  flip  around. 

The  first  manual,  a  reference  to 
compiler  installation  and  usage  is 
complete  and  well  organized,  includ¬ 
ing  a  table  of  contents  and  index.  It 
includes  a  section  on  compiler  diag¬ 
nostics,  with  a  paragraph  describing 
each  error. 

The  second  manual  is  a  complete 
language  reference  and  includes  a  ta¬ 
ble  of  contents  but  no  index.  This 
manual  is  extensive  compared  to 
those  that  most  vendors  provide,  but 
it  is  too  terse  to  serve  as  your  only 
reference  to  the  C  language.  There  is 
no  summary  of  differences  from  the 
K  &,  R  definition  of  C. 

The  third  manual  is  the  library  ref¬ 
erence  and  includes  a  table  of  con¬ 
tents  and  an  index.  The  function  defi¬ 
nitions  are  organized  in  Unix  fashion, 
with  no  examples  anywhere.  A  li¬ 
brary  summary  section  provides  a 
one-line  description  of  what  each 
function  does,  organized  by  catego¬ 
ry.  This  will  help  you  find  the  func¬ 
tion  that  does  what  you  want  more 
quickly,  but  it  does  not  serve  as  a 
quick  reference  to  the  library.  Wiz¬ 
ard  includes  a  set  of  screen  functions 
and  a  Unix  emulation  package  in  the 
library.  There  are  more  than  the  usu¬ 
al  number  of  DOS  interface  functions 
and  a  useful  section  in  the  overview 
that  lists  the  most  appropriate  library 
function  for  each  DOS  system  call. 
The  overview  does  not  contain  near¬ 
ly  enough  background  information 
on  buffered  and  unbuffered  I/O. 
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Hot  C 

WordTech  Systems  markets  a  com¬ 
piler  for  dBASE  III.  Recently  (by  the 
time  you  read  this),  it  has  started  to 
sell  a  C  compiler  imported  from  Hi¬ 
Tech  Software  of  Australia.  Word- 
Tech  is  calling  the  package  Hot  C  and 
is  apparently  marketing  it  primarily 
as  a  complement  to  its  dBASE  compil¬ 
er.  We  received  a  preliminary  ver¬ 
sion  of  the  package  for  review. 

Hot  C  allows  programming  in  the 
large/large-memory  model  and  can 
produce  programs  that  make  use  of 
an  8087.  It  does  not  include  a  sensing 
library,  so  a  program  that  uses  an 
8087  will  not  run  if  an  8087  is  not  pre¬ 
sent.  Hot  C  does  not  implement  bit 
fields,  but  void,  enum,  structure  as¬ 
signment,  and  structure  pass/return 
are  supported.  It  includes  a  symbolic 
(not  source-level)  debugger,  some¬ 
what  similar  to  the  Unix  debugger 
adb.  WordTech  claims  that  an  editor 
and  a  C  language  tutorial  will  be  in¬ 
cluded  with  the  final  package,  but 
they  were  not  available  when  we  re¬ 
ceived  the  package.  The  version  of 
the  compiler  we  received  included  a 
very  preliminary  copy  of  the  docu¬ 
mentation,  so  we  cannot  comment 
on  the  quality  of  the  package  you  will 
receive.  The  compiler  itself  comes  on 
two  disks,  with  the  source  for  the  li¬ 
brary  in  compressed  format. 

Hot  C  does  not  support  a  separate 
environment  variable  to  specify  the 
search  path  for  include  files,  as  do 
most  compilers.  It  does  support  an 
environment  variable  to  specify 
where  to  store  temporary  files  and 
where  to  find  the  compiler  passes. 
The  latter  option  is  not  optional  if  you 
have  a  hard  disk.  The  driver  program 
looks  for  the  compiler  on  drive  A:  if 
you  do  not  tell  it  otherwise — it  does 
not  scan  the  path  or  the  current 
directory!  Likewise,  drive  A:  is 
searched  if  the  preprocessor  cannot 
find  one  of  your  include  files  in  the 
current  directory  or  one  of  the  direc¬ 
tories  you  specify  with  -/  arguments 
on  the  command  line. 

The  preliminary  copy  of  the  Hot  C 
manual  we  received  had  several 
problems,  including  page  layout,  that 
we  assume  will  be  rectified  before 
WordTech  actually  starts  shipping. 
We  are  more  concerned  about  the 


contents  than  the  format.  Our  copy 
had  no  index  or  table  of  contents,  and 
most  of  the  manual  consists  of  a  series 
of  appendices.  There  are  also  fre¬ 
quent  references  to  a  Z80  version  of 
the  compiler  that  may  not  even  be 
available  in  this  country. 

The  first  appendix  is  a  detailed  list 
of  differences  from  the  K  &  R  C  "stan¬ 
dard.”  It  is  organized  to  correspond 
to  the  Reference  Manual  section  of  K 
&  R  on  a  point-for-point  basis  and  is 
complete.  This  is  the  right  way  to 
present  this  information. 

The  library  reference  is  patterned 
after  the  Unix  model,  with  brief  text 
describing  several  functions  under  a 
single  heading  and  no  examples.  This 
kind  of  format  is  difficult  to  use,  espe¬ 
cially  in  the  absence  of  an  index,  be¬ 
cause  functions  are  not  in  alphabeti¬ 
cal  order.  Related  functions  are  cross- 
referenced,  however,  and  there  is  a 
quick-reference  list  of  functions  or¬ 
ganized  by  category.  Sometimes  in¬ 
formation  is  missing — for  instance, 
the  DOS  interrupt  function  msdos- 
C)t(  )  returns  a  long  containing  regis¬ 
ters  cy  and  dy  returned  from  DOS,  but 
whether  cfy  or  cy  is  in  the  high-order 
word  of  the  long  result  is  not  men¬ 
tioned  (dy  is). 

Summary 

We  promised  to  draw  some  conclu¬ 
sions  about  these  results,  based  on 
both  what  we  have  written  and  what 
we  could  not  write  because  of  time 
and  space  limitations. 

Datalight's  products  are  the  best 
value  in  MS-DOS  C  compilers  today. 
At  $60  for  a  full  K  &  R  compiler  (Data- 
light  C),  you  get  a  fast-compiling, 
easy-to-use,  good  code-quality  com¬ 
piler.  And  it  is  compatible  with  Lat¬ 
tice's  calling  convention  to  boot.  For 
$99  total  (for  the  Datalight  C  Develop¬ 
er’s  Kit),  you  can  add  three  more 
memory  models  and  the  source  code 
for  the  entire  run-time  system. 

Microsoft's  compiler  is  the  best  MS- 
DOS  C  development  environment 
value  today.  At  $395  list  (less  than 
$300  discounted),  you  get  everything 
you  could  want  (except  an  editor  and 
assembler)  to  develop  virtually  any 
kind  of  program  conceivable.  A 
make  facility,  the  compiler,  a  linker, 
and  a  debugger  allow  generation  of 
high-quality,  unlimited-size  pro¬ 
grams  with  almost  total  flexibility. 

Wizard's  is  the  best  compiler  to¬ 


day.  What  it  does  have  is  library 
source  for  a  very  large  library,  good 
documentation,  excellent  support, 
and  lint. 

Our  choice  if  we  could  make  our 
own?  We  would  take  Wizard's  com¬ 
piler  (with  the  huge  keyword  and 
MetaWare’s  pragmas  added)  and 
Microsoft's  library  (with  source), 
documentation,  and  debugger  at  Da¬ 
talight's  price. 

We  are  also  strongly  attracted  to 
MetaWare’s  High  C,  Manx  Aztec  C  and 
DeSmet  C  by  C  Ware.  High  C  is  the 
most  flexible  compiler  available  (if 
you  need  it,  High  C  has  got  it),  has  very 
complete  documentation,  and  has  ab¬ 
solutely  the  best  support.  Code  quality 
is  very  good,  the  compiler  and  library 
are  fully  compatible  with  the  emerg¬ 
ing  ANSI  standard,  and  compiler  diag¬ 
nostics  are  the  best.  You  can  move 
code  between  this  compiler  and  cor¬ 
responding  compilers  for  the  IBM 
RT/PC,  the  Atari,  IBM  mainframes, 
DEC  VAX,  and  68000  and  32000  series 
processors.  However,  it  is  a  slow  com¬ 
piler,  needs  lots  of  room,  costs  $495, 
and  does  not  include  full  library 
source  or  a  debugger. 

Aztec  C  does  include  full  library 
source  and  a  source-level  debugger. 
The  code  quality  is  good  with  prom¬ 
ises  to  get  better  in  the  next  release.  It 
includes  an  editor,  make,  assembler, 
and  linker,  and  the  linker  can  locate, 
allowing  easy  ROM  development. 
Moving  code  across  different  micros 
is  easy  because  Manx  has  compilers 
for  Apple,  CP/M,  MS-DOS,  the  Amiga, 
the  Macintosh,  and  Atari  computers. 
But  the  documentation  is  difficult  to 
use,  the  price  is  $495,  and  the  code 
quality,  although  good,  is  not  among 
the  best  anymore. 

DeSmet  C  is  another  value-packed 
system,  including  an  editor,  assem¬ 
bler,  and  linker.  Library  source,  a 
good  source-level  debugger,  speedy 
compiles,  and  a  low  price  distinguish 
this  compiler  from  the  others.  Minor 
improvements  in  the  library,  debug¬ 
ger,  code  generator,  and  manual 
would  make  this  package  hard  to 
beat. 

DOJ 

(Listings  begin  on  page  104.) 
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Listing  One  (text  in  July) 

Screen  #  0 

(  Support  for  Intel/Lotus  Expanded  Memory  13:16  08/14/85  > 

This  file  contains  sane  simple  definitions  to  allocate 
Expanded  Memory  space  and  use  it  for  word  arrays. 

The  usage  within  a  PC/FORTH  program  would  follow  the  sequence 
EM-OPEN  (  in  program  initialization  code  ) 

...  d  @EM  ...  (  various  array  accesses  ) 

EM-CLOSE  (  de-al locate  memory  ) 

If  you  fail  to  issue  the  EM-CLOSE,  the  Expanded  Memory  pages 
will  not  be  de-allocated  and  other  programs  may  not  be  able 
to  obtain  sufficient  memory. 

Copyright  (c)  1985  Ray  Duncan,  Laboratory  Microsystems  Inc. 

P.  0.  Box  10430,  Marina  del  Rey,  CA  90295 


Screen  #  1 

(  arrays  &  variables  13:16  08/14/85  ) 

FORTH  DEFINITIONS  HEX 

(  guaranteed  device  name  for  ) 
CREATE  em_name  ,"  EMMXXXX0"  0  C,  (  Expanded  Memory  Manager  ) 

67  CONSTANT  em_int  (  hex  interrupt  number  for  EMM  ) 

— > 


Screen  #  2 

(  test  for  EMM  device  driver  header  method  14:02  08/14/85  ) 

(  -  status  ;  =0  if  EMM  present,  -1  if  not  present  ) 

(  compares  name  in  presumed  device  driver  to  guaranteed  name  ) 


CODE  ems? 

SI 

PUSH 

DI, 

DI  XOR  ES,  DI 

MOV 

(  pick  up  EMM 

DI, 

#  em  int  4  *  MOV 

(  int  vector 

ES: 

:  ES,  2  [DI]  MOV 

DI, 

# 

0A  MOV 

SI, 

#  em  name  MOV 

cx. 

# 

8  MOV 

CLD  REPZ  BYTE  CMPS 

( 

compare  driver  name 

SI 

POP 

1$ 

JNZ  ( 

jump 

if  EMM  driver  found 

AX, 

#  0  MOV  2$  JMP 

( 

return  FALSE  flag 

1$: 

AX, 

#  -1  MOV 

1 

[  return  TRUE  flag 

2$: 

AX 

PUSH  NEXT,  END- 

■CODE 

— > 


Screen  #  3 

(  get  EMM  frame,  EMM  free  pages  14:02  08/14/85  ) 

( - segment  ;  get  segment  of  the  EM4  page  frame  ) 

(  segment  is  returned  as  0  if  function  failed  ) 

CODE  em_frame  AH,  #41  MOV 
em_int  INT 

AH,  AH  OR  1$  JZ  BX,  #  0  MOV 
1$:  BX  PUSH  NEXT,  END-CODE 

(  returns  number  of  EMM  pages  which  are  currently  available  ) 

(  -  free_pages  total_pages  ) 

CODE  emjpages  AH,  #  42  MOV  em_int  INT 

AH,  AH  OR  1$  JZ  DX,  #  0  MOV  BX,  DX  MOV 
1$:  BX  PUSH  DX  PUSH  NEXT,  END-CODE 

— > 


Screen  #  4 

(  open  ETW  Sc  allocate  pages  15:45  08/14/85  ) 

(  get  an  ENW  handle  and  allocate  EMM  logical  pages  to  it  ) 

(  pages  -  handle  |  0  ) 

CODE  em_open  BX  POP 

AH,  #  43  MOV  em_int  INT 

AH,  AH  OR  1$  JZ  (  jump  if  no  error  ) 

DX,  #  0  MOV  (  if  error  return  0  ) 

1$:  DX  PUSH 

2$:  NEXT,  END-CODE 

— > 

Screen  #  5 

(  memory  mapping  16:20  08/14/85  ) 


(continued  on  page  72) 
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Listing  One  (Listing  continued) 


(  map  an  EMM  logical  page  owned  by  handle  to  a  physical  page  ) 
(  logical_page  physical_page  handle  -  status;  =0  if  ok  ) 


CODE  emjnap 


1$: 

2$: 


DX  POP  (  handle  ) 

AX  POP  (  physical  page  #  ) 

BX  POP  (  logical  page  #  ) 

AH,  #  44  MOV  em_int  INT 
AH,  AH  OR  1$  JZ  (  jump  if  no  error  ) 
AH,  AL  XCHG  (  AL  :=  error  code  ) 

AH,  #  0  MOV  2$  JMP 

AX,  #  0  MOV  (  return  0  if  no  error  ) 
AX  PUSH  NEXT,  END-CODE 


VARIABLE  $EM_PID  (  handle  for  FORTH  from  EM  manager  ) 

VARIABLE  $EM_FRAME  (  segment  of  EM  paging  frame  ) 

(  dl  -  d2  ;  quick  double  number  multiplies  > 


:  D2* 

2DUP  D+  ; 

:  D4* 

D2*  D2*  ; 

:  D8* 

D4*  D2*  ; 

(  d - 

;  compile  a  double  number 

:  D, 

HERE  2!  4  ALLOT  ; 

— > 

Screen  #  6 

(  release  page  allocation  16:35  08/14/85  ) 


(  release  an  EMM  handle  and  all  logical  pages  allocated  to  it 
(  handle  -  status  ) 

CODE  em_close  DX  POP  AH,  #  45  MOV 

em  int  INT 


AH,  AH  OR  1$  JZ  (  jump  if  no  error 
AH,  AL  XCHG  (  AL  :=  error  code 
AH,  #  0  MOV  2$  JMP 

1$:  AX,  #  0  MOV  (  return  0  if  no  error 
2$:  AX  PUSH  NEXT,  END-CODE 


) 


) 

) 

) 


— > 


Screen  #  8 

(  EM  array  alignment,  EM-CLOSE  14:02  10/04/85  ) 

(  -  ;  align  EM  on  2-byte  boundary  for  single  int  array  ) 

:  WALIGN  $EM_USED  2@  OVER  1  AND  0  D+ 

$EM_USED  2!  ; 

(  -  ;  release  Expanded  Memory  allocation  ) 

:  EM-CLOSE  $EM_PID  @  DUP  0=  ABORT"  EM  not  opened" 

em_close  ABORT"  Can't  release  memory" 

$EM_PID  OFF  ; 


Screen  #  7 

(  EM  variables  &  misc  defs  11:13  10/03/85  ) 

2 VARIABLE  $EM_USED  (  bytes  of  EM  assigned  to  arrays  ) 


Screen  #  9 

(  EM-OPEN  10:01  10/04/85  ) 

(  -  ;  establish  availability  of  Expanded  Memory  &  allocate  ) 

:  EM-OPEN  $EM_PID  @  IF  EM-CLOSE  THEN 

ems?  ABORT"  Memory  manager  not  installed" 
em_frame  DUP  0=  ABORT"  EM  Frame  not  valid" 
$EM_FRAME  !  (  save  EM  paging  segment  ) 

em_pages  SWAP  DROP  4000  UM* 

$EM_USED  2@  D< 

ABORT"  Insufficient  expanded  memory  available" 
$EM_USED  20  4000  UM/MOD  SWAP 

IF  1+  THEN  (  round  up  to  next  page  ) 

em_open  DUP  0=  ABORT"  Can't  get  EMM  handle" 

$EM  PID  !  ; 


Screen  #  10 

(  EM-ARRAY  word  array  12:49  10/03/85  ) 


(  d_cells - ;  compiling  ) 

(  d_cell#  em_daddr  ;  executing  ) 

:  EM-ARRAY  CREATE  WALIGN  (  word  align  EM  ptr  ) 

2DUP  1.  D-  D,  (  highest  cell  #  ) 

D2*  (  *2  for  #  of  bytes  needed  ) 

$EM_USED  2@  (  get  current  EM  offset  ) 

2DUP  D,  (  save  it  ) 

D+  $EM_USED  2!  (  update  EM  offset  ) 

DOES>  DUP  >R  2@  (  get  #  of  cells  declared  ) 

20VER  DU<  ABORT"  Index  out  of  bounds" 

D2*  (  cell#  *2  for  offset  ) 

R>  4  +  20  D+  ;  (  +  base  offset  ) 


Screen  #  11 

(  @EM  ! EM  13:05  10/03/85  ) 

(  em_daddr  -  n  ) 

:  @EM  4000  UM/MOD  0  (  pa_offs  log_pa  phys_pa  ) 

$EM_PID  @  emjnap  ABORT"  @EM  mapping  error" 
$EM_FRAME  @  SWAP  @L  ; 

(  n  em_daddr - ) 

:  !  EM  4000  UM/MOD  0  (  pa_offs  log  pa  phys_pa  ) 

$EM_PID  @  emjnap  ABORT"  !  EM  mapping  error" 
$EM_FRAME  0  SWAP  !L  ; 

DECIMAL  CR  CR  . (  EMM  management  routines  loaded.  ) 

CR  7WORKSPACE  U.  . (  bytes  left  in  dictionary.  )  CR  CR 


End  Listing 
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Listing  One  (Text  begins  on  page  10.) 


Listing  One 

;DeSmet  function  isqrt ( source) ; 

...source  is  a  long  integer  (32  bit)... 

.•Returns  square  root  of  source  in  ax,  using  Newton's  method;  see  Scanlon's 
; 80 86  book  for  similar  function  (Scanlon's  is  not  sufficiently  general,  and  has 
;an  error) . . . 


REGISTER  USAGE 


cx:bx  ...stores  copy  of  32-bit  source  throughout... 
di  . ..  "last ''  estimate  of  isqrt  (source)  ..  . 

si  ...current  estimate  of  isqrt  (source) .. . 

dxrax  ...used  to  divide  source  by  di . . . 


cseg 

public  isqrt_ 
isqrt_: 


push  bp 
mov  bp, sp 

mov  bx,  (bp+41  .’Store  a  copy  of  source  in  cx:bx; 

mov  cx,  [bp+6]  ;cx:bx  preserved  till  almostdone . . . 

Start  block  to  determine  initial  estimate;  base  estimate  on  most - 

significant  non-zero  byte  of  cx :bx - - - 

cmp  ch,  0  .’Note  46341  covers  largest  positive 

je  test_cl  ;long  that  most  compilers  will  pass. 


mov  di, 46341 
jmp  load_si 

cmp  cl,0 
je  text_bh 
mov  di,2896 
jmp  load_si 


;If  you  use  32-bit  unsigned,  replace 
.-with  65535,  and  if  cx>-FFFEH,  jump 
;out  and  set  result-  65535. 


cmp  bh,0 
je  its_bl 
mov  di, 181 
jmp  load_si 


its_bl:  mov  di,8 

load_si:  mov  si,di 

■End  block  to  determine  initial  estimate- 


; - Begin  loop  to  refine  the  estimate - 

refine:  mov  dx, cx  ;Load  dx:ax  pair  with  source  in  prep 

mov  ax, bx  ;for  divide  by  di-estimate... 

div  di 

; - Block  to  average  quotient  and  last  estimate - 

3hr  ax, 1  ; We  can't  just  add  di,ax  then 

adc  di,0  ;shr  di,  1  because  sum  of  di  and  ax 

shr  di, 1  ;may  exceed  65535... 

sub  si,di 
jz  almostdone 
cmp  si,l 
je  almostdone 
cmp  si,  — 1 
je  almostdone 
mov  si,di 

jmp  refine 

; - End  loop  to  refine  the  estimate - 

almostdone:  mov  ax,di 

raul  di 
sub  bx,  ax 
sbb  cx, dx 
jns  done 
dec  di 

done:  mov  ax, di 

mov  sp,  bp 
pop  bp 
ret 

/*  Test  driver  for  isqrt ()...  */ 

main{) 

{ 

long  start, i, NumSqrts; 
print  f  (  "ENTER  start:  ''); 
scanf  (  "%D  ' ' ,  istart)  ; 
print f  (  "ENTER  NumSqrts:  ''); 
scanf  (  "%D ' ' ,  iNumSqrts) ; 

printf ( ' 'isqrt (%D) -  %u\n* 1 , start,  isqrt ( start) ) ; 
put char ( 1  \ 00 7  ' ) ; 

for (i-start; i<start+NumSqrts; ++i) isqrt (i) ;  /*  Remove  this  isqrt ()  to  find  */ 
putchar ( *\007 ' ) ;  /*  time  taken  by  loop  itself...*/ 

} 


,’Obtain  difference  betw.  old  (si) 
;and  new  estimates;  if  0,  we're 

/almost  done... Else  if  diff.  is 
;1  or  -1  we're  almost  done... 


.•Store  current  value  di  in  si  as 
;"old'*  estimate  for  next  iteration. 


.•Check  to  see  if  estimate*estimate 
;is  less  than  cx:bx;  this  step  is 
;for  fussbudgets  who  demand  final 
.•integer  sqrt  be  <  real  sqrt;  ditch 
;it  and  save  approx.  60  clocks... 
;If  product  >cx:bx,  subtract  1... 
;DeSmet  looks  for  result  in  ax.  .  . 


/*  Another  short  driver;  this  one  better  for  verifying  algorithm  */ 

main() 

( 

long  source; 
unsigned  result; 

printf  ( "ENTER  #  for  sqrt;  negative  exits\n''); 
whi le (printf ( * 'ENTER  ♦  :  ' ' ) , scanf (  "%D‘ 1 , t source) , 30urce>-OL) ( 
result-isqrt (source) ; 

printf  (  "result-  SQRT  ( %D)  -  %u\n  source,  result) ; 

printf ( '  'result ‘result-  %D\n' ' , ( (long) result ) • ( (long) result) ) ; 

printf ( ' ' ( result +1 ) * (result +1 ) -  %D\n\n' ' , (result+lL) • ( result+lL) ) ; 

) 

1  End  Listing  One 

Listing  Two 

Listing  Two  Bit-Shifting  Method  (Slower) 

;DeSmet  function  Isqrt ();  takes  a  long  (32-bit)  integer  as  an  argument,  returns 
; a  short  (16-bit)  integer  square  root.  Function  result  returned  in  ax. 

.•Modified  after  68000  code  published  in  DDJ  #109,  Nov.  1985,  p.  90.  Comments 

.•give  roughly  analogous  68000  instructions;  correspondence  with  68000  registers 
;  is : 

;  DO  -  sp:si (initially  holds  argument) 
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Listing  Two  (Listing  continued,  text  begins  on  page  10.) 


;  D1  -  dx:di (Error  term) 

;  D 2  -  ax  (Running  estimate) 

:  D3  -  bx  (High  bracket;  may  exceed  16  bits  on  last  iteration) 

;  D4  -  cx  (Loop  counter) 

.-Note  sp  is  used  as  a  general  register,  so  can't  push  or  pop  between 
;  "raov  bp, sp11  and  '  'mov  sp,bp' 1 . . .also,  we  must  disable  DOS's  timer 
.•interrupt,  because  it  manipulates  the  stack  every  55  milliseconds... 

cseg 

public  lsqrt_ 

lsqrt_:  push  bp 

mov  bp, sp 

; - Now  can  address  stack;  4-byte  argument  starts  at  bp +4 - 

cli  .-Clear  interrupts  (lock  out)... 


mov  si, word 
mov  sp,  word 

(bp+4 ) 
[bp+6] 

.•Place  argument  in  sp:si-  ''DO1'... 

xor  di,di 
mov  dx,di 
mov  ax,  di 
mov  cx, 16 

.■Zero  "Dl ' '  and  "D21'... 

; Loop  counter  cx-  '  'D4  1 '  . .  . 

sqrtl : 

shl  si,l 
rcl  sp, 1 
rcl  di,l 
rcl  dx, 1 

;  "asl.l  #1,  DO  * '  . .  . 

;  "roxl.l  *1,D1"  . .  . 

shl  si,l 
rcl  sp, 1 
rcl  di,l 
rcl  dx, 1 

.■Repeat  shift  and  rotate... 

shl  ax, 1 

;  "asl.l  #1, D2 ' ' .  . . 

mov  bx, ax 

; * 'move . 1  D2, D3 1 • . .  . 

shl  bx, 1 
jc  is_carry 

cmp  dx, 0 
jb  sqrt2 
ja  pastl 
cmp  di,bx 
jbe  sqrt2 

;  "asl.l  #1,  D3  1  • .  .  . 

;Jump  out  of  loop  if  new "D3 ' '  exceeds 
; 16  bits  (may  happen  on  last 
; iteration) . . . 

;  "crap.l  D3,D1 '  '  .  .  . 

;  "bis  sqrt2' 1  . .  . 

pastl : 

inc  ax 
inc  bx 

;  "addq.l  #1,D2' '  . .  . 

:  "addq.l  *1,D3' ' . . . 

sub  di,bx 
sbb  dx, 0 

;  "sub.  1  D3,  Dl '  '  .  . . 

sqrt2 : 

loop  sqrtl 

"dbra  D4,  sqrtl  *  1 .. . 

jmp  past3 

,-Skip  'is_carry'  block  if  we  finished 
;loop  through  16  iterations  (no  jc, 

;"D3''  stayed  <17  bits)... 

is_carry; 

past2 : 

cmp  dx, 0001H 
ja  past2 
jb  past3 
cmp  di,bx 
jbe  past3 

inc  ax 

;If  we  got  here,  there  was  a  carry 
;for  shl  bx,l  on  last  iteration  of 
;  loop;  compare  upper  word  "Dl ' ' 

.•against  upper  word  "D31',  which  is 

;now  0001H;  then  compare  lower  words 
; of  "Dl"  and  "D3‘  '.  .. 

;  "addq.l  #1,D2‘  ' .  .. 

past3 : 

sti 

mov  sp,  bp 
pop  bp 

.•Restore  interrupts.  .  . 

.•Restore  frame,  function  result 
;is  already  in  ax.... 

ret 

End  Listing  Two 

Listing  Three 


Listing  Three 


Integer  Square  Root  (32  to  16  bit) . 

*’ 

(Exact  method,  not  approximate) . 

Call  with: 

DO.L  -  Unsigned  number. 

Returns: 

DO.L  -  SQRT(DO.L) 

Notes:  Result  fits  in  DO.W,  but  is  valid  in  longword.  * 

Takes  from  122  to  1272  cycles  (including  rts) .  * 

Averages  610  cycles  measured  over  first  65535  roots.  * 
Averages  1104  cycles  measured  over  first  500000  roots.* 

.globl  lsqrt 

* 

Cycles 

lsqrt 

tst.l  dO  (4) 

;  Skip  doing 

zero . 

beg. s  done 

(10/8) 

cmp. 1  *$10000, dO 

(14) 

If  is  a  longword,  use  the  long  routine. 

bhs.s  glsqrt 

(10/8) 

cmp.w  #625, dO 

(8) 

Would  the  Bhort  word  routine  be  quicker? 

bhi.s  gsqrt 

(10/8) 

No,  use  general  purpose  word  routine. 

• 

• 

Otherwise  fall  into  special  routine. 

*  For  speed,  we  use  three  exit  points. 

*  This  is  cheesy,  but  this  is  a  speed-optimized  subroutine! 
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Listing  Three  (Listing  continued,  text  begins  on  page  10.) 


Faster  Integer  Square  Root  (16  to  8  bitj  .For  small  arguments.  * 

(Elxact  method,  not  approximate)  .  * 

Call  with:  8 

DO . W  -  Unsigned  number.  * 

Returns:  * 

DO . W  -  SQRT(DO.W)  * 

Notes:  Result  fits  in  DO.B,  but  is  valid  in  word.  * 

Takes  from  72  (dO-1)  to  504  (dO-625)  cycles  * 

(including  rts)  .  * 

Algorithm  supplied  by  Motorola.  * 


Use  the  theorem  that  a  perfect  square  is  the  sum  of  the  first 
sqrt(arg)  number  of  odd  integers. 


• 

Cycles 

move.w  dl,-(sp) 

(8) 

move.w  #-l,dl 

(8) 

qsqrtl 

addq.w  #2,dl 

(4) 

sub.w  dl,dO 
bpl  qsqrtl  (10/8) 

(4) 

asr.w  #l,dl 

(8) 

move.w  dl,d0 
move.w  (sp)+,dl  (12) 

(4) 

done 

rts 

(16) 

Integer 

Square  Root  (16  to  8  bit). 

(Exact 

method,  not  approximate) . 

Call  with: 

DO . W  —  Unsigned  number. 

Returns 

DO.L  -  SQRT(DO.W) 

Uses: 

D1-D4  as  temporaries  — 

Dl  -  Error  term; 

D2  -  Running  estimate; 

D3  -  High  bracket; 

D4  -  Loop  counter 

Notes : 

Result  fits  in  DO.B,  but  is  valid  in  word. 

Takes  from  512  to  592  cycles  (including  rts) . 

Instruction  times  for  branch-type  instructions 
listed  as  (X/Y)  are  for  (taken/not  taicen)  . 

*  Cycles 

gsqrt  movem.w  dl-d4,-(sp)  (24) 

move.w  #7,d4  (8)  ;  Loop  count  (bits-l  of  result), 

clr.w  dl  (4)  ;  Error  term  in  D1 . 


sqrtl 

clr.w  d2  (4) 
add.w  d0,d0 

(4) 

addx.w  dl,dl 

(4) 

add.w  d0,d0 

(4) 

addx.w  dl,dl 

(4) 

add.w  d2,d2 

(4) 

move.w  d2,d3 

(4) 

add.w  d3,d3 

(4) 

cmp.w  d3,dl 

(4) 

bls.s  sqrt2 

(10/8) 

addq.w  #l,d2 

(4) 

addq.w  #l,d3 

(4) 

sub.w  d3,dl 

(4) 

sqrt2 

dbra  d4, sqrtl 

(10/14) 

move.w  d2,d0 

(4) 

movem.w  (sp)+,dl-d4 

(28) 

rts 

(16) 

;  Get  2  leading  bits  a  time  and  add 
;  into  Error  term  for  interpolation. 

;  (Classical  method,  easy  in  binary) . 

;  Running  estimate  *  2. 


;  New  Error  term  >2*  Running  estimate? 
;  Yes,  we  want  a  ' 1 '  bit  then. 

;  Fix  up  new  Error  term. 

;  Do  all  8  bit-pairs. 


Integer  Square  Root  (32  to  16  bit)  . 

(Exact  Method,  not  approximate) . 

Call  with: 

DO.L  -  Unsigned  number. 

Returns: 

DO.L  -  SQRT(DO.L) 

Uses:  D1-D4  a3  temporaries  — 

Dl  -  Error  term; 

D2  -  Running  estimate; 

D3  -  High  bracket; 

D4  -  Loop  counter . 

Notes:  Result  fits  in  DO.W,  but  is  valid  in  longword 

Takes  from  1080  to  1236  cycles  (including  rts.) 

Two  of  the  16  passes  are  unrolled  from  the  loop  so 
quicker  instructions  may  be  used  where  there  is  no 
danger  of  overflow  (in  the  early  passes) . 

Instruction  times  for  branch-type  instructions 
listed  as  (X/Y)  are  for  (taken/not  taken) . 
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. 

* 

Cycles 

glsqrt 

movera.i  dl-d4 , 

(sp)  (40) 

moveq  #13, d4 

(4) 

;  Loop  count  (bits-1  of  result) . 

raoveq  #0,dl 

(4) 

;  Error  terra  in  Dl . 

raoveq  #0,d2 

(4) 

lsqrt 1 

add. 1  dO,  dO 

(8) 

;  Get  2  leading  bits  a  time  and  add 

addx.w  dl,dl 

(4) 

;  into  Error  term  for  interpolation. 

add . 1  dO.dO 

(8) 

;  (Classical  method,  easy  in  binary) . 

addx.w  dl,dl 

(4) 

add . w  d2,d2 

(4) 

;  Running  estimate  *  2. 

move . w  d2,d3 

(4) 

add . w  d3,d3 

(4) 

cmp.w  d3,dl 

(4) 

bis. 3  lsqrt2 

(10/8) 

;  New  Error  term  >  2*  Running  estimate? 

addq.w  #l,d2 

(4) 

;  Yes,  we  want  a  '1*  bit  then. 

addq.w  #l,d3 

(4) 

;  Fix  up  new  Error  terra. 

sub.w  d3,dl 

(4) 

lsqrt2 

dbra  d4,lsqrtl 

(10/14)  ; 

Do  first  14  bit-pairs. 

add. 1  dO,  dO 

(8) 

;  Do  15-th  bit-pair. 

addx.w  dl,dl 

(4) 

add.l  dO,dO 

(8) 

addx.l  dl,  dl 

(8) 

add.w  d2,d2 

(4) 

raove.l  d2,d3 

(4) 

add.w  d3,d3 

(4) 

cmp .1  d3 , d 1 

(6) 

bis. a  lsqrt3 

(10/8) 

addq.w  ♦l/d2 

(4) 

addq.w  #l,d3 

(4) 

sub.l  d3,dl 

(8) 

lsqrt3 

add.l  dO, dO  (8) 

;  Do  16-th  bit-pair. 

addx.l  dl,dl 

(8) 

add.l  dO, dC  : 

(8) 

addx.l  dl,dl 

(8) 

add.w  d2,d 2 

(4) 

raove.l  d2,d3 

(4) 

add.l  d3,d3 

(8) 

cmp.l  d3,dl 

(6) 

bis. s  l8qrt4 

(10/8) 

addq.w  #l,d2 

(4) 

lsqrt 4 

raove.w  d2,d0 

(4) 

raovera. 1  (3p) +,dl- 

d4 

(44) 

rts 

(16) 

end 

Listing  Four 

Listing 

Four 

Integer  Square  Root 

(32  to  16 

bit) .  * 

(Newton-Raphson  method). 

Call  with: 

DO.  L  - 

Unsigned  number. 

Returns: 

DO. L  -  SQRT (DO. L) 

Notes:  Result  fit3 

in  DO . W, 

but  is  valid  in  longword.  * 

Takes  from  338  cycles 

(1  shift,  1  division)  to  * 

1580  cycles 

(16  shifts,  4  divisions)  (including  rts).* 

Averages 

854 

cycles  measured  over  first  65535  roots.  * 

Averages 

992 

cycles  measured  over  first  500000  roots.  • 

.globl  lsqrt 

* 

Cycles 

lsqrt 

movem.l  dl-d2,-(sp) 

(24) 

;  Set  up  for  guessing  algorithm. 

raove.l  d0,dl 

(4) 

beq.s  return 

(10/8) 

;  Don't  process  zero. 

moveq  #l,d2 

(4) 

guess 

cmp.l  d2,dl 

(6) 

;  Get  a  guess  that  is  guaranteed  to  be 

bis. 8  newton 

(10/8) 

;  too  high,  but  not  by  much,  by  dividing  the 

add.l  d2,d2 

(8) 

;  argument  by  two  and  multiplying  a  1  by  2 

lsr.l  #1,  dl 

(10) 

;  until  the  power  of  two  passes  the  modified 

bra . 3  guess 

(10) 

;  argument,  then  average  these  two  numbers. 

newton 

add.l  dl , d2 

(8) 

;  Average  the  two  guesses. 

lsr.l  # 1 , d2 

(10) 

;  Generate  the  next  approximation ( s) 

raove.l  d0,dl 

(4) 

divu  d2, dl  (140) 

;  via  the  Newton-Raphson  method. 

bvs . s  done  ( 10/8 ) 

;  Handle 

out-of-range  input  (cheats  1) 

cmp .  w  d  1 ,  d2 
bis  .s  done  (10/8) 

(4) 

;  Have  we  converged? 

swap  dl 

(4) 

;  No,  kill  the  remainder  so  the 

clr.w  dl  (4) 

;  next  average  comes  out  right. 

swap  dl 

(4) 

bra. s  newton 

(10) 

done 

clr.w  dO  (4) 

;  Return 

a  word  answer  in  longword. 

swap  dO 

(4) 

raove.w  d2,d0 

(4) 

return 

raovera.  1  (sp)+,dl- 

d2 

(28) 

rts 

(16) 

•nd 

End  Listings 
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Listing  On©  (Text  begins  on  page  20.) 

Listing  1  —  tree.h 

1  typedef 

int 

‘TREE;  /*  Dummy  typedef  for  a  tree.  */ 

3  int 

delete 

(  TREE**,  LEAF*,  int (*) ()  ); 

4  LEAF 

♦insert 

(  TREE**,  LEAF*,  int (*) ()  ); 

5  LEAF 

♦find 

(  TREE*  ,  LEAF*,  int (*) ()  ); 

7  void 

tprint 

(  TREE*  ,  int  (*)  {) ,  FILE*  )  ; 

9  LEAF 

♦talloc 

(  int  ) ; 

10  void 

tfree 

(  LEAF*  ); 

11  void 

freeall 

(  TREE**  ); 

End  Listing  One 

Listing 

Two 

Listing  2  —  test.c 

1  #include  <stdio 

.h> 

3  typedef 

struct 

int  key;  }  LEAF; 

5  iinclude  "tree. 

h“  /*  LEAF  must  be  defined  before  tree.h  is  ((included 

*/ 

9  prnt (  stream,  p 

) 

10  FILE 

♦stream 

11  LEAF 

*p; 

12  t 

13 

/* 

Print  routine  needed  by  tprint () .  Should  always  print 

14 

* 

the  same  number  of  characters.  When  p  ==  0  it  should 

15 

* 

print  blanks. 

16 

*/ 

17 

18 

fprintf(  stream,  p  ?  "%2d"  :  "  ",  p->key  ); 

19  ) 

20 

22 

23  icmp(  nl,  n2  ) 

/*  Comparison  routine  for 

*/ 

24  LEAF 

♦nl,  *n2;  /*  insert  ()  to  use. 

*/ 

25  ( 

26 

return  ( 

nl->key  -  n2->key  ) ; 

27  } 

28 

29  dcmp(  key,  n2  ) 

/*  Comparison  routine  for 

*/ 

30  LEAF 

*n2; 

/*  delete ()  and  find()  to  use. 

*/ 

31  ( 

32 

return  ( 

key  -  n2->key  ) ; 

33  t 

34 

. 

/ 

36 

37  docmd (  cmd,  n  ) 

38  { 

39 

static 

TREE  *root  =  NULL; 

40 

LEAF 

*p,  *p2; 

41 

42 

switch ( 

cmd  ) 

43 

( 

44 

case  'd' 

45 

if(  (delete (Sroot,  (LEAF  *)  n  ,  dcmp)  ) 

46 

fprintf (stderr,  "Node  NOT  in  tree\n“); 

47 

break; 

48 

49 

case  'f' 

50 

if (  p  =  find(root,  (LEAF  *)  n,  dcmp)  ) 

51 

fprintf (stderr,  "Node  %d  found\n",  p->key  ); 

52 

else 

53 

fprintf (stderr,  "Node  NOT  found\n"  ) ; 

54 

break ; 

55 

56 

case  '  i 

57 

if (  ! (p  =  talloc (si zeof (LEAF) ) )  ) 

58 

fprintf (stderr,  "Out  of  memory. \n"  ); 

59 

else 

60 

{ 

61 

p->key  =  n; 

62 

if(  p2  =  insert (sroot ,  p,  icmp)  ) 

63 

f 
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64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80  } 
81 

82  /* 
83 


fprintf  (stderr,  "%d  already  in  tree\n",  p2->key) ; 
tfree  (  p  ) ; 

} 

} 

break ; 


case  ' a ' : 

freeall  (  &root  ) ; 
break; 

case  'q‘: 

exit (0)  ; 

} 

t print (  root,  prnt,  stdout  ); 
printf ("\n") ; 


*/ 


84  main(argc#  argv) 

85  char  **argv; 


86  { 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 

103 

104 

105  } 


/*  Assemble  a  tree,  first  get  commands  from  the  command  line 

*  until  these  are  exhauseted,  then  get  commands  from  the 

*  keyboard. 

*/ 


char  buf [128] ; 

for(  ++argv;  — argc  >  0  ;  ++argv  ) 

docmd(  **argv,  atoi  (*argv  +1)  ); 

printf ("commands  are:  iN  -insert  node  N  into  tree\n") ; 
printf ("  dN  -delete  node  N\n"); 

printf ("  fN  -find  node  N\n"); 

printf ("  a  -delete  the  entire  tree\n"); 

printf ("  q  -quit\n"); 


for(;  gets (buf);  printf ("i/d/ f/a/q:  ")  ) 
docmd(  *buf,  atoi  (buf +1)  ); 


End  Listing  Two 


Listing  Three 

Listing  3  —  avl.h 


typedef 

{ 


1 
2 

3 

4 

5 

6 

7  } 

8  HEADER; 

9 


struct  _leaf 

struct  _leaf 
struct  _leaf 
unsigned 
unsigned 


*left 
*right 
size  :  14 
bal  :  2 


/*  Possible  values  of  bal  field.  Can  be  */ 


10 

/* 

any 

three  consecutive 

numbers  but 

*/ 

11 

/* 

L  < 

B  <  R  must  hold. 

*/ 

12 

#def ine 

L 

0 

/* 

Left  subtree  is 

larger 

*/ 

13 

#def ine 

B 

1 

/* 

Balanced  subtree 

*/ 

14 

#define 

R 

2 

/* 

Right  subtree  is 

larger 

*/ 

15 

16 


17 

int 

delete 

(  HEADER**, 

HEADER*, 

int  (*)  () 

)  ; 

18 

HEADER 

* insert 

(  HEADER**, 

HEADER*, 

int  (*)  () 

)  ; 

19 

HEADER 

*find 

(  HEADER*  , 

HEADER*, 

int  (*)  () 

)  ; 

20 

void 

t print 

(  HEADER*  , 

int  (*)  (), 

FILE* 

) ; 

21 

HEADER 

*talloc 

(  int 

)  ; 

22 

void 

tfree 

(  HEADER* 

>; 

Listing  Four 


End  Listing  Three 


Listing  4  —  avlprnt.c 


1  #include  <stdio.h> 

2  # include  "avl.h" 

3 

4  /* - 

5  *  These  IBM  graphics  (box  drawing)  characters  are  used  only  if  the 

6  *  output  stream  is  stdout  and  isattyO  is  true  (it  will  be  false  if 

7  *  stdout  is  redirected) . 

8  * 

9  *  GAMMA:  + -  ELL: 

10  *  \332  |  \300 

11  * 

(continued  on  nepct  page) 


|  T_RIGHT  + 

+ -  \303  | 
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Listing  Four  (Listing  continued;  text  begins  on  page  20.) 


12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 


T_LEFT 

\264 


VERT 

\263 


T_UP: 

\331 

(dash) 

\304 


T_D0WN 

\277 


I 


*/ 

#define  VERT  Cset[0] 

#define  GAMMA  Cset[l] 

#define  ELL  Cset[2] 

#define  T_LEFT  Cset[3] 
fdefine  T_UP  Cset[4) 
fdefine  T_DOWN  Cset[5] 

f ifdef  DEBUG 

f  define  PAD  ()  printf("  "); 

#  define  PBAL(r)  printf (" (%c) ",  r->bal==B  ?  'B' :  r->bal==L  ?  'L':  'R'); 

#else 

f  define  PAD() 

f  define  PBAL(r) 

#endif 


/* 


*/ 


static  char  *Graph_chars [ )  -  {  "\263",  "\332\304\304",  "\300\304\304"  , 

"\304\304\264",  "\304\304\331",  H\304\304\277,,  }; 


static  char  *Norm_chars ( ] 


{  "I", 


43 

static 

int 

(♦Print)  () ; 

/* 

Node  print  function  pointer 

*/ 

44 

static 

FILE 

*Out; 

/* 

Output  stream 

*/ 

45 

static 

char 

**Cset  ; 

/* 

Current  character  set 

V 

46 

static 

char 

Map[  64/8  ]; 

/* 

Bitmap  for  64  bits.  If  the 

*/ 

47 

/* 

tree  is  deeper  than  this. 

*/ 

48 

/* 

we're  in  trouble. 

*/ 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 

87 

88 

89 

90 

91 

92 


#define  testbit (c)  (  Map[c  »  3]  &  (1  «  (c  &  0x07))  ) 


static  setbit (  c,  val  ) 
int  c,  val; 

{ 

if (  val  ) 

Map[c  »  3]  |= 

else 

Map[c  »  3]  &= 


1  «  (c  &  0x07)  ; 
-(1  «  (c  &  0x07))  ; 


/* 


static  trav(  root,  amleft  ) 

HEADER  *root; 
int  amleft; 

{ 

/*  Prints  a  binary  tree  graphically,  with  lines  showing 

*  all  the  pointers.  This  is  essentially  the  same  routine 

*  we  looked  at  last  month.  See  that  article  for  more 

*  info  about  how  it  works. 


static  int 
static  int 


depth 

i; 


-l; 


/*  Current  depth  in  the  tree 


i f (  root  ) 

{ 


++depth; 

if  (  root->right  ) 

trav (  root->right,  0  ); 

else 

setbit (  depth+1,  1  ); 


for(i  =1;  i  <=  depth  ;  i++  ) 

{ 

(*Print) (Out,  0) ; 

PAD  ()  ; 
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93 

94 

if  <  i 

==  depth  ) 

95 

fprintf(Out,  "  %s",  amleft  ?  ELL 

96 

97 

else  if(  testbit  (i)  ) 

98 

fprintf(Out,  "  %s  "  , 

VERT  ) ; 

99 

else 

100 

fprintf(Out,  "  "  ); 

101 

} 

102 

103 

(*Print) (Out, 

root  +  1  ) ; 

104 

PBAL (root) ; 

105 

106 

fprintf(Out,  " 

%s\n". 

107 

(root->left)  ?  (root->right 

?  T_LEFT 

108 

:  (root->right 

?  T_UP 

109 

) ; 

110 

111 

112 

setbit  (  depth. 

amleft  ?  0  ;  1); 

113 

114 

if(  root->left 

) 

115 

trav  ( 

root->left,  1  ); 

116 

else 

117 

setbit (  depth+1,  0  ) ; 

118 

119 

— depth; 

120 

} 

121  } 

122 

123  /*  - 

124 

125  void 

126  HEADER 

127  int 

128  FILE 

129  { 

130 

131 

132 

133 

134 

135  } 


tprint(  root,  print,  stream  ) 

*root; 

(*print)  () ; 

* st ream; 

Out  =  stream; 

Print  =  print; 

Cset  =  Out  ==  stdout  &&  isatty  (fileno (stdout) )  ?  Graph_chars 

:  Norm_chars  ; 

trav(  root,  0  ); 


End  Listing  Four 


Listing  Five 


Listing  5  —  avlfind.c 


1  # include  <stdio.h> 

2  #include  "avl.h" 


3 

4  HEADER 

5  HEADER 

6  HEADER 

7  int 

8  { 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18  } 


*find(  root,  key,  cmp  ) 

*root; 

*key; 

(*cmp)  () ; 

static  int  relation; 

i f  (  ! root  ) 

return  NULL; 

relation  =  (*cmp) (  key,  root  +  1  ); 

return  (relation  ==  0)  ?  root  +  1  : 

find(  relation  <  0  ?  root->left  :  root->right,  key,  cmp  ); 

End  Listing  Five 


Listing  Six 

Listing  6  —  avlfree.c 


1  #include  <stdio.h> 

2  # include  "avl.h" 

3 

4  static  void  fa (  root  ) 

5  HEADER  *root; 

6  { 

7  /*  Delete  the  entire  tree  pointed  to  by  root.  Note  that  unlike 

8  *  tfree(),  this  routine  is  passed  a  pointer  to  a  HEADER  rather 

9  *  than  to  the  memory  just  below  the  header. 

10  V 

11 

12  if (  root  ) 

13  ( 

(continued  on  nepct  page) 
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UStinCj  Six  (Listing  continued,  text  begins  on  page  20.) 

14 

fa (  root->left  ) ; 

15 

fa  (  root -> right  ) ; 

16 

free (  root  ) ; 

17 

i 

18 

i 

19 

21 

22 

void  freeall (  root  ) 

23 

HEADER  **root; 

24 

( 

25 

fa {  ‘root  ) ; 

26 

*root  =  NULL; 

27 

} 

End  Listing  Six 

Listing  Seven 

Listing  7 

—  avlins.c 

1 

# include  <stdio.h> 

2 

♦include  "avl.h" 

4 

/* - 

5 

*  Externally  accessible  routines: 

6 

* 

7 

*  HEADER  * insert  (  rootp,  newnode,  cmp  >  Insert  newnode  in  tree 

8 

*  HEADER  ‘talloc (  size  ) 

Allocate  a  tree  node 

9 

*  void  tfree (  p  ) 

Free  a  tree  node 

10 

* 

* 

12 

*/ 

13 

14 

static  int  (*Cmp)  () ; 

15 

static  HEADER  *Newnode; 

16 

static  HEADER  *Conf licting; 

17 

19 

20 

HEADER  ‘talloc (  size  ) 

21 

{ 

22 

HEADER  *malloc  () ; 

23 

HEADER  *p; 

24 

25 

if  (  p  =  malloc(  size  +  si zeof  (HEADER) )  ) 

26 

27 

p->left  =  NULL; 

28 

p->right  =  NULL; 

29 

p->size  =  size; 

30 

p->bal  =  B; 

31 

P++; 

32 

1 

33 

return  p; 

34 

i 

35 

36 

/* 

37 

' 

38 

void  tfree (  p  ) 

39 

HEADER  *p; 

40 

i 

41 

free  (  — p  )  ; 

42 

i 

43 

45 

46 

static  int  ins (  pp  ) 

47 

HEADER  **pp; 

48 

{ 

49 

HEADER  *p; 

50 

HEADER  *pl,  *p2; 

51 

int  relation; 

/*  relation  >  0  <==>  p  >  Newnode 

52 

*  relation  <  0  <==>  p  <  Newnode 

53 

*  relation  ==  0  <==>  p  ==  Newnode 

54 

*/ 

55 

56 

static  int  h  -  0; 

/*  Set  by  recursive  calls  to  search  to 

57 

*  indicate  that  the  tree  has  grown. 

58 

*  It  will  magically  change  its  value 

59 

*  everytime  ins()  is  called  recursively. 

60 

*/ 

(continued  on  page  92) 
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Listing  Seven 

(Listing  continued,  text  begins  on  page  20.) 

61 

If (  ! (p  =  *pp)  ) 

62 

f 

63 

p  =  Newnode  ;  /*  insert  node  in  tree  */ 

64 

h  =  1; 

65 

i 

66 

else  if(  (relation  =  (*  Cmp) (  p+l#  Newnode+1))  ==  0  ) 

67 

( 

68 

Conflicting  =  p  +  1; 

69 

i 

70 

else  if (  relation  >  0  ) 

71 

t 

72 

ins (  &p->left  ); 

73 

74 

if (  h  )  /*  left  branch  has  grown  */ 

75 

i 

76 

switch (  p->bal  ) 

77 

{ 

78 

case  R:  p->bal  =  B  ;  h  =  0;  break; 

79 

case  B:  p->bal  =  L  ;  break; 

80 

81 

case  L:  /*  rebalance  */ 

82 

pi  -  p->left; 

83 

if (  pl->bal  ==  L  )  /*  Single  LL  */ 

84 

{ 

85 

p->left  =  pl->right; 

86 

pl->right  =  p; 

87 

p->bal  =  B; 

88 

p  =  pi; 

89 

) 

90 

else  /*  Double  LR  */ 

91 

{ 

92 

p2  =  pl->right; 

93 

pl->right  =  p2->left; 

94 

p2->left  =  pi; 
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Listing  Seven 

(Listing  continued,  text  begins  on  page  20.) 

95 

p->left 

=  p2->right; 

96 

p2->right 

=  p; 

97 

p->bal 

=  (p2->bal  ==  L)  ?  R  :  B  ; 

98 

pl->bal 

=  (p2->bal  ==  R)  ?  L  :  B  ; 

99 

P 

-  p2; 

100 

) 

101 

p->ba  1  =  B; 

102 

h  =  0; 

103 

i 

104 

105 

i 

106 

else 

107 

i 

108 

ins (  &p->right  ) ; 

109 

110 

if  ( 

h  )  /* 

right  branch  has  grown  */ 

111 

i 

112 

switch (  p->bal  ) 

113 

< 

114 

case  L:  p->bal  =  B;  h  = 

0;  break; 

115 

case  B:  p->bal  =  R; 

break ; 

116 

117 

case  R: 

/*  rebalance:  */ 

118 

pi  =  p->right; 

119 

if (  pl->bal  ==  R 

/*  Single  RR  */ 

120 

< 

121 

p->right 

pl->left; 

122 

pl->left 

=  p; 

123 

p->bal 

B; 

124 

P 

=  pi; 

125 

i 

126 

else 

/*  Double  RL  */ 

127 

i 

128 

p2 

=  pl->left; 

129 

pl->left 

=  p2->right; 

130 

p2->right 

=  pi; 

131 

p->right 

=  p2->left; 

132 

p2->left 

=  p; 

133 

p->bal 

=  (p2->bal  ==  R)  ?  L  :  B  ; 

134 

pl->bal 

=  (p2->bal  ==  L)  ?  R  :  B  ; 

135 

P 

-  p2; 

136 

i 

137 

p->bal  =  B; 

138 

h  =  0; 

139 

} 

140 

i 

141 

i 

142 

143 

*pp  =  p; 

144  ) 

145 

146  /* - 

- */ 

147 

148  HEADER 

♦insert  (  rootp,  newnode,  cmp  ) 

149  HEADER 

** rootp; 

150  HEADER 

♦newnode; 

151  lnt 

(*cmp)  () ; 

152  { 

153 

/*  Insert 

newnode  into  tree  pointed  to  by  *rootp.  Cmp  is  passed 

154 

*  two  pointers  to  HEADER  and  should  work  like  strcmpO . 

155 

*  Return 

NULL  on  success  or  a  pointer  to  the  conflicting  node 

156 

*  on  error. 

157 

*/ 

158 

159 

Cmp 

=  cmp; 

160 

Newnode 

=  newnode  -  1; 

161 

Conflicting 

=  NULL; 

162 

163 

ins (rootp) ; 

164 

165 

return  Conflicting; 

166  } 

End  Listing  Seven 

Listing  Eight 

Listing  8  —  avldel.c 

1  # include 

<stdio.h> 

2  # include 

"avl.h" 

(continued  on  page  96) 
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Listing  Eight  (Listing  continued,  text  begins  on  page  20.) 


Local  static  subroutines: 


8  extern 

9  extern 

10  extern 

11  extern 

12 

13  /* - 

14 

15  static 

16  static 

17  static 

18 

19  /* - 

20 

21  static 

22  HEADER 

23  { 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 


balance_l  (  HEADER**  ); 
balance_r  (  HEADER**  ); 
descend  (  HEADER* *,  HEADER**  ); 
del  (  HEADER**  ); 


HEADER  *Key; 
int  (*Cmp)  () ; 

int  Not found; 


balance_l (  pp  ) 


This  routine  is  called  when  the  left  branch  of  the  current 
subtree  (pointed  to  by  p)  has  shrunk.  It  adjusts  the  balance 
factors  and  rebalances  if  necessary,  modifying  *pp  to  point 
at  the  new  root  (after  the  rebalance).  Returns  1  if  the 
tree  got  smaller  as  a  result  of  the  delete  or  the  rebalance 
operation,  else  returns  0. 


register  HEADER  *p,  *pl,  *p2; 

int  bl,  b2; 

int  got  smaller  =  1; 


switch (  p->bal  ) 

{ 

case  L:  p->bal  =  B; 
case  B:  p->bal  =  R; 
case  R: 

pi  =  p->right; 
bl  =  pl->bal; 


got_smaller 


if (  bl  >= 


/*  Single  RR 


p-> right 
pl->left 


pl->left; 

p; 


if (  bl  !=  B  ) 
p->bal 

else 


pl->bal  =  B; 


p->bal  =  R; 
pl->bal  =  L; 
got_smaller  = 


P2 

b2 

pl->left 

p2->right 

p->right 

p2->left 

p->bal 

pl->bal 

P 

p2->bal 


=  pl->left; 

=  p2->bal; 

=  p2->right; 

=  pi; 

=  p2->left; 

=  p; 

=  (b2  ==  R)  ?  L 
=  (b2  ==  L)  ?  R 


/*  Double  RL 


*pp  =  p; 

return  got  smaller; 


82  static  int 


balance_r (  pp  ) 


(continued  on  page  98) 
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Listing  Eight  (Listing  continued;  text  begins  on  page  20.) 


83  HEADER 

84  { 


85 

/* 

Same  as  balance  1  but  is  called  1 

86 

* 

has  been  made  smaller. 

87 

*/ 

88 

89 

register  HEADER  *p,  *pl,  *p2; 

90 

int 

bl,  b2; 

91 

int 

got_smaller  =1; 

92 

93 

P  =  *pp; 

94 

95 

switch ( 

i— i 

.a 

A 

1 

a 

96 

{ 

97 

case  R: 

p->bal  =  B; 

98 

case  B: 

p->bal  =  L;  got_smaller  =0; 

99 

case  L: 

100 

pi  =  p->left; 

101 

bl  =  pl->bal; 

102 

103 

if (  bl  <=  B  ) 

104 

{ 

105 

p->left  =  pl->right; 

106 

pl->right  =  p; 

107 

108 

if (  bl  !=  B  ) 

109 

p->bal  =  pl->bal 

110 

else 

111 

{ 

112 

p->bal 

L; 

113 

pl->bal 

R; 

114 

got  smaller  = 

0; 

115 

} 

116 

p  =  pi; 

117 

} 

118 

else 

/*  rebalance 


/*  Single  LL 
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Listing  Eight 


(Listing  continued,  text  begins  on  page  20.) 


119 

< 

120 

p2 

121 

b2 

122 

pl->right 

123 

p2->left 

124 

p->left 

125 

p2->right 

126 

p->bal 

127 

pl->bal 

128 

P 

129 

p2->bal 

130 

) 

131 

) 

132 

133 

*pp  =  p; 

134 

return  got 

smaller  ; 

135  } 

136 

138 

pl->right;  /*  Double  RL  */ 

p2->bal; 

p2->left; 

pi; 

p2->right; 

p; 

(b2  ==  L)  ?  R  :  B  ; 

(b2  ==  R)  ?  L  :  B  ; 

P2; 

B; 


139  static  int  descend  (  rootp,  dpp  ) 

140  HEADER  **rootp  ;  /*  Address  of  root  of  current  node  */ 

141  HEADER  **dpp  ;  /*  Address  of  node  to  be  deleted  */ 

142  { 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161  } 

162 


163  /* - */ 

164 

165  static  int  del (  rootp  ) 

166  HEADER  **rootp; 

167  { 

168  /*  Delete  Key  from  tree  pointed  to  by  *rootp.  Return  1  if  the  size 

169  *  of  the  tree  has  been  reduced,  0  otherwise. 

170  */ 

171 

172  HEADER  *dp;  /*  Pointer  to  node  to  delete  */ 

173  int  got_smaller  =  0;  /*  set  TRUE  if  tree  shrinks  */ 

174  static  int  relation; 

175 

176  if(  !*rootp  ) 

177  Notfound  =  1; 

178  else 

179  { 

180  relation  =  (*Cmp) (Key,  *rootp  +  1); 

181 

182  if (  relation  <  0  )  /*  Go  left  */ 

183  { 

184  if(  del  (  & (*rootp) ->left)  ) 

185  got_smaller  =  balance_l (  rootp  ) ; 

186  } 

187  else  if(  relation  >  0  )  /*  Go  right  */ 

188  { 

189  if(  del (  &  (*rootp) ->right)  ) 

190  got_smaller  =  balance_r(  rootp  ); 

191  } 

192  else  /*  Delete  current  */ 

193  { 

194  dp  =  *rootp  ; 

195 

196  if(  dp->right  ==  NULL  ) 

197  { 

198  * rootp  =  dp->left; 

199  got_smaller  =  1; 


/*  Does  the  actual  delete  when  the  root  node  has  both  left  and 

*  right  decendants.  Descends  to  the  rightmost  node  of  the 

*  left  subtree  and  then  copies  the  contents  of  that  node 

*  to  the  node-to-be-deleted  (*dpp) .  Then  the  node-to-be-deleted 

*  is  modified  to  point  at  the  former  rightmost  node. 

*/ 

if (  (*rootp)->right  ) 

return (  descend  (  & (*rootp) ->right,  dpp)  ) 

?  balance_r (rootp)  :  0  ; 

else 

{ 

memcpy(  *dpp  +  1,  *rootp  +  1,  (*rootp) ->size  ); 

*dpp  =  (* rootp) ; 

*rootp  =  (*rootp) ->left; 

return  1; 
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Listing  Nine  (Listing  continued;  text  begins  on  page  20.) 

Listing  9  —  makefile  for  avl.lib 


# 

# 

# 

# 

.c.obj : 


Make  avl.lib  and  test.exe  using  the  Microsoft  C  Compiler,  ver.  3.0 
and  Polymake. 


cl  -c  $*.c  »err 


OBJECTS  =  avldel.obj  avlfind.obj  avlfree.obj  avlins.obj  avlprnt.obj 


test.exe:  test.obj  tree. lib 

cl  test.obj  -link  tree. lib 

test.obj:  tree.h 


tree. lib:  $ (OBJECTS) 

del  tree. lib 
lib  <@< 

tree 

y 

$ (OBJECTS) 
tools. ndx 
<  »err 


avldel.obj:  avl.h 
avlins.obj:  avl.h 
avlfind.obj:  avl.h 
avlprnt.obj:  avl.h 
avlfree.obj:  avl.h 


End  Listings 


200 

i 

201 

else  if(  dp->left  ==  NULL  ) 

202 

{ 

203 

*rootp  =  dp->right; 

204 

got  smaller  =1; 

205 

206 

else  if(  descend (  & (*rootp)->left,  &dp  )  ) 

207 

< 

208 

got  smaller  =  balance  1(  rootp  ); 

209 

i 

210 

211 

free (  dp  ) ; 

212 

) 

213 

! 

214 

215 

return  got  smaller; 

216  } 

217 

219 

220  int 

delete (  rootp,  key,  cmp  ) 

221  HEADER 

**rootp; 

222  HEADER 

*key; 

223  int 

(*cmp)  () ; 

224  { 

225 

/*  Cmp  is  a  comparison  routine  called  with  (*cmp) (key,  node); 

226 

*  where  "key"  is  the  second  argument  to  delete  and  "node" 

227 

*  is  a  pointer  to  one  node  in  the  tree.  It  should  return 

228 

*  <0  if  key<node  0  if  key==node  >0  if  key>node.  Returns 

229 

*  1  if  the  node  was  deleted,  0  if  the  node  wasn't  in  the 

230 

*  tree. 

231 

*/ 

232 

233 

Cmp  =  cmp; 

234 

Key  =  key; 

235 

Not found  =0; 

236 

237 

del (  rootp  ) ; 

238 

End  Listing  Eight 

239 

return  ! Not found; 

240  ) 
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Listing  One  (Text  begins  on  page  30.) 

/* 

♦define  EACHLOOP 
*/ 

/* 

♦define  VERIFY 
*/ 

struct  fcmtype 

{ 

int  (*func)  (  ) ; 

char  *pf ; 

int  loop,  time; 


Listing  Two 

fcm_main.c 

♦include  <stdio.h> 

♦include  "bench. h" 

extern  struct  bratype  bm[  ]; 

main{  argc,  argv  ) 

int  argc; 

char  *argv[  ]; 

{ 

register  struct  bmtype  *bmp; 
int  total; 

FILE  *table,  *fopen ( ) ; 
total  -  0; 
functions  */ 

for  (  trip  -  &bm[0];  bmp->loop;  bmp++  ) 

{ 

total  +-  (bmp->time  -  (*bmp->func) (  bmp->loop  )); 

printf(  "%8.8s  *5d  %4d.%ld\n",  bmp->pf,  t«np->loop,  bmp->time  /  10, 

} 


*/ 


table  -  fopen (  "result .tbl",  "a"  ); 


End  Listing  One 


/*  Run  all  the  benchmark 


bmp->time  %  10  ) ; 
/*  Print  out  all  the  results 


for  (  fcsnp  -  &bm[0];  bmp->loop;  bmp++  ) 

fprintf (table,  "\"%-8 . 8s\", \"%-8 . 8s\", \"%-8 . 8s\", \"%-20 . 20s\", , , , , %d, %d . %ld\n", 

argv[l],  argv [2],  bmp->pf,  "  ",  tmp->loop, 
bmp->time  /  10,  bmp->time  %  10  ); 

print f (  "\n  TOTAL:  %4d.%ld\n",  total  /  10,  total  %  10  ); 

fclose  (  table  ) ; 


End  Listing  Two 


Listing  Three 


optimize .c 
♦include  "bench. h" 
extern  int  optimizer  ); 
struct  bmtype  bm[  ]  - 


}, 

{ 

/*  End  of  list  */ 


optimize,  "optimize",  100,  0 


optimize,  "",  0,  0 


optimizer  loop  ) 


{ 


int  loop; 

int  i,  il,  i2,  i3,  i4,  i5; 
int  inner; 
int  array [8]; 

i  -  1; 
time_0(  ); 

for  (  ;  loop;  loop —  ) 


*  This  benchmark  may  look  strange,  but  it  is 

*  intended  to  make  non-optimizing  compilers 

*  look  bad.  It  contains  a  number  of  statements 

*  that  could  easily  be  optimized. 

*! 
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Listing  Three  (Listing  continued,  text  begins  on  page  30.) 


for  (  inner  -  1000;  inner;  inner —  ) 

{ 

/*  Multiple  assignments  */ 

il  -  i2  -  i3  -  i4  -  i5  -  0; 

il  -  i2  -  i3  -  i4  -  i5  -  0; 

il  -  i;  il  -  i;  il  -  i;  il  -  i;  il  -  i; 

il  -  i;  il  -  i;  il  -  i;  il  -  i;  il  -  i; 


Increment  and  Decrement  */ 


11  +-  1;  il  +-  1;  il  +-  1;  il  +-  1;  il  +-  1; 

12  —  1;  il  +-  1;  il  +-  1;  il  +-  1;  il  +-  1; 


Multiply  by  two  (left  shift)  */ 


time  expression  eval  */ 


il  -  1; 

il  *-  2;  il  *-  2;  il  *-  2;  il  *-  2;  il  *-  2; 


il  -  (10  *  (27  +  14  +  i)  -  i)  *  47  +  32; 

/*  Compare  equivalent  constructions  */ 

il  +-  1; 
il  -  i  +  1; 
il++; 


subexpressions  */ 


extraction  from  loop  */ 


12  -  (i4  *  i5)  +  i3; 
il  -  (i4  *  i 5 )  +  i2; 

13  -  ( (i4  *  i5)  +  i2 )  *  ((i4  *  i5)  +  il); 


for  (il  -  i2;  il;  il--) 

( 

13  -  array!  inner  +  i2  J; 

14  -  array!  inner  +  il  j; 

15  -  array!  i3  +  1  ] ; 

14  -  array!  i2  +  1  ] ; 

15  -  array!  12  +  1  j ; 

} 


/*  Code  motion: 


return (  time  n (  )  ) ; 


Listing  Four 


pointer. c 


♦include  "bench. h" 
extern  int  pointer (  ) ; 


struct  bratype  tm[  ) 

( 


End  Listing  Three 


pointer,  "pointer",  1500,  0 


/*  End  of  list  */ 


pointer,  "",  0,  0 


static  int  s [10] ( 10] t 10] ; 
static  int  d[10] (10] [10] ; 

pointer (  loop  ) 


*  This  benchmark  copies  one  three  dimensional 

*  array  to  another  using  pointers.  It  is 

*  complictaed  by  the  use  of  three  levels  of 

*  pointer  indirection  to  increase  the  ratio  of 

*  pointer  arithmetic  to  overhead. 

V 


int  *spl,  **sp2; 
int  *dpl,  **dp2; 
register  int  ***sp3,  ***dp3; 

sp2  -  &spl; 
sp3  -  &sp2; 
dp2  -  4 dpi; 
dp3  -  4dp2; 


for  (  ;  loop;  loop —  ) 

{ 
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LjStiriQ  FOUr  (Listing  continued,  text  begins  on  page  30.) 

dpi  -  &d[0] [0] [01 ; 

for  (  spl  -  &s [0] [0] [0] ;  spl  <-  ts(9][9][9];  spl++,  dpl++  ) 

*  **dp3  -  *  **  sp3 ; 

} 

return (  time  n(  )  ); 

) 

End  Listing  Four 

Listing  Five 

trig.c 

♦include  "bench.h" 

extern  int  trig(  ); 

struct  bmtype  bm  [  ]  = 

( 

{ 

trig,  "trig",  100,  0 

}, 

{ 

/*  End  of  list  */ 

trig,  "",  0,  0 

) 

}; 

int  trig(  loop  ) 

/* 

*  This  benchmark  function  tests  the  simple 

*  trigonometic  functions  sin,  cos,  and  tan. 

*  It  does  12  of  each  operation,  and  assumes 

*  radian  arguments. 

*/ 

int  loop; 

{ 

double  a,  b,  c 

,  d; 

double  sin (  ) , 

cos  ( 

),  tan (  ); 

time_0 (  ) ; 

for  (  ;  loop; 

loop- 

-) 

a  - 

sin( 

.392699  ); 

b  - 

sin( 

.785398  ); 

c  - 

sin( 

1.178097  ); 

d  - 

sin( 

1.963495  ); 

a  - 

sin( 

2.356194  ); 

b  - 

sin( 

2.748893  ); 

c  - 

sin( 

3.534292  ); 

d  - 

sin( 

3.926991  ); 

a  - 

sin  ( 

4.319690  ); 

b  - 

sin  ( 

5.105088  ); 

c  - 

sin  ( 

5.497787  ); 

d  - 

sin  ( 

5.890486  ); 

a  - 

cos  ( 

.392699  ); 

b  - 

cos  ( 

.785398  ); 

c  - 

cos  ( 

1.178097  ); 

d  - 

cos  ( 

1.963495  ); 

a  - 

cos  ( 

2.356194  ); 

b  - 

cos  ( 

2.748893  ); 

c  - 

cos  ( 

3.534292  ); 

d  - 

cos  ( 

3.926991  ); 

a  - 

cos  ( 

4.319690  ); 

b  - 

cos  ( 

5.105088  ); 

c  - 

cos  ( 

5.497787  ); 

d  - 

cos  ( 

5.890486  ); 

a  - 

tan  ( 

.392699  ); 

b  - 

tan  ( 

.785398  ); 

c  - 

tan  ( 

1.178097  ); 

d  - 

tan( 

1.963495  ); 

a  - 

tan( 

2.356194  ); 

b  - 

tan  ( 

2.748893  ); 

c  - 

tan  ( 

3.534292  ); 

d  - 

tan( 

3.926991  ); 

a  - 

tan  ( 

4.319690  ); 

b  - 

tan( 

5.105088  ); 

c  - 

tan  ( 

5.497787  ); 

d  - 

) 

tan( 

5.890486  ); 

return (  time  n (  ) 

} 

End  Listings 

Dr.  Dobb's  Journal,  August  1986 


108 


STRUCTURED  P 

ROGRAMMING 

LiStirTQ  One  (Text  begins  on  page  11 6.) 

type  List  is  array  (Index_Range)  of  Member; 
funtion  Largest (L  :  List)  return  Member; 

function  Largest (L  :  List)  return  Member  is 

Listing  One.  Ada  procedure  to  swap  two  integers. 

—  Initialize  Big  to  lowest  value 

Big  :  Member  :=  Member' FIRST; 

procedure  Swap (First,  Second  :  in  out  integer)  is 

begin 

for  i  in  Index  Range  loop 

Temporary  :  integer; 

if  Big  <  L(i)  then  Big  :=  L(i);  end  if; 

end  loop; 

begin 

return  Big; 

Temporary  :=  First; 

end  Largest; 

First  : -  Second; 

End  Listing  Four 

Second  :=  Temporary; 

end  Swap; 

End  Listing  One 

Listing  Five 

Listing  Two 

Listing  Five.  Generic  Ada  function  to  return  the  average 

of  a  floating  point  typed  array. 

Listing  Two.  Generic  Ada  procedure  to  swap  two  scalars. 

generic 

type  Index  Range  is  range  <>; 

type  Element  is  digits  o; 

generic 

—  Declare  generic  types  here 

type  List  is  array  (Index  Range)  of  Element; 

function  Average (X  :  List)  return  Element; 

type  Object  is  private; 

—  List  heading  for  generic  routines  here 

function  Average (X  :  List)  return  Element  is 

procedure  Swap (First,  Second  :  in  out  Object); 

Sum  :  Element  :=  0.0;  —  Initialize  summation 

—  Full  definition  of  procedures  is  below 

begin 

for  i  in  Index  Range  loop 

procedure  Swap (First,  Second  :  in  out  Object)  is 

Temporary  :  Object; 

Sum  :=  Sum  +  X  (i) ; 
end  loop; 

begin 

Temporary  :=  First; 

return  (Sum  /  FLOAT (Index_Range) ) ; 
end  Average; 

First  Second; 

End  Listing  Five 

Second  Temporary; 

end  Swap; 

End  Listing  Two 

Listing  Six 

Listing  Three 

Listing  Six.  Generic  Ada  procedure  to  solve 

the  mathematical  root  of  a  function. 

Listing  Three.  Generic  Ada  procedure  to  return 

generic 

the  next  element  in  a  circular  list. 

type  Floating  is  digits  <>; 

—  declaring  a  subprogram  parameter 

generic 

—  the  "with"  keyword  distinguishes  it  from  other 

type  Circular  Item  is  (o); 

—  declared  generic  routines. 

function  Fetch  Next  In  Circular  List (Member  :  Circular  Item) 

with  function  F  of  X(X  :  Floating)  return  Floating; 

return  Circular  Item; 

procedure  Root  (Guess  :  Tn  out  Floating;  Accuracy  :  in  Floating; 

Iter  Max  :  in  INTEGER;  Converge  :  out  BOOLEAN) ; 

—  Declare  the  generic  function  body 

function  Fetch  Next  In  Circular  List  (Member  :  Circular  Item) 

procedure  Root (Guess  :  in  out  Floating;  Accuracy  :  in  Floating; 

return  Circular_Item  is 

Iter_Max  :  in  INTEGER;  Converge  :  out  BOOLEAN)  is 

begin 

Increment,  Diff  :  Floating; 

—  use  predefined  LAST  attribute 

Iter  :  INTEGER  :=  0; 

if  Member  =  Circular  Item'LAST 

then  —  use  predefined  FIRST  attribute 

begin 

return  Circular  Item' FIRST; 

Converge  :=  true; 

else  —  use  predefined  SUCCesive  attribute 

loop 

return  Circular  Item 1 SUCC (Member) ; 

if  abs (Guess)  >  1.0 

end  if; 

then  Increment  :=  0.01  *  Guess; 

end  Fetch  Next  In  Circular  List; 

else  Increment  :=  0.01; 

end  if; 

Diff  :=  2.0  *  Increment  *  F  of  X (Guess)  / 

—  Examples  for  generic  instantiation  are 

(F  of  X (Guess  +  Increment)  - 

—  type  Day  is  (MON,  TUE,  WED,  THU,  FRI,  SAT,  SUN) ; 

F  of  X (Guess  -  Increment)); 

—  function  NextDay  is  new  Fetch  Next  In  Circular  List  (Day) ; 

Guess  :=  Guess  -  Diff; 

—  NextDay  (TUE)  returns  WED 

Iter  :=  Iter  +  1; 

—  NextDay (SUN)  returns  MON 

if  Iter  >  Iter  Max  then  Converge  :=  false;  end  if; 

if  (abs (Diff)  <  Accuracy)  or  (not  Converge) 

—  subtype  Hours  is  integer  0..24; 

then  exit; 

—  function  NextTime  is  new  Fetch  Next  In  Circular  List (Hours) ; 

end  if; 

—  NextTime  (4)  returns  5 

end  loop; 

—  NextTime (24)  returns  0 

end  Root; 

End  Listing  Three 

End  Listing  Six 

Listing  Four 

Listing  Seven 

Listing  Four.  Generic  Ada  function  that  scans  an  array 

Listing  Seven.  Generic  Shell  sort  procedure  in  Ada. 

and  returns  the  largest  value  found. 

generic 

generic 

type  Range  Index  is  (<>); 

type  Index  Range  is  range  <>; 

type  Data  Ts  private; 

type  Member  is  range  <>; 

type  List  is  array  (Range_Index  range  <>)  of  Data; 
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—  declare  generic  function/operator 
with  function  ">" (A,  B  :  Data)  return  BOOLEAN; 
procedure  Shell_Sort(L  :  in  out  List;  Num  :  INTEGER); 

procedure  Shell_Sort (L  :  in  out  List;  Num  :  INTEGER)  is 

Offset,  I,  K  :  INTEGER; 

Tempo  :  Data; 

In_Order  :  BOOLEAN; 


begin 

Offset  :=  Num; 
while  Offset  >  1  loop 

Offset  :=  Offset  /  2; 
loop 

InjDrder  :=  true; 

K  : =  Num  -  Offset; 
for  J  in  1. .K  loop 

I  :=  J  +  Offset; 

if  L(J)  >  L(I)  —  Using  the  ">"  operator 


then  In_Order  :=  false; 
Tempo  :=  L(I) ; 

L(I)  :=  L(J) ; 

L(J)  :=  Tempo; 

end  if; 
end  loop; 

if  In_Order  then  exit;  end  if; 
end  loop;  —  open  loop 
end  loop;  —  while  loop 
end  Shell  Sort; 


End  Listing  Seven 


Listing  Eight 


Listing  Eight.  Generic  Modula-2  function  to  search  for  a 

specific  value  in  an  integer /cardinal 
array. 

PROCEDURE  Li nearSearch  (VAR  Element  :  ARRAY  OF  WORD;  (*  input  *) 

SearchValue  :  INTEGER;  (*  input  *) 

VAR  Index  :  CARDINAL  (*  output  *) 

)  :  BOOLEAN; 

VAR  Found  :  BOOLEAN; 
hi  :  CARDINAL; 

BEGIN 

Index  ;=  0;  hi  :=  HIGH (Element) ;  Found  :=  FALSE; 

WHILE  (Index  <=  hi)  AND  (NOT  Found)  DO 

(*  Logical  expression  tested  converts  *) 

(*  array  element  into  an  integer  type  *) 

IF  SearchValue  =  INTEGER (Element [Index] ) 

THEN  Found  :=  TRUE 
ELSE  INC (Index) 

END;  (*  IF  *) 

END;  (*  WHILE  *) 

RETURN  Found 
END  LinearSearch; 

End  Listing  Eight 


Listing  Nine 


Listing  Nine.  Generic  Modula-2  Shell  sort  procedure. 


(*  in/out  *) 

(*  input  *) 
(*  input  *) 
(*  input  *) 

VAR  Offset,  I,  K,  DataSize  :  CARDINAL; 

InjDrder  ;  BOOLEAN; 


PROCEDURE  Shell Sort (VAR  L  :  ARRAY  OF  WORD; 

Samplel , 

Sample2  :  ARRAY  OF  WORD; 

Num  :  CARDINAL; 

IsGreater  :  UserDefinedProc) ; 


PROCEDURE  Fet chit em ( It em_Num  :  CARDINAL;  (*  input  *) 

VAR  Item  :  ARRAY  OF  WORD);  (*  output  *) 
(*  Procedure  copies  an  element  from  main  array  in  Item  *) 

VAR  Count  :  CARDINAL; 

BEGIN 

FOR  Count  :=  0  TO  DataSize  -  1  DO 

Item [Count]  :=  L [Count  +  Item_Num  *  DataSize] 

END; 

END  Fet chi tern; 


PROCEDURE  Putltem (Item_Num  :  CARDINAL;  (*  input  *) 

VAR  Item  :  ARRAY  OF  WORD) ;  (*  output  *) 
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Listing  Nine  (Listing  continued,  text  begins  on  page  116.) 

(*  Procedure  copies  an  element  to  main  array  *)  I  Listing  Jq p| 


VAR  Count  :  CARDINAL; 

BEGIN 

FOR  Count  :=  0  TO  DataSize  -  1  DO 

L [Count  +  Item_Num  *  DataSize] 

END; 

END  Putltem; 


Item [Count] 


BEGIN  (* - Shell  Sort - *) 

DataSize  :=  HIGH (Samplel)  +  1; 

Offset  :=  Num; 

WHILE  Offset  >  1  DO 

Offset  :=  Offset  DIV  2; 

REPEAT 

In_Order  :=  TRUE; 

K  :=  Num  -  1  -  Offset; 

FOR  J  :=  0  TO  K  DO 

I  :=  J  +  Offset; 

Fetchltem  (I,  Sairplel) ; 

Fetchltem  ( J,  Sarnple2) ; 

(*  Logical  expression  employs  *) 
(*  user-supplied  logical  function  *) 
IF  I  sG  feater  (Samplel, Sample2) 

THEN  In_Order  :=  FALSE; 

(*  Swap  items  *) 

PutItem(J,  Samplel); 
PutItem(I,  Sample2); 

END;  (*  IF  *) 

END;  (*  FOR  *) 

UNTIL  In_Order; 

END;  (*  WHILE  *) 

END  Shell  Sort; 


Listing  TEN.  Modula-2  function  compares  "frequency"  fields. 


PROCEDURE  GreaterFreq (Fieldl ,  Field2  :  ARRAY  OF  WORD)  :  BOOLEAN; 

VAR  Ptrl,  Ptr2  :  POINTER  TO  NameUse;  (*  record  type  defined  *) 

(*  elsewhere  in  program  *) 

BEGIN 

(*  Get  address  of  records  *) 

RecordPointerl  :=  ADR  (Fieldl ) ; 

RecordPointer2  :=  ADR(Field2) ; 

RETURN  RecordPointerl A. Frequency  >  RecordPointer2A. Frequency 
END  GreaterFreq; 

End  Listing  Ten 


Listing  Eleven 


End  Listing  Nine 


Listing  Eleven.  Iterator  example.  Professional  Pascal 

program  compares  a  list  of  names 
with  a  list  of  keys  and  report 
any  matches  found. 


program  Pick_Data; 

const  MAX_NAME  =  1000; 

MAX_KEY  =50; 

type  Name_type  =  String (80); 

Name_Array  =  array  [  1 . . MAX_NAME  ]  of  Name_type; 
Key_Array  =  array  [l..MAX_KEY]  of  Name_type; 
Count  =  array  [ 1 . . MAX_KEY ]  of  Integer; 

var  K  :  Integer; 

Names  :  Name_Array; 

Keys  :  Key_Array; 

Key_Count  :  Count; 

Num_Name,  Num_Key  :  Integer; 

Name_File,  Key_File  :  Text; 


iterator  Select (Num_Name#  Num_Key)  : 

(Key_Index,  Name_Index  :  Integer) ; 
var  I,  J  :  Integer; 
begin 

(*  Loop  counters  are  automatic  in  Prof.  Pascal  *) 
for  I  :=  1  to  Num_Key  do 

for  J  :=  1  to  Num_Name  do 
if  Keys[J]  =  Names [I] 
then  begin 

Key_Count[J]  :=  Key_Count[J]  +  1; 
Yield  (J,  I) 

end 

end; 


Reset (Name_F lie,' NAMES . TXT ’ ) ;  Num_Name  : =  0 ; 

Reset (Key_File/  ' KEYS . TXT ' ) ;  Num_Key  : =  0 ; 

(*  Read  names  from  name  file  *) 
while  not  EOF (Name_File)  do  begin 
Num_Name  :=  Num_Name  +  1; 

Readln  (Name_File,  Names  [Num_Name] ) ; 

end; 

Close (Name_File) ; 

(*  Read  keys  from  name  file  *) 
while  not  EOF (Key_File)  do  begin 
Num_Key  :=  NumJKey  +  1; 

Key_Count [Num_Key]  :=  0; 

Readln (Key_File, Keys [Num_Key ] ) ; 

end; 

Close  (Key_File)  ; 

(*  Loop  that  finds  and  displays  matching  keys  and  names  *) 
for  Key  Index,  Name_Index  in  Select  (Num_Name,  Num_Key)  do 
WrTteln(Keys[Key_Index, 'is  key  #  ",Key_Index, 

'  matches  name  #  ' ,  Name_Index) ; 

(*  Loop  to  display  name  matching  frequency  *) 
for  K  :=  1  to  Num_Key  do 

Writeln('Key  #  ' ,K,  '  has  found  ' , Key_Count , '  matched 

names ' ) ; 


End  Listings 
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Generic  Routines  in  Ada  and  Modula-2  and  Pascal  Iterators 


In  this  column  I'll  look  at  generic 
routines  in  Ada  and  Modula-2.  Ada 
formally  supports  generics,  whereas 
Modula-2  provides  an  indirect  ap¬ 
proach.  I  will  also  examine  a  new 
type  of  extended  ^or  loop,  implement¬ 
ed  in  a  commercial  Pascal  compiler. 

Pascal  programmers  are  familiar 
with  the  limitations  of  strong  data 
typing,  which  dictates  the  creation  of 
multiple  versions  of  the  same  rou¬ 
tines  to  handle  different  data  types. 
In  effect,  a  lot  of  effort  is  spent  rein¬ 
venting  the  wheel.  The  situation 
worsens  when  arrays  are  handled  by 
routines  such  as  those  for  sorting  and 
searching,  and  for  multidimensional 
arrays,  matters  are  even  more  com¬ 
plicated.  These  problems  were  in¬ 
herited  by  the  designers  of  Ada  and 
Modula-2,  who  decided  to  put  an  end 
to  them. 

The  solution  to  the  above  dilemma 
comes  in  two  stages.  The  first  is  the 
creation  of  routines  that  handle  dif¬ 
ferent  size  arrays  with  the  same  data 
types.  Many  Pascal  implementations, 
as  well  as  standard  Modula-2  and 
Ada,  enable  programmers  to  write 
general-purpose  libraries  to  handle 
arrays  of  different  sizes.  Modula-2 
supports  one-dimensional  open  ar¬ 
rays.  Some  Pascal  implementations 
provide  the  same  feature;  others  al¬ 
low  multidimensional  arrays  to  be 
handled.  The  second  stage  deals  with 
writing  routines  that  handle  differ¬ 
ent  data  types  and,  where  appropri¬ 
ate,  different  array  sizes. 

Generic  Routines  in  Ada 

Consider  a  short  procedure  to  swap 


by  Namir  Clement 
Shammas 


two  integers,  as  shown  in  Listing 
One,  page  110.  Without  using  the  ge¬ 
neric  feature,  programmers  must 
have  as  many  versions  of  Swap  as 


data  types  encountered.  To  minimize 
this  waste,  you  can  write  a  simple  ge¬ 
neric  procedure  as  shown  in  Listing 
Two,  page  110.  Notice  the  use  of  the 
reserved  word  generic  to  declare 
such  a  routine.  In  addition,  you  de¬ 
fine  the  data  type  Object  as  a  private 
type.  The  generic  procedure  resem¬ 
bles  a  template  or  a  mold,  and  the  pri¬ 
vate  type  represents  a  blank  type. 

Generic  routines  cannot  be  used  di¬ 
rectly.  Instead,  they  must  first  be  in¬ 
stantiated  (that  is,  used  to  create  a  cus¬ 
tomized  routine).  This  dictates 
creating  a  new,  usable  routine  with  a 
distinct  name.  In  addition  the  private 
type  parameter  must  be  associated 
with  a  specific  data  type.  The  second 
step  is  to  write  a  use  <customized 
routine  name>  statement.  To  create 
two  versions  of  Swap  (one  for  inte¬ 
gers,  the  other  for  reals),  you  can 
write  the  following: 

procedure  Swap_Int  is  new 

Swap(INTEGER); 

use  Swap_Int;  --  now  we  are  ready! 
procedure  Swap  _JFloat  is  new 

Swap(FLOAT); 

use  Swap  afloat; 

The  above  procedures  are  declared 
with  new  names  and  specify  the  ac¬ 
tual  data  type  to  which  the  custom¬ 
ized  version  is  tailored.  The 
keywords  is  new  are  part  of  the  Ada 
syntax  used  in  generic  instantiation. 
Operations  tackling  private  parame¬ 
ter  types  are  limited  to  assignments. 

Ada  permits  other  kinds  of  data 
type  parameters.  With  each  class 
comes  a  set  of  operations  that  are 
needed  to  avoid  confusing  situations 


involving  generics. 

Generic  enumerated  parameters 
allow  the  use  of  all  operators  in¬ 
volved  with  normal  enumerated 
types.  This  includes  relational  opera¬ 
tors,  SUCC  and  PRED,  and  member¬ 
ship  operators  in  and  not  in.  Generic 
enumerated  types  are  declared  using 
(<>).  Listing  Three,  page  110, 
shows  a  generic  function  to  return 
the  next  element  in  a  circular  list.  Ex¬ 
amples  for  using  the  function  are 
shown  at  the  trailing  comments:  The 
first  uses  the  enumerated  type  Day, 
which  includes  the  weekdays;  the 
second  example  uses  an  integer  su¬ 
brange  to  represent  hours. 

Generic  integer  parameters  allow 
the  use  of  integer  operators  in  addi¬ 
tion  to  those  of  the  enumerated  type. 
Integer  parameters  are  declared 
with  range  <  >.  Listing  Four,  page 
110,  shows  a  generic  function  that 
scans  an  integer-typed  array  and  re¬ 
turns  the  largest  value  found.  This  ex¬ 
ample  also  introduces  generic  arrays. 
Notice  that  there  are  three  generic 
data  types:  two  integers  and  one  ar¬ 
ray.  When  the  generic  function  is  in¬ 
stantiated,  three  parameters  are 
needed.  The  following  example  pro¬ 
duces  a  function  that  tackles  an  array 
of  100  integers.  You  are  not  using  the 
standard  type  integer  specifically, 
however.  Instead  you  are  employing 
a  derived  type,  called  Whole— 
Number,  which  is  a  range  of  integers 
from  1  to  1,000. 

type  List— Range  is  range  1..100; 
type  Whole_Number  is  integer 

range  1..1000; 

type  My _Own _ List  is  array 

(List-Range)  of  Whole— Number; 
function  Highest  is  new  Largest(List 
—Range,  Whole— Number, 
My_ Own_ List); 

When  function  Highest  is  called,  the 
local  variable  Big  is  set  to  1,  the  lowest 
value  of  the  Whole— Number  type. 


Dr.  Dobb’s  Journal,  August  1986 


116 

591 


Generic  floating-point  types  per¬ 
mit  floating-point  operations.  They 
are  declared  using  digits  <  >.  Listing 
Five,  page  110,  shows  a  generic  func¬ 
tion  that  returns  the  average  values 
of  an  array  of  floating-point  num¬ 
bers.  Once  again  there  are  three  ge¬ 
neric  parameter  types,  requiring 
three  typed  arguments  for  instantiat¬ 
ing  the  generic  function.  The  follow¬ 
ing  creates  a  function  Mean  that  pro¬ 
cesses  arrays  of  floating-point 
numbers,  100  elements  long: 

type  List_Range  is  range  1..100; 
type  Numbers  is  array  (List-Range) 

of  FLOAT; 

function  Mean  is  new  Average!  List 

—Range,  FLOAT,  Numbers); 

Other  generic  types  include  the 
fixed  and  limited  private.  The  generic 
fixed  parameters  are  declared  using 
delta  <  >.  Limited  private  has  strict¬ 
er  access  rules  and  is  declared  using 
|  limited  private. 

For  the  sake  of  brief  listings,  I  have 
shown  so  far  examples  with  one  ge¬ 
neric  routine.  This  does  not  reflect 
any  restrictions,  though.  Multiple  ge¬ 
neric  routines  are  allowed  by  Ada — 
for  example,  you  can  write  a  generic 
library  for  complex  mathematical 
operations  and  functions,  and  this  li¬ 
brary  can  become  a  template  for  rou- 
|  tines  that  handle  different  floating¬ 
point  types. 

Ada  extends  the  types  of  generic 
parameters  to  include  subprograms. 

J  This  feature  has  two  kinds  of  applica- 
j  tions.  The  first  helps  to  create  generic 
functions  with  functional  parame¬ 
ters.  Listing  Six,  page  110,  shows  a  ge¬ 
neric  mathematical  root  finder  that 
uses  Newton's  method.  It  also  uses  a 
generic  floating-point  type  to  make  it 
usable  with  all  floating-point  types. 

!  The  declaration  of  function  F_ o/LX 
is  preceded  by  the  with  keyword. 
This  tells  the  compiler  that  this  is  a 
subprogram  parameter  and  not  an 
ordinary  generic  subprogram.  To  use 
!  the  generic  procedure  Root,  the  cli¬ 
ent  program  must  define  a  function 
that  matches  F_o/l_X — call  it  Cubic 
—Polynom.  The  customized  version 
;  of  Root  is  instantiated  for  the  ordi¬ 
nary  FLOAT  type  as  shown  in  the  fol¬ 
lowing  example: 

function  Newton_ Root  is  new 

RooflFLOAT,  Cubic— Polynom) 


The  second  use  of  generic  subpro¬ 
gram  parameters  is  to  provide  re¬ 
quired  operations  for  generic  types 
that  have  no  predefined  operations. 
Consider,  for  example,  the  task  of 
writing  a  generic  shell  sorting  proce¬ 
dure  that  potentially  handles  an  array 
of  any  data  type.  As  discussed  earlier, 
you  must  resort  to  the  generic  private 
type  parameter.  This  type  does  not 
have  the  much  needed  predefined  in¬ 
equality  operators,  however.  Ada  al¬ 
lows  you  to  overcome  this  obstacle  if 
you  can  supply  these  operators  your¬ 
self.  Listing  Seven,  page  110,  shows  a 
generic  sort  program.  To  instantiate  it, 
you  must  supply  the  name  of  the  in¬ 
equality  operator  you  have  written 
for  the  data  type  involved.  If  it  hap¬ 
pens  to  be  a  standard  type,  you  simply 
supply  the  name  of  the  predefined 
operator.  To  create  a  new  version  for 
sorting  an  array  of  1,000  integers,  for 
example,  you  would  write  the  follow¬ 
ing  lines: 


j  procedure  Sort— Int  is  new 

Shell_Sort( 1000,  INTEGER, Int _ List,"  >  ”) 

I  where  Int— List  is  a  1,000-integer  ar¬ 
ray  type  and  ">  "  refers  to  the  prede¬ 
fined  operator.  Similarly,  you  can 
create  other  versions  to  sort  arrays  of 
records,  as  long  as  you  supply  the 
needed  operator. 


Generic  Routines  in 
Modula-2 

Modula-2  approaches  the  matter  of 
generic  routines  very  differently 
from  the  way  in  which  Ada  does. 
Modula-2  does  not  define  generic 
'  data  types  and  procedures  explicitly. 
Instead,  you  use  its  open-array  fea¬ 
ture,  which  allows  arrays  of  differ¬ 
ent  sizes  but  consistent  data  types  to 
be  passed  to  procedures  and  func¬ 
tions.  The  second  ingredient  is  the 
imported  type  WORD,  which  repre¬ 
sents  a  unit  of  data  storage.  Integers 
and  cardinals  are  stored  in  one 
WORD.  Reals  occupy  two  WORDS. 
User-defined  structures  occupy  as 
many  WORDS  as  are  needed  for  them 


I-  to  fit.  The  bottom  line  is  that  Modula- 
,  2  can  provide  the  equivalent  of  Ada’s 
private  types  by  using  WORD-typed 
open  arrays.  Cardinals  and  integers 
create  one  small  exception  to  the 
!  above — because  they  occupy  one 
WORD,  a  special  but  limited  class  of 
generic  routines  can  be  developed 
for  them. 

Listing  Eight,  page  111,  demon¬ 
strates  a  function  that  searches  ar¬ 
rays  of  cardinals  or  integers,  looking 
for  a  match  to  the  supplied  key  value. 
The  function  returns  a  Boolean  value 
indicating  whether  the  search  is  suc¬ 
cessful.  The  index  of  the  located  ele¬ 
ments  is  also  returned  through  the 
argument-list  variable  Indey.  Notice 
that  the  supplied  search  value  is  an 
integer.  This  is  because  array  ele¬ 
ments  are  forcibly  converted  into  in¬ 
tegers.  As  a  consequence,  the  func¬ 
tion  LinearSearch  can  safely  handle 
arrays  of  integers  and  cardinals  with 
values  ranging  from  0  to  MAX(IN- 
TEGER),  which  is  the  common  range 
of  values  between  the  two  types. 

As  mentioned  earlier,  in  generic 
routines  in  Modula-2,  the  open  array 
of  WORDS  emulates  Ada’s  private 
types,  and  I  discussed  how  these  types 
need  generic  subprogram  parameters 
to  provide  user-definable  operations. 
Modula-2,  however,  permits  proce¬ 
dural  parameter  passing.  This  means 
you  can  supply  Modula-2  procedures 
tailored  to  specific  data  types.  There 
remains  one  last  ingredient:  a  sample 
j  "template”  data  type  needed  when 
J  generic  arrays  are  processed. 

Listing  Nine,  page  111,  shows  a 
Modula-2  procedure  that  performs 
generic  shell  sorting.  The  formal  ar¬ 
gument  list  includes: 

•  The  data  array  L. 

•  Two  sample  template  data  objects. 
They  are  defined  as  arrays  of  WORD 
to  enable  multi-tvo/tD  types,  such  as 
record  structures. 

•The  actual  number  of  data  items. 
This  is  useful  when  arrays  are  par¬ 
tially  filled  with  data. 

•  The  user-definable  procedure  7s- 
Greater  to  provide  the  logical  out¬ 
come  of  comparing  two  data  items. 
This  is  equivalent  to  the  opera¬ 
tor  supplied  to  the  Ada  generic  ver¬ 
sion.  The  user  function  type  UserDe- 
finedProc  is  declared  as: 

TYPE  UserDefinedProc  =  PROCEDURE 
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(ARRAY  OF  WORD,  ARRAY  OF  WORD) : 

BOOLEAN; 

In  comparing  the  Ada  and  Modula- 
2  versions  for  generic  shell  sorting, 
you  can  see  that  Modula-2  requires 
more  internal  procedures.  The  pro¬ 
cedures  Fetchltem  and  Putltem  serve 
to  copy  data  between  the  sorted  ar¬ 
ray  and  the  supplied  sample  object. 
In  the  innermost  FOR  loop,  two  array 
elements  are  copied  into  variables 
Samplel  and  Sample2.  The  user-sup¬ 
plied  IsGreater  function  is  used  to 
compare  the  above  data  items.  If 
needed,  they  are  swapped  simply  by 
writing  them  back  to  the  original  ar¬ 
ray  in  a  switched  order. 

The  role  of  user-defined  functions 
is  most  vital  in  processing  multi- 
WORD  data  types.  For  example,  the 
generic  shell  sorting  procedure 
might  be  called  to  sort  an  array  of  re¬ 
cords.  (See  Table  1,  below.)  The  re¬ 
cord  structure  has  two  fields:  one  for 
the  name;  the  other  for  counting  the 
frequency  of  occurrence.  Now  as¬ 
sume  you  have  defined  a  logical 
function  GreaterFreq  (see  Listing  Ten, 
page  112)  to  compare  two  Frequency 
fields  of  NameUse  type  records.  A 
call  to  ShellSort  to  arrange  a  100- 
member  array  in  order  using  the 
GreaterFreq  function  is  written  as: 

ShellSort(NameList,  Namel,  Name2, 
100,  GreaterFreq) 

Extended  For  Loop 

I  found  an  interesting  extended  for 
loop  in  Professional  Pascal  (from 
MetaWare,  Santa  Cruz,  California). 
Called  the  iterator,  it  is  composed  of 
two  main  parts:  the  iterator  declara¬ 
tion  and  the  extended  for  loop.  Table 
2,  right,  shows  the  general  syntax  of 
an  iterator.  It  takes  two  parameter 
lists:  the  first  is  the  input  list;  the  sec¬ 
ond  is  the  output  list.  Thus  the  itera¬ 
tor  is  capable  of  returning  more  than 
one  value  explicitly,  using  the  Yield 
statement.  The  latter  is  directly  re¬ 
sponsible  for  passing  back  results.  Ta¬ 
ble  2  also  shows  an  alternate  header 
declaration  for  returning  a  single  val¬ 
ue,  and  it  shows  how  the  iterator  is 
invoked  using  the  special  for  loop. 
The  loop  can  have  multiple  counters 
and  must  be  matched  by  the  number 
of  arguments  in  the  output  parame¬ 
ter  list. 

Listing  Eleven,  page  112,  shows  a 


simple  example  using  iterators.  The 
program  reads  two  text  files:  one  con¬ 
tains  names;  the  other,  search  keys. 
Neither  the  names  nor  the  keys  are 
sorted  in  any  order.  The  iterator  Se¬ 
lect  contains  two  nested  loops  to 
match  keys  with  names.  When  a 
match  is  found,  it  '‘yields”  the  indices 
for  the  corresponding  key  and  name. 
This  information  is  used  in  the  ex¬ 
tended  for  loop  to  display  the  name 
and  the  indices  for  the  matching  key 
and  name.  This  shows  a  feature  of 
iterators:  executing  the  extended  for 
loop  body  only  when  values  are  yield¬ 
ed. 

Because  iterators  are  separate  pro¬ 
gram  bodies,  the  algorithms  they  im¬ 
plement  can  be  replaced  by  more  effi¬ 
cient  ones,  which  minimizes  the 
effort  associated  with  the  changes. 
The  extended  for  loops  need  not  be 
altered,  although  they  automatically 
benefit  from  any  increase  in  the  per¬ 
formance  of  the  iterator  bodies.  In  the 
case  of  my  search  example,  the  itera¬ 
tor  can  be  modified  if  either  or  both 


name  and  key  lists  are  sorted.  Putting 
them  in  order  helps  to  shorten  the 
search  time.  The  sorting  can  be  car¬ 
ried  out  by  the  iterator  or,  more  ap¬ 
propriately,  by  another  program. 
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type  NameUse  =  record 

Name  :  ARRAY  [0..29] 
OF  CHAR; 
Frequency :  CARDINAL; 
END; 

VAR  NameList  :  ARRAY  [0..999]  OF 

NameUse; 

Namel ,  Name2  :  NameUse; 


Table  1:  Record  structure  to  sort  names  by  frequency  of  occurrence 


(*  Iterator  declaration  *) 

iterator  <Name>(<  Formal  parameter  list  1  >): 

<Formal  parameter  list  2>); 

(*  Declarations  here  *) 
begin 

(*  Iterator  body  here  *) 

(*  Values  returned  by  a  "Yield”  statement  *) 

Yield(<Formal  parameter  list  2>); 
end; 

(*  Alternate  Iterator  declaration  *) 

iterator  <Name>(< Formal  parameter  list  1  >):  <type_name> 

(*  Declarations  here  *) 
begin 

(*  Iterator  body  here  *) 

(*  Values  returned  by  a  "Yield”  statement  *) 
Yield(<value>); 
end; 

(*  Invoking  the  iterator  *) 

for  < Counter!  >,<Counter2>, . .  .  ,<Counter<n>>  in 
<lterator_Name>(<Argument  list>)  do 
(*  Body  of  loop  *) 


Table  2:  The  general  syntax  for  an  iterator  (extended  for  loop) 
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Unify  Corp.  has  an¬ 
nounced  an  MS-DOS  version 
of  the  Unify  relational  data¬ 
base  management  system 
software.  It  includes  a  full 
set  of  development  tools,  in¬ 
cluding  industry  standard 
SQL  and  a  fourth-genera¬ 
tion  report  writer,  and  is 
compatible  with  Unix.  It 
also  provides  users  with  a 
Host  Language  Interface  to 
C.  Without  the  Host  Lan¬ 
guage  Interface,  Unify  costs 
$995;  the  Host  Language  In¬ 
terface  costs  $495. 

Interpreters 

Version  2.0  of  the  Run/C 
Interpreter  from  Lifeboat 
Associates  includes  a  full¬ 
screen  editor,  improved 
language  implementation, 
and  built-in  graphics  func¬ 
tions  for  IBM  PC  and  com¬ 
patible  systems.  The  built- 
in  editor  uses  cursor  keys 
and  provides  block-move 
and  search-and-replace  ca¬ 
pabilities.  Run/C’s  retail 
price  is  $120. 

Pinnacle  Systems  has 
announced  the  port  of  a 
fully  implemented  version 
of  the  Unix  System  V  oper¬ 
ating  system  for  the  Pinna¬ 
cle  XL.  Pinnacle's  enhance¬ 
ments  to  the  operating 
system  include  the  imple¬ 
mentation  of  a  proprietary 
memory-management-unit 
architecture,  the  structured 
separation  of  low-level  I/O 
tasks  from  operating  sys¬ 
tem  functions,  and  an  en¬ 
hanced  version  of  the  serial 
I/O  routines.  The  retail 
price  is  $12,000. 

Version  4.0  of  Fortrix-C 
from  Rapitech  Systems 
translates  FORTRAN  state¬ 


ments  such  as  ASSIGN, 
PAUSE,  INQUIRE,  and  BACK¬ 
SPACE.  The  program  also 
supports  assumed-size,  ad¬ 
justable,  and  three-dimen¬ 
sional  arrays.  The  program 
runs  on  VAX/VMS,  Unix,  MS- 
DOS,  and  other  systems  on 
IBM,  DEC,  AT&T,  and  Sun 
computers. 

The  Santa  Cruz  Opera¬ 
tion  has  introduced  two 
Unix-based  work-alikes  of 
major  DOS  applications:  SCO 
Professional  and  SCO  Fox- 
Base.  SCO  Professional  of¬ 
fers  Lotus  1-2-3  functiona¬ 
lity,  with  fully  integrated 
spreadsheet,  database,  and 
graphics.  SCO  FoxBase  can 
run  Ashton-Tate's  dBASE  II 
program  in  multiuser 
mode  without  modifica¬ 
tion.  Each  program  costs 
$795. 

Version  2.2  of  Advanced 
Trace86  from  Morgan 
Computing  Co.  offers  pro¬ 
grammers  an  assembly-lan¬ 
guage  interpreter  that  also 
includes  a  full-screen  sym¬ 
bolic  debugger.  It  features 
BASIC-like  commands  such 
as  load,  save,  insert,  delete, 
edit,  list,  trace,  and  run.  It 
can  also  trace  .EXE  or  .COM 
programs  in  disassembled 
format  with  labels  and  vari¬ 
able  names  scanned  from 
the  .MAP  file.  Advanced 
Trace86  sells  for  $175. 

Lattice  has  introduced 
an  RPG  II  Compiler  for  the 
IBM  PC.  It  supports  standard 
MS-DOS  files  plus  the  stan¬ 
dard  PC  keyboard  and 
function  keys.  It  has  ISAM 
files  compatible  with 
dBASE  III  and  includes  spe¬ 
cial  extensions  for  string 
handling.  Additional  utili¬ 
ties  such  as  Sort/Merge  and 
Source  Entry  are  also  avail¬ 
able.  The  RPG  II  Compiler  is 
priced  at  $750. 

Clisp  is  a  LISP  interpreter 
from  Westcomp  that  is 
written  in  the  C  language. 
It  performs  basic  LISP  func¬ 


tions  as  well  as  functions 
defined  in  a  library,  and 
definitions  can  be  saved  to 
or  loaded  from  disk.  Clisp 
can  run  under  MS-DOS,  Ver¬ 
sion  2,  or  later.  The  pack¬ 
age  costs  $69.95. 

Ryan  McFarland  Corp. 
has  announced  the  avail¬ 
ability  of  RM/COBOL  with 
Informix-ESQL/COBOL  (em¬ 
bedded  SQL  for  COBOL).  This 
capability  allows  micro¬ 
computer  RM/COBOL  users 
to  access  Relational  Data¬ 
base  Systems’  Informix-SQL 
relational  database  via  SQL 
statements  embedded  in 
their  COBOL  programs. 
These  programs  pass 
through  an  RDS  translator 
to  convert  SQL  statements  to 
COBOL  prior  to  compilation; 
the  translated  microcom¬ 
puter  COBOL  code  can  then 
interface  with  the  relation¬ 
al  database. 

Application 

Development 

Allen,  Emerson  &  Frank¬ 
lin  has  unveiled  Version  2 
of  the  GTP  Development 
System  and  a  Professional 
Model  of  GTP.  The  new  ver¬ 
sion  features  multiple- 
screen  applications,  a  con¬ 
text-sensitive  help 

function,  a  database  man¬ 
ager,  and  global  search  cri¬ 
teria.  It  costs  $150. 

SofCap  has  announced 
H.  D.  Tuneup,  a  disk-opti¬ 
mization  package  for  IBM 
and  compatible  PCs.  H.  D. 
Tuneup  eliminates  the 
fragmentation  DOS  causes 
in  a  file  system.  After  a 
tuneup,  every  file  is  inter¬ 
nally  contiguous  and  each 
file  is  physically  adjacent 
to  its  directory  neighbors. 
The  list  price  is  $39.95  plus 
shipping  and  handling. 

Visible  Systems  Corp. 
has  released  The  Visible 
Rules,  a  productivity  tool 
for  software  engineering 
development  and  mainte¬ 


nance.  The  Visible  Rules 
software  integrated  with 
The  Visible  Analyst  dia¬ 
gramming  tool  provides  a 
CAD-like  software  design 
tool  based  on  Yourdon 
rules  and  Gane  and  Sarson 
rules.  The  major  features 
of  this  software  are  an  en¬ 
hanced  graphics  package 
oriented  for  data  flows,  de¬ 
signs  examined  on  both  a 
local  and  global  basis,  and  a 
level-to-level  balancing 
feature  that  verifies  the 
conservation  of  data  flow 
by  comparing  a  diagram 
and  its  lower  levels.  The 
Visible  Rules  software  is 
available  for  $595. 

Martian  Technologies 
has  announced  a  16-bit  Vir¬ 
tual  Disk  System  for  the 
TurboDOS  operating  sys¬ 
tem.  The  Virtual  Disk  Sys¬ 
tem  features  data  transfers 
using  the  special  80186/ 
80286  block  I/O  instruc¬ 
tions.  The  average  transfer 
rate  is  888,888  bytes  per  sec¬ 
ond  using  an  8-MHz  80186 
or  more  than  1.1  megabytes 
per  second  using  a  10-MHz 
CPU.  All  data  reads  and 
writes  are  checked  for 
hardware  parity  errors  on 
a  sector-by-sector  basis. 
Any  parity  errors  are 
passed  back  to  TurboDOS 
for  error  processing.  The 
pricing  for  a  2-megabyte 
SemiDisk  with  Virtual  Disk 
software  is  $1,495;  the  Vir¬ 
tual  Disk  Master  costs 
$3,495. 

For  the  IBM  PC/XT 

A&T  Systems  has  released 
DMS/The  Disk  Manage¬ 
ment  System  for  IBM  PCs 
and  compatibles.  DMS  is  a 
full-screen,  menu-driven 
software  package  that  al¬ 
lows  users  to  recover  lost 
data,  increase  system 
speed  and  reliability,  lo¬ 
cate  or  reorganize  infor¬ 
mation,  and  execute  appli¬ 
cations  using  function 
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keys.  DMS  has  more  than  40 
disk-  and  file-management 
functions  available.  It  is 
priced  at  $99. 

iDEAssociates  has  intro¬ 
duced  Supermax/EMS,  a 
high-performance  multi¬ 
function  board  for  the  IBM 
PC/AT.  It  offers  expanded, 
extended,  and  convention¬ 
al  memory;  two  serial  ports 
and  one  parallel  port  as 
standard  features;  and  a 
memory  capacity  of  up  to  4 
megabytes.  The  board's  ex- 
panded-memory  feature  is 
compatible  with  software 
applications  written  to  the 
Lotus/Intel/Microsoft  Ex¬ 
panded  Memory  Specifica¬ 
tion  (EMS).  The  price  for  Su¬ 
permax/EMS  ranges  from 
$495  for  a  bare  board  to 
$2,595  for  4  megabytes  of 
memory. 

American  Computer  & 
Peripheral’s  XTsr  uses  the 
high-performance,  16-bit, 
8088-2  microprocessor  and 
has  up  to  640K  RAM  on  a 
four-layer  motherboard. 
Eight  sockets  provide  64K 
of  usable  EPROM  for  repro¬ 
grammable  firmware  and 
BIOS.  The  XTsr  has  eight  ex¬ 
pansion  slots  for  memory, 
up  to  2.5  megabytes,  and 
other  I/O  function  cards. 
Other  features  include 
automatic  self-test  of  sys¬ 
tem  components  and 
memory  at  power-up,  MS- 
DOS  2.11,  and  Macro-As¬ 
sembler  software  and  a 
speaker  for  audio  and  mu¬ 
sic  applications.  The  XTsr  is 
priced  at  $2,560. 

Aristo  Computers  has 
added  640K  motherboard 
upgrades  for  the  IBM  PC/XT 
and  the  Compaq  Portable  to 
its  product  line.  The  up¬ 
grades  are  fully  compatible 
with  all  DOS  versions  later 
than  l.xx.  They  are  not  suit¬ 
able  for  the  various  XT 
clones.  Retail  prices  are  $49 
for  the  XT  upgrade  and  $29 
for  the  Compaq  upgrade. 

Graphics 

Under  an  agreement  with 


Graphic  Software  Sys¬ 
tems,  IBM  has  introduced 
a  TopView-compatible 
graphics  application  devel¬ 
opment  package,  the  IBM 
PC  Graphics  Development 
Toolkit  1.1.  This  package  al¬ 
lows  programmers  to  sup¬ 
port  TopView  1.1  with  ap¬ 
plications  using  pop-up 
menus,  windows,  icons, 
and  other  bit-map  images. 
Applications  are  compati¬ 
ble  with  emerging  high- 
performance  graphics  pro¬ 
cessor  chips  through  GSS- 
CGI  software  and  firmware 
products. 

Paradise  Systems  has 
introduced  a  single-chip 
implementation  of  the  IBM 
Enhanced  Graphics  Adap¬ 
tor  standard  that  supports 
all  the  other  display  stan¬ 
dards  for  the  office  market. 
Pega-1  is  a  single  84-pin  in¬ 
tegrated  circuit  that  lets 
OEMs  implement  the  IBM 
monochrome  and  color 
graphics  standards  (MDA 
and  CGA,  respectively), 
Hercules  monochrome 
graphics,  Plantronics  Col- 
orPlus,  and  Paradise  color 
simulation  on  a  mono¬ 
chrome  monitor.  Develop¬ 
ment  samples  with  the 
chip  in  a  board  are  avail¬ 
able  for  $200. 

Amdek  Corp.’s  RGB  color 
monitor  is  compatible  with 
the  IBM  Professional 
Graphics  Adaptor.  It  can 
display  256  colors  at  a  time, 
selected  from  a  4,096  color 
palette.  The  Color  730  PGA- 
compatible  Analog  RGB 
monitor  is  available  for 
$1,099. 

Attachmate  Corp.  has 

unveiled  its  3270  Host 
Graphics  Program,  a  soft¬ 
ware  package  that  allows 
PC  users  to  access  host-gen¬ 
erated  color  graphics.  The 
product  uses  the  compa¬ 
ny’s  IBM  Irma-compatible  3- 
N-l  Coax  Adapter  and  3270- 
PC  Emulation  Program  to 
manage  up  to  four  concur¬ 
rent  host  sessions.  Any 
combination  of  3270  text  or 
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graphics  sessions,  as  well  as 
a  PC  application,  can  be  ac¬ 
tive  simultaneously.  Both 
the  standard  IBM  Color 
Graphics  Adaptor  and  the 
high-resolution  Enhanced 
Graphics  Adaptor  are  sup¬ 
ported.  The  3270  Host 
Graphics  Program  retails 
for  $595;  the  3-N-l  Coax 
Adapter  retails  for  $1,195. 

Communications 

Network  Software  Asso¬ 
ciates  has  introduced  an 
enhanced  version  of  its 
AdaptModem,  a  combina¬ 
tion  high-speed  synchro¬ 
nous  modem  and  Synchro¬ 
nous  Data  Link  Control 
communications  adapter 
for  IBM  PC,  PC/XT,  PC/AT, 
and  compatibles.  Adapt¬ 
Modem  incorporates  the 
company's  Automatic  Call 
Control  (ACC)  facilities.  It  in¬ 
cludes  auto-dial,  auto-an¬ 
swer,  automatic  redial,  a 
180-entry  call  directory  for 
speed  dialing  or  unattend¬ 
ed  automatic  operation, 
automatic  phone-line  and 
modem  testing  proce¬ 
dures,  plus  modem  config¬ 
uration  options.  AdaptMo¬ 
dem  is  priced  at  $795. 

Electronic  Specialists’ 
Kleen  Line  Security  models 
are  available  for  standard  4- 
pin  telephone  modular 
connectors  (FJ-11)  and  the 
wider  8-pin  connectors  (RJ- 
45).  The  system  uses  mod¬ 
ern  two-stage  semiconduc¬ 
tors  and  gas-discharge-tube 
suppression  techniques.  An 
isolated  ground  is  em¬ 
ployed  to  isolate  equipment 
from  lightning  discharge 
current.  The  cost  is  $73.95. 

Move-It,  Version  4,  from 
Woolf  Software  Systems 
features  automatic  file 
compression,  keyboard 
macros,  scripting  files, 
XMODEM  protocol  support, 
infilter  and  outfitter  com¬ 
mands,  and  the  ability  to 
send  and  receive  files  auto¬ 


matically.  Move-It,  Version 
4,  retails  for  $150  and  runs 
on  the  IBM  PC/XT/ AT  and 
compatibles. 

SoftStyle  has  an¬ 
nounced  Version  2.1  of  its 
Printworks  for  Lasers  soft¬ 
ware  for  IBM  PC/XT/AT 
computers  and  compati¬ 
bles.  The  software  offers 
memory-resident  'power 
printing”  typesetting  func¬ 
tions  and  support  for  three 
additional  laser  printers. 
The  new  version  adds  35 
typesetting-like  commands 
that  can  be  activated  from 
a  pop-up  menu  and  insert¬ 
ed  directly  into  any  text 
file,  using  any  Epson  MX-80 
printer-compatible  PC  ap¬ 
plication  software.  Among 
the  35  laser-printing  func¬ 
tions  the  user  can  select  are 
26  built-in  laser-printer 
typefaces,  any  cartridge  in 
5  printer  font-cartridge 
slots,  6  downloaded  fonts, 
26  foreign-language  and 
mathematical  symbol  sets, 
26  point  sizes,  6  pitches,  3 
line  spacings,  4  special 
shadings,  and  a  variety  of 
type  styles.  Printworks  for 
Lasers,  Version  2.1,  is 
priced  at  $125. 

Microcom’s  High  Densi¬ 
ty  Modem  System  (HDMS) 
offers  password  protection 
for  both  the  modem  and 
the  operator’s  consol,  as 
well  as  dial-back  security. 
HDMS  consists  of  a  chassis,  a 
controller,  and  dual  mo¬ 
dem  cards.  Its  price  ranges 
from  $1,300  to  $1,500,  de¬ 
pending  on  configuration. 

The  Netway  100  Dual  Ses¬ 
sion  from  Tri-Data  adds 
dual-session  and,  in  some 
cases,  windowing  capabili¬ 
ties  to  the  Netway  System, 
which  is  designed  to  link  in¬ 
compatible  hosts,  termi¬ 
nals,  personal  computers, 
and  local-area  networks. 
With  the  Net  way  System, 
virtually  any  ASCII  termi¬ 
nal,  as  well  as  the  AT&T 
4540  keyboard  display,  can 
be  used  to  access  a  variety 
of  host  computer  environ- 
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ments,  including  those 
from  IBM,  DEC,  Sperry  Uni- 
vac,  Honeywell,  and  Data 
General. 

Storage 

The  Data  Vault  Subsystems 
from  Peripheral  Tech¬ 
nology  Corp.  feature 
mainframe-type  Winches¬ 
ter  disk  drives  using  the 
Enhanced  Standard  Device 
Interface.  These  drives  of¬ 
fer  formatted  capacities  of 
150  to  320  megabytes,  data 
transfer  rates  of  1.25  mega¬ 
bytes/second,  and  average 
access  times  of  less  than  20 
ms.  A  microprocessor- 
equipped  intelligent  flop¬ 
py-  and  hard-disk  control¬ 
ler  offers  full  16-bit  direct 
memory  access  and  simul¬ 
taneous  data  transfer. 
Prices  start  at  $6,995  for  an 
internal  mount  150-mega- 
byte  disk  and  controller 
and  at  $8,495  for  an  inter¬ 
nal  150-megabyte  disk,  55- 
megabyte  streaming  tape, 
and  controller. 

Artificial 

Intelligence 

LISP  Machine’s  Object- 
Lisp  is  a  portable  second- 
generation  object-oriented 
programming  paradigm 
designed  to  make  the 
power  of  object-oriented 
programming  more  acces¬ 
sible  to  programmers  at  all 
levels.  ObjectLisp  features 
portability,  software  devel¬ 
opment,  implementation 
in  Common  Lisp,  and  pub¬ 
lic-domain  status. 

Miscellaneous 

A  business  information  ser¬ 
vice  with  data  on  more 
than  10  million  public  and 
private  companies  is  avail¬ 
able  from  Dialog  Informa¬ 
tion  Services.  Five  major 
categories  of  applications 
are  available  through  Dia¬ 
log  Business  Connection: 
corporate  intelligence,  fi¬ 
nancial  screening,  products 
and  markets,  sales  pros¬ 
pecting,  and  travel  plan¬ 


ning.  A  start-up  package  for 
Dialog  Business  Connection 
costs  $145  and  includes  $100 
worth  of  free,  on-line  time 
for  orientation  during  the 
first  month,  a  private  pass¬ 
word,  an  IBM-compatible 
communications  software 
disk,  and  a  user’s  guide 
with  "where-to-find-it” 
listings. 

Advanced  Logic  Re¬ 
search’s  Fast/286  is  an  IBM 
PC/AT  bus-  and  form-com¬ 
patible  CPU  motherboard 
that  features  512K  to  2 
megabytes  on-board  mem¬ 
ory,  an  8-MHz  CPU  clock,  a 
parallel  printer  port,  and 
parity  checking  RAM.  It  op¬ 
erates  under  DOS  3.0  or  3.1 
and  Xenix.  The  system  is 
priced  at  $2,495. 

Computer  Friends  has 
announced  Proteus,  a  par¬ 
allel  double  buffer  and 
data  switch.  Proteus  fea¬ 
tures  a  buffer  on  each  of 
the  two  output  ports,  data 
switch,  control  manually 
or  via  software,  and  multi¬ 
ple-copy  capability  on  both 
ports.  Its  cost  is  $199. 

The  GMX  Micro-20  Sin¬ 
gle  Board  Computer  com¬ 
bines  a  12.5-  or  16.67-MHz 
Motorola  MC68020  32-bit 
microprocessor  and  an  op¬ 
tional  MC68881  floating¬ 
point  coprocessor  with  2 
megabytes  of  32-bit-wide 
RAM,  up  to  256K  of  32-bit- 
wide  EPROM,  four  serial 
ports,  an  8-bit  parallel  port, 
a  5V4-inch  floppy-disk  con¬ 
troller,  a  SASI  peripheral  in¬ 
terface,  and  a  time-of-day 
clock  with  battery  backup. 
A  16-bit  expansion  connec¬ 
tor  allows  the  addition  of 
the  off-the-shelf  or  custom 
I/O  interfaces.  The  12.5- 
MHz  version  costs  $2,750. 

Dwarf  Nebula  Software 
has  announced  666-Shell,  a 
DOS  visual  shell  that  gives 
users  a  fully  interactive 
sorted  directory,  a  file 
browser,  a  Where  Is  pro¬ 
gram,  an  Egrep  program,  a 
Sort  routine,  and  an  intelli¬ 
gent  disk-copy  routine. 
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The  director  supports  mul¬ 
tiple  commands  at  the  DOS 
prompt,  full  command 
aliasing,  command  recall, 
and  full  edit  at  the  DOS 
prompt.  The  cost  is  $39. 

Omnitronix  is  offering  a 
stand-alone,  Z80-based,  RS- 
232  microcontroller  for 
commercial  applications. 
The  board  provides  8K 
EPROM;  one  bank  of  dy¬ 
namic  RAM;  and  two  bidir¬ 
ectional,  asynchronous, 
RS-232  serial  ports.  The 
RAM  addressing  supports 
16K,  64K,  or  256K  DRAM. 
The  controller  comes  with 
a  UL/CSA-approved  wall 
power  supply.  The  single¬ 
piece  price  for  the  pro¬ 
grammers’  kit  is  $349;  the 
technical  programming 
pack  is  available  separately 
for  $14.95. 

Harris/Lanier  Business 
Products  has  announced 
HarrisDesk,  a  word-pro- 
cessing  package  that  can  be 
run  in  a  multiuser  configu¬ 
ration  via  the  Concept  4300 
personal-computer  work¬ 
group  server  or  as  a  stand¬ 
alone  product  on  the  Har¬ 
ris  2000  PC  or  any  IBM- 
compatible  personal 
computer.  Other  features 
of  HarrisDesk  include 
Speller  and  Task.  The 
Speller  function  uses  a 
90,000-word  main  dictio¬ 
nary  and  a  6,500-word 
user-definable  dictionary 
to  verify  spelling  on  docu¬ 
ments.  This  function  can 
be  performed  on  screen  or 
run  in  the  background. 

Reference  Map 

A&T  Systems  Inc.,  12904 
Olivine  Wy.,  Silver  Spring, 
MD  20904;  (301)  384-1425. 
Reader  Service  Number  16. 
Advanced  Logic  Re¬ 
search  Inc.,  2991  E.  White 
Star  Ave.,  Anaheim,  CA 
92806;  (714)  666-2951.  Read¬ 
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Allen,  Emerson  &  Frank¬ 


lin  Inc.,  P.O.  Box  928,  Katy, 
TX  77492;  (713)  391-8570. 
Reader  Service  Number  18. 
Amdek  Corp.,  2201  Lively 
Blvd.,  Elk  Grove  Village,  IL 
60007;  (312)  364-1180.  Read¬ 
er  Service  Number  19. 
American  Computer  & 
Peripheral  Inc.,  2720 
Croddy  Wy.,  Santa  Ana,  CA 
92704;  (714')  545-2004.  Read¬ 
er  Service  Number  20. 
Aristo  Computers,  16811 
El  Camino  Real,  Ste.  213, 
Houston,  TX  77058;  (800) 
3ARISTO,  in  TX  (713)  480- 
6288.  Reader  Service  Num¬ 
ber  21. 

Attachmate  Corp.,  3241 
118th  St.  SE,  Bellevue,  WA 
98005;  (206)  644-4010.  Read¬ 
er  Service  Number  22. 
Computer  Friends  Inc., 
6415  S.W.  Canyon  Ct.,  Ste. 
10,  Portland,  OR  97221;  (503) 
297-2321.  Reader  Service 
Number  23. 

Dialog  Information  Ser¬ 
vices  Inc.,  3460  Hillview 
Ave.,  Palo  Alto,  CA  94304; 
(415)  858-3742.  Reader  Ser¬ 
vice  Number  24. 

Dwarf  Nebula  Software, 
P.O.  Box  46,  Dept.  S,  Sugar- 
land,  TX  77487.  Reader  Ser¬ 
vice  Number  25. 
Electronic  Specialists 
Inc.,  171  S.  Main  St.,  Natick, 
MA  01760;  (800)  225-4876,  in 
MA  (617)  655-1532.  Reader 
Service  Number  26. 

GMX  Inc.,  1337  W.  37th  PL, 
Chicago,  IL  60609;  (312)  927- 
5510.  Reader  Service  Num¬ 
ber  27. 

Graphic  Software  Sys¬ 
tems  Inc.,  9590  S.W.  Gemi¬ 
ni  Dr.,  P.O.  Box  4900,  Bea¬ 
verton,  OR  97005;  (503)  641- 
2200.  Reader  Service 
Number  28. 

Harris/Lanier  Business 
Products  Inc.,  1700  Chan¬ 
tilly  Dr.  NE,  Atlanta,  GA 
30324;  (404)  329-8000.  Read¬ 
er  Service  Number  29. 
IDEAssociates  Inc.,  35 
Dunham  Rd.,  Billerica,  MA 
01821;  (617)  663-6878.  Read¬ 
er  Service^) umber  30. 
Lattice  Inc.,  P.O.  Box  3072, 
Glen  Ellyn,  IL  60138;  (312) 


858-7950.  Reader  Service 
Number  31. 

Lifeboat  Associates,  55  S. 
Broadway,  Tarrytown,  NY 
10591  (914)  332-1875.  Read¬ 
er  Service  Number  32. 

LISP  Machine  Inc.,  Bldg.  4 
Andover  Tech  Center,  6 
Tech  Dr.,  Andover,  MA 
01810;  (617)  682-0500.  Read¬ 
er  Service  Number  33. 
Martian  Technologies, 
8348  Center  Dr.,  Ste.  F,  La 
Mesa,  CA  92041;  (619)  464- 
2924.  Reader  Service  Num¬ 
ber  34. 

Microcom,  1400A  Provi¬ 
dence  Hwy.,  Norwood,  MA 
02062;  (617)  762-9310.  Read¬ 
er  Service  Number  35. 
Morgan  Computing  Co., 
P.O.  Box  112730,  Carrollton, 
TX  75011;  (214)  245-4763. 
Reader  Service  Number  36. 
Network  Software  Asso¬ 
ciates  Inc.,  22982  Mill 
Creek,  Laguna  Hills,  CA 
92653;  (714)  768-4013.  Read¬ 
er  Service  Number  37. 
Omnitronix  Inc.,  P.O.  Box 
43,  Mercer  Island,  WA 
98040;  (206)  236-2983.  Read¬ 
er  Service  Number  38. 
Paradise  Systems  Inc., 
217  E.  Grand  Ave.,  South 
San  Francisco,  CA  94080; 
(415)  588-6000.  Reader  Ser¬ 
vice  Number  39. 
Peripheral  Technology 
Corp.,  1331  Harlan  Ln., 
Lake  Forest,  IL  60045;  (312) 
941-8787.  Reader  Service 
Number  40. 

Pinnacle  Systems  Inc., 
10355  Brockwood  Rd.,  Dal¬ 
las,  TX  75238;  (214)  340-4941. 
Reader  Service  Number  41. 
Rapitech  Systems  Inc., 
Montebello  Corporate 
Park,  Suffern,  NY  10901; 
(914)  368-3000.  Reader  Ser¬ 
vice  Number  42. 
Ryan-McFarland  Corp., 
609  Deep  Valley  Dr.,  Rolling 
Hills  Estates,  CA  90274;  (213) 
541-4828.  Reader  Service 
Number  43. 

Santa  Cruz  Operation 
(The),  500  Chestnut  St.,  P.O. 
Box  1900,  Santa  Cruz,  CA 
95061;  (408)  425-7222.  Read¬ 
er  Service  Number  44. 


SofCap  Inc.,  P.O.  Box  131, 
Cedar  Knolls,  NJ  07927; 
(201)  386-5876.  Reader  Ser¬ 
vice  Number  45. 

SoftStyle  Inc.,  Hawaii  Kai 
Office  Building,  Ste.  205, 
7192  Kalanianaole  Hwy., 
Honolulu,  HI  96825;  (808) 
396-6368.  Reader  Service 
Number  46. 

Tri-Data,  505  E.  Middle- 
field  Rd.,  Mountain  View, 
CA  94043  (415)  969-3700. 
Reader  Service  Number  47. 
Unify  Corp.,  4000  Kruse 
Way  PL,  Lake  Oswego,  OR 
97034-2548;  (503)  635-6265. 
Reader  Service  Number  48. 
Visible  Systems  Corp., 
336  Baker  Ave.,  Concord, 
MA  01742;  (617)  369-1800. 
Reader  Service  Number  49. 
Westcomp,  Software  En¬ 
gineering  Group,  517  N. 
Mountain  Ave.,  Upland,  CA 
91786-5016.  Reader  Service 
Number  50. 

Woolf  Software  Systems 
Inc.,  6754  Eton  Ave.,  Can- 
oga  Park,  CA  91303;  (818) 
703-8112.  Reader  Service 
Number  51. 

— Wendelin  Colby 
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SWAINE'S  FLAMES 


In  Bloomington,  Indiana,  where  I 
once  spent  nine  years,  the  humid¬ 
ity  and  temperature  fight  it  out 
around  ninety  at  this  time  of  year.  In 
these  long,  hot,  summer  days,  Bloo¬ 
mington  boy  John  Cougar  Mellen- 
camp  advises,  we  need  a  way  to  cool 
ourselves  down. 

Even  for  those  who  didn't  grow  up 
in  a  Mellencamp  Midwest,  the  last 
weeks  of  summer  can  evoke  visions 
of  carnivals  and  lightning  bugs.  So 
pop  in  the  American  Fool  tape,  pop 
the  tab  off  a  Leinenkugel,  and  put 
your  feet  up.  Here's  some  light  sum¬ 
mer  reading. 

Close  enough  for  rock  and  roll 

but  inadequate  for  physics  could  de¬ 
scribe  today’s  programming  lan¬ 
guages,  according  it)  B.  Manner. 

Except  in  atmospheric  writing  like 
the  first  paragraph  above,  compar¬ 
ing  temperature  and  humidity  is  a 
no-no.  In  physics  classes  we  learned 
that  we  can  meaningfully  multiply 
or  divide  quantities  that  involve  dif¬ 
ferent  units  of  measurement,  but  not 
add,  subtract,  or  compare  them.  In 
our  computer  classes  we  apparently 
forgot  the  lesson,  as  no  computer  lan¬ 
guage  today  implements  these  well- 
known  computational  rules. 

Manner,  writing  in  the  March  1986 
SIGPLAN  Notices,  proposes  changing 
this  He  would  extend  the  syntax  of 
high-level  languages  so  that  units 
such  as  centimeters,  grams,  and  sec¬ 
onds  could  be  represented  as  data 
types,  with  appropriate  compile¬ 
time  checks  on  their  combination. 
Units  could  be  defined  in  terms  of 
other  units,  as  erg  —  g  ‘cm  *cm/(sec- 
'sect,  and  scale  factorscould  be  intro¬ 
duced,  as  k  —  1000;  kg  —  k  *g. 

it's  an  interesting  idea  that  would 
automate  a  useful  checking  tech¬ 
nique  familiar  to  every  physics  stu¬ 
dent.  I  recommend  the  article. 

A  few  American  kids  doing  the 
best  they  can  are  the  subjects  of  Pro¬ 
grammers  at  Work,  a  new  hook  of  in¬ 
terviews  with  programmers  pub¬ 
lished  by  Microsoft  Press. 


The  interviewer  and  editors  did  an 
excellent  job  of  bringing  out  the  per- 
j  sonalities  and  the  ideas.  You'll  find 
i  Kildall  and  Gates  and  Bricklin  and 
j  Frankston  here,  as  well  as  some  less  j 
]  celebrated  but  thoughtful  software  ! 
!  artists  such  as  Jaron  Lanier.  You  can  | 
i  recommend  this  l>ook  to  your  non-  j 
programmer  friends  and  still  find  it 
j  worthwhile  reading  for  yourself. 

Everyone  needs  a  hand  to  hold 
on  to,  and  Carnegie-Mellon  Universi¬ 
ty  is  a  little  closer  to  linking  up  all  its 
'  students  with  a  network  of  3-M  work-  j 
j  stations  (so  called  because  each  user  j 
|  will  have  at  least  a  megabyte  of  mem-  ! 
I  ory,  a  processing  speed  of  at  least  one 
j  MIPS,  and  a  million-plus  pixel  display) 
and  a  powerful  distributed  file  system 
called  Vice,  there  are  at  least  three 
!  computers  that  CMU  judges  capable  of 
j  functioning  as  workstations  on  the 
;  system:  dec's  MicroVAX,  a  version  of 
|  the  Apollo  Sun,  and  the  IBM  RT/PC. 

Carnegie-Mellon  is  keeping  the  svs-  i 
|  tern  as  open  as  possible  to  different 
vendors’  advanced  workstations. 

I  can  think  of  two  developments 
j  that  could  result  from  this  ambitious  j 
j  project.  One:  the  price  of  such  work- 
;  stations  will  come  down.  CMU  offi- 
|  cials  are  predicting  a  price  of  around 
$3,000  by  next  fall.  Two:  at  CMU  anv- 
j  way,  "Miami  Vice"  could  soon  lose  j 
:  rating  points  to  Pittsburgh  Vice. 

In  my  weakest  moments,  I  listen 
;  to  my  cousin  Corbett's  software 
schemes.  His  latest  is  Distributed 
Semantics. 

PROECX;  and  other  logical  languages 
I  are  fine  as  far  as  they  go,  Corbett  says. 


But,  like  other  languages,  all  they  do  is 
supply  a  syntax  for  the  expression  of 
ideas;  they  lack  a  semantic  compo- 
nent.  Rules  and  facts  take  their  mean¬ 
ings  from  variables  that  are  them¬ 
selves  left  undefined. 

In  expert  systems  for,  sav,  medical 
diagnosis,  it  is  critically  important  that 
variables  have  reliable  meanings. 

Corbett  thinks  the  solution  is  Dis-  j 
tributed  Semantics.  We  just  need  to 
be  sure  that  when  two  programs  use 
the  same  name,  they  are  referring  to 
the  same  class  of  object.  People  man¬ 
age  this  by  consulting  a  dictionary; 
programs  could  consult  a  dictionary 
of  PROLOG-style  facts. 

Any  such  dictionary  would  be  inad¬ 
equate  at  first;  it  would  have  to  be  able 
to  learn  and  grow.  It  would  gradually 
accumulate  connotative  meanings 
and  would  grow  into  a  working  lexi¬ 
cal  model  of  the  world. 

Until  we  have  such  a  dictionary, 
Corbett  suggests,  all  PROLOG  pro¬ 
grammers  should  adopt  a  uniform 
commenting  style  for  defining  vari¬ 
ables.  For  now,  these  comments 
would  simply  tell  the  reader  what 
the  variable  name  refers  to.  When 
the  dictionary  becomes  available, 
though,  a  compiler  directive  would 
cause  these  comments  to  be  inter¬ 
preted  as  calls  to  the  dictionary.  Thus 
your  comment 

/*  In  this  program,  "horse"  means 
anything  you  can  put  a  saddle  on.  */ 

would  become  a  clause  such  as 

horse(X)  if  envdhis  program)  and 
can_wear(X,  saddle). 

with  the  definitions  of  can^wcar  and 
saddle  to  be  sought  in  the  dictionary. 

Corbett  is  selling  a  commenting 
style  manual  lor  $19.97,  prepaid. 

j/ff'cloti 

Michael  Swaine 
editor-in-chief 
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with  resident  programs  doing  file  I/O. 

THE  RIGHT  TO  ASSEMBLE:  The  W  orm  Memory  Test 

by  Jan  W.  Steinman 

A  self-overlaying  test  to  help  diagnose  memory  errors 
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About  the  Cover 

The  architectural  illustration  for 
this  cover  was  done  by  Robert  H. 
Frank.  The  photograph  was 
done  by  Michael  Carr/ Pacific 
Horizons. 


This  l»»ue 

Many  algorithms  now  used  on 
computers  have  their  roots  in 
mechanical  processes.  This 
month,  we  present  two  such  al¬ 
gorithms;  one  that  replaces  the 
draftsman  s  spline  and  one  that 
sorts  in  an  old  fashioned  ibut 
sometimes  faster'  way.  Michael 
Swaine  offers  some  thoughts  on 
Borland's  latest  product,  and  we 
present  a  review  of  several  PC 
speed  boosters.  Allen  Holub  and 
Rav  Duncan  provide  tasty  tidbits, 
and  Jan  Steinman  brings  us  a 
very  unusual  memory  test. 


IVext  Issue 

In  October,  we  ll  take  a  close  look 
at  Intel’s  80386  chip.  What  does  it 
really  offer,  and  how  do  you  up¬ 
grade  from  the  80286?  We  ll  also 
demonstrate  some  interesting 
code  for  the  NS320xx  chip  set. 
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and  programs  that  de¬ 
velop  new  problem- 
heuristics 


Sthe 

•Next  Big  I'hing  i.s  H 
cl  neglected  old  thing 
When  I  was  a  gradu- 
ate  student  I  look  all  gggg 
the  M  classes  and  sem  1|®| 
inars  I  could.  In  a  class  TJK 

taught  by  Gene  (Sy'i  j 
Freuder,  who  had  just  Fill  / 
arrived  from  MIT  i\j  -  i 
where  he  had  studied  ll  » 

under  Patrick  Henry  W _ .1 

Winston,  I  wrote  an  expert  system 
for  draw  poker.  At  that  time,  expert 
systems  interested  me,  but  not  as 
much  as  the  challenge,  posed  by  an¬ 
other  of  my  professors,  Doug  Hof- 
stadter,  of  writing  a  program  that 
could  generate  analogies,  a  problem 
in  the  area  of  machine  learning.  My 
expert  system  worked,  after  a  fash¬ 
ion,  and  1  never  got  anywhere  with 
the  machine  learning  program. 
Looking  back  over  the  past  few 
years,  it  may  seem  that  the  same 
could  be  said  for  the  entire  field  of  AI: 
expert  systems  work;  machine  learn¬ 
ing  never  got  started. 

I  once  believed  that,  but  now  I  think 
i  was  wrong.  Research  in  machine 
learning  has  certainly  taken  a  back 
seat  to  expert  systems  work  since  my 
graduate  school  days.  The  results  are 
evident:  By  focusing  on  narrow  prob¬ 
lem  areas  and  domain-specific  knowl¬ 
edge,  workers  in  expert  systems  have 
created  some  very  powerful  practical 
tools  and  turned  a  technique  into  an 
industry.  The  Business  section  of  the 
July  7,  1986,  San  Jose,  California,  San 
Jose  Mercury  News,  amid  grumblings 
about  the  industrywide  slump  in  soft¬ 
ware,  computers,  and  electronics, 
noted  that  one  expert  systems  compa¬ 
ny,  Teknowledge,  was  doing  spectac¬ 
ularly  well. 

Machine  learning  never  makes  it 
into  the  Mercury  News ;  nevertheless, 
research  in  machine  learning  has 
continued  quietly  over  the  years — 
and  not  without  results.  There  are, 
for  example,  programs  whose  per¬ 
formance  improves  with  experience 


solving 

I  here 

(  I  that  produce  interest 

ing  analogies. 

1  hope  that  machine 
learning  is  about  to 
i  I  capture  the  imagina- 
I  /{  tions  of  programmers 
;  and  venture  capital- 

- ■  ists.  The  potential 

benefits  from  work  in  machine 
learning  are,  I  believe,  far  greater 
than  the  benefits  of  expert  systems 
work.  Understanding  natural  lan¬ 
guage,  for  example,  requires  the  abil¬ 
ity  to  learn  new  concepts  rather  than 
requiring  a  tody  of  expert  knowl¬ 
edge.  And  by  the  very  nature  of  the 
learning  process,  it  seems  that  any 
learning  program  would  have  to  be 
general  in  application,  suggesting 
that  we  would  only  need  one.  Given 
one,  we  could  clone  it. 

Also  by  the  nature  of  the  learning 
process,  the  performance  of  learning 
programs  will  probably  be  unreli¬ 
able,  and  this  may  force  us  to  start 
looking  at  programs  in  a  different 
way.  Induction  and  generalization 
seem  incompatible  with  the  provabil¬ 
ity  and  reliability  necessary  for  Star 
Wars-type  projects.  Making  mistakes 
may  well  be  an  inextricable  compo¬ 
nent  of  learning.  We  may  one  day 
find  ourselves  praising  programs  for 
their  efforts  as  much  as  for  their 
results. 
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The  review  of  PC  speed-up  boards 
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comparable  board: 

STD  (Seattle  Telecom  &  Data  Inc.) 

2637  151st  Pi.  NE 
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Anew  sanity 
seems  to  be 
infecting  a  growing 
number  of  computer- 
related  companies. 

Could  it  be  that  our 
industry  is  becoming 
customer  drive  rt? 

Here  are  some  exam¬ 
ples  of  this  new  and 
encouraging  trend: 

Copy  protection, 
long  a  hotly  debated  issue  between 
customers  and  software  makers,  is  fi¬ 
nally  being  abandoned  as  more  and 
more  customers  spurn  protected  soft¬ 
ware.  For  many  years  it's  been  diffi¬ 
cult  to  find  major  software  packages 
that  weren’t  bound  up  in  all  sorts  of 
cryptic  ways.  Now,  with  only  a  few 
exceptions,  every  important  program 
is  available  in  an  unprotected  form. 
This  has  been  a  rapid  process.  Why 
didn't  it  happen  sooner? 

The  industry  seems  to  be  con¬ 
cerned  about  creating  a  completely 
machine-independent  standard  for 
the  new  CD-ROM  technology.  Every¬ 
one  seems  hesitant  to  produce  any 
real  products  until  there  is  a  standard 
that  can  be  applied  across  all  prod¬ 
ucts.  We  applaud  this.  Why  didn't 
this  kind  of  cooperative  effort  go  into 
floppy-disk  formats? 

Other  standards  seem  to  be  emerg¬ 
ing  as  well.  For  example,  the  Post¬ 
Script  page-description  language,  de¬ 
veloped  by  Adobe  Systems  for 
Apple’s  LaserWriter,  is  now  support¬ 
ed  by  a  new  series  of  plug-compati¬ 
ble  printers  from  Texas  Instruments. 
This  is  a  credit  to  both  Apple  and  TI 
(and  Adobe,  of  course).  Other  makers 
of  page-output  products  have  indicat¬ 
ed  their  intentions  to  support 
PostScript, 

Living  Videotext  recently  made 
public  the  file-storage  format  for  its 
ThinkTank  series  of  idea-processor 
programs.  The  response  from  pro¬ 
grammers  was  immediate  and  en¬ 
thusiastic.  We  predict  we  ll  soon  see 
other  products  that  are  compatible 


with  ThinkTank. 

Even  venerable  Ap¬ 
ple  Computer  is  finally 
going  to  produce  a 
Macintosh  with  slots. 
What  is  this  world 
coming  to? 

We  think  the  indus¬ 
try  is  finally  becoming 
respectable.  Now  that 
^  there  are  enough  cus- 
— I  tomers  so  that  a  small 
percentage  of  the  market  share  can 
mean  a  large  change  in  dollar  vol¬ 
ume,  the  customer's  feelings  about  a 
product  are  suddenly  important.  We 
encourage  you  to  let  your  feelings  be 
known.  Now  that  companies  are  fi¬ 
nally  starting  to  respond  in  a  big  way, 
your  voice  can  make  a  difference. 

This  month's  hint  for  writers  con¬ 
cerns  communication — from  us  to 
you  and  back.  First,  we  want  to  re¬ 
mind  you  of  how  important  it  is  to 
include  a  phone  number  with  every 
letter,  manuscript,  outline,  or  pro¬ 
posal  that  you  send  us.  Often  we  save 
several  weeks  of  correspondence  by 
calling  you  directly  and  discussing 
your  idea  over  the  phone. 

We  have  a  set  of  form  letters  that 
we  send  out  at  various  times  during 
the  article  editing  process.  If  you 
send  us  a  manuscript,  you  will  defi¬ 
nitely  get  some  sort  of  a  reply  within 
a  few  weeks.  If  your  article  is  not  re¬ 
jected  right  away,  it  will  be  put  into  a 
file  for  consideration.  It  may  spend  as 
much  as  a  month  in  there  before  it 
gets  assigned  or  rejected.  If  you  have 
sent  a  manuscript  into  DDJ  and  you 
haven't  heard  from  us  in  a  while,  feel 
free  to  call  me.  I'll  be  happy  to  look  it 
up  and  let  you  know  what's 
happening. 


Nick  Turner 
editor 


ARCHIVES 

The  Safe  Bet 

Nineteen  eighty-one  will  bring  the  ad¬ 
vent  of  16-bit  microcomputer  systems. 
ITlhere  will  be  a  shift  toward  very  large 
companies  in  the  microcomputer  mar¬ 
ket _  ‘—Bill  Gates,  InfoWorld.  January 

19,  1981. 

"Microsoft  played  a  significant  role  as  a 
consultant  to  IBM  in  the  development  of  its 
hardware.  .  .  ."—Paul  Freiberger, 

InfoWorld,  October  S,  1 981. 

'People  have  teen  dazzled  by  the  stuff 
that's  gone  on  at  Xerox  PARC  for  years. 
With  good  bit  mapped  graphics  and  16-bit 
machines  on  real  production  equipment, 
we  can  perform  some  of  those  same  pieces 
of  magic.  ”— Bill  Gates,  InfoWorld,  January 
11,  1982. 

Insiders  suggest  that  Apple  had  to  go  to 
Microsoft  to  get  some  of  the  ILisa  software) 
done.  Why  Microsoft?  Apparently  Micro¬ 
soft  has  a  couple  of  ex-Xerox  PARC  Small¬ 
talk  programmers.’'  John  Dvorak , 
InfoWorld,  January  31,  1983. 

"There  should  also  be  some  really  usable 
portable  computers  using  liquid-crystal 
displays  of  at  least  8  lines  by  40  charac¬ 
ters.”—  Bill  Gates,  InfoWorld,  Jammy  10, 
1983. 

"Microsoft . . .  developed  all  the  software 
for  the  Model  too.” — Scoff  Mace, 
InfoWorld,  April  11,  1983. 

"Most  predictions  tare]  inside  informa¬ 
tion  in  the  guise  of  prognostication.  "— John 
Dvorak,  InfoWorld,  January  10,  1983. 

Ten  Years  Ago  in  DDJ 

"Heilman  and  Oiffie  hold  that  the  [56-bit 
DE5!  key  is  not  all  that  secure,  that  such  a 
key  could  be  broken  in  a  day  by  anyone 
witli  enough  money  to  build  the  trial-and- 
error  machinery  to  search  the  100  million 
billion  keys  . .  .  not  too  much  for  a  govern¬ 
ment  agency,  say,  the  NSA  or  CIA.'  -  DDJ, 
September  1976. 

Motorola  is  reliably  rumored  to  be 
working  on  their  6809,  which  supposedly 
will  give  Zilog's  Z80  some  stiff  competition. 
More  details  when  we  have  'em."— DDJ, 
September  1976. 

"For  non-Apple  systems:  source  and  ab¬ 
ject  code  supplied  [for  a  6502  disassembler] 
occupies  pages  8  and  9.  All  code  is  on  page 
8,  tables  on  page  9.  These  tables  may  be 
relocated  at  will. ..code  may  also  be  relo¬ 
cated.  Be  careful  if  you  use  pages  0  or  1, 
Page  I  is  the  subroutine  return  stack. . 
Sieve  Wozniak,  DDJ,  September,  1976. 

"I  wish  to  express  a  certain  disgruntle- 
ment  with  some  of  the  gargoyles  that  have 
been  erected  on  the  cathedral  of  LISP." 
— John  McCarthy,  DDJ,  September,  1976. 

"I  enclose  my  . . .  string  immediate-out¬ 
put  subroutine  for  6502-basecl  systems. 
—Chris  Espinosa,  DDJ,  September,  1976. 
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The  Right  to 
Optimize 

Dear  DDJ, 

Richard  Campbell's  March 
column  on  NS32016  square 
root  calculations  prompted 
me  to  implement  his  algo¬ 
rithm  on  my  68000  system 
and  do  some  comparative 
measurements.  My  system 
is  a  68000  board  hooked  to 
an  Apple  II  computer  run¬ 
ning  at  an  effective  clock 
rate  of  approximately  8.1 
MHz.  (The  nominal  clock 
rate  of  12.5  MHz  is  slowed 
down  by  one  additional 
wait  cycle  on  every  bus 
transfer  and  a  software  D- 
RAM  refresh  scheme.) 

Unfortunately,  I  do  not 
have  a  C  compiler  for  my 
board,  so  I  had  to  resort  to 
rewriting  Mr.  Campbell's 
program  for  what  I  have 
available,  which  is  a  UCSD 
p-code  System  adapted 
from  Apple  Pascal  to  the 
68000.  One  of  the  limita¬ 
tions  of  this  system  is  that  it 
handles  only  16-bit  signed 
integers,  so  I  had  to  use 
some  routines  of  my  own 
to  support  32-bit  integer 
arithmetic  in  order  to  stay 
compatible  with  Mr. 
Campbell's  benchmarks, 
which  used  a  loop  from  0 
to  60,000  to  time  the  square 
root  routines. 

As  the  Pascal  compiler 
produces  p-code  object  pro¬ 
grams,  I  wrote  the  square 
root  routine  in  68000  assem¬ 
bly  language  and  linked  it 
as  an  external  procedure  to 
the  surrounding  Pascal  pro¬ 
gram  [Listing  One,  page  56]. 
For  performance  measure¬ 


ments,  I  used  a  system  time 
procedure  with  a  resolu¬ 
tion  of  l/60th  of  a  second 
and,  like  Mr.  Campbell  in 
his  article,  a  loop  perform¬ 
ing  60,001  calls  to  the 
square  root  routine  with  ar¬ 
guments  ranging  from  0 
through  60,000.  To  derive 
the  time  it  takes  for  the 
square  root  routine  to  exe¬ 
cute,  I  measured  the  execu¬ 
tion  time  of  the  Pascal  pro¬ 
gram  and  then  subtracted 
from  it  the  execution  time 
of  the  same  program  linked 
to  a  routine  that  skips  the 
calculation  of  the  square 
root;  the  latter  time  there¬ 
fore  represents  the  over¬ 
head  for  the  loop  and  the 
procedure  call  mechanism, 
which  has  nothing  to  do 
with  the  square  root  algo¬ 
rithm  itself. 

Using  the  routine  that 
mimics  Mr.  Campbell's 
compiler-generated  code 
[Listing  Two,  page  56],  the 


program  executes  in  16.73 
(+/—  0.02)  seconds  on  my 
system  (without  printing 
or  counting  shifts  and  divi¬ 
sions)  and  the  empty  shell 
program  needs  12.08  sec¬ 
onds.  Calculating  60,001 
square  roots,  therefore, 
takes  4.65  seconds,  for  an 
average  of  77.5  microsec¬ 
onds  per  square  root.  To 
answer  Mr.  Campbell's 
question  about  whether 
hand  optimizing  the  as¬ 
sembly  code  is  worth  it,  I 
did  just  that.  Using  the 
same  measuring  proce¬ 
dure  as  above,  the  opti¬ 
mized  code  [Listing  Three, 
page  56]  needed  3.90  sec¬ 
onds  to  perform  the  60,001 
square  root  calculations 
(without  overhead),  for  an 
average  of  65  microsec¬ 
onds  per  square  root — a 
speedup  of  about  16  per¬ 
cent.  In  my  book,  that  is 
well  worth  the  little  trou¬ 
ble  it  takes  to  optimize  the 


routine,  especially  if  it  is 
used  often. 

To  find  out  by  how  much 
Mr.  Campbell’s  algorithm  is 
faster  than  the  algorithm 
mentioned  by  Jim  Cathey,  I 
also  performed  the  mea¬ 
surements  for  a  program 
using  that  algorithm  to  cal¬ 
culate  the  square  root  [List¬ 
ing  Four,  page  58],  Without 
overhead,  Mr.  Cathey’s  al¬ 
gorithm  took  8.66  seconds 
to  perform  the  60,001 
square  roots,  or  an  average 
of  144  microseconds  per 
square  root;  it  is  therefore 
almost  twice  as  slow  as  the 
unoptimized  code  for  Mr. 
Campbell’s  algorithm. 

To  compare  my  results 
for  the  MC68000  with  the 
published  ones  for  a  6-MHz 
NS32016,  they  should  be 
multiplied  by  a  factor  of 
1.60  (9.6  MHz/6  MHz)  to  get 
timings  equivalent  to  a  6- 
MHz  68000.  If  this  is  done, 
the  time  to  calculate  a 
square  root  using  the  unop¬ 
timized  code  becomes  124 
microseconds,  the  opti¬ 
mized  version  needs  104 
microseconds,  and  the 
square  root  calculation  us¬ 
ing  bit  shifting  needs  231 
microseconds.  This  clearly 
disproves  Mr.  Campbell's 
statements  about  the  supe¬ 
riority  of  the  NS32016. 

Regarding  Mr.  Camp¬ 
bell’s  comments  about  the 
bit-shifting  algorithm  "hit¬ 
ting  the  NS32016  below  the 
belt,”  I  can  only  say  that 
Mr.  Cathey's  algorithm 
was  not  specifically  de¬ 
signed  to  do  that  but  is  rath¬ 
er  a  general-purpose  algo¬ 
rithm  that  merely  points 
out  certain  weaknesses  in 
the  NS32016's  design.  In  my 
opinion,  the  MC680XX  fam¬ 
ily  is  clearly  superior  to  the 
microprocessors  of  the 
NS320XX  family;  everything 
you  can  do  with  a  NS32016, 
you  can  also  do  on  a 
68000 — often  more  easily, 
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usually  faster,  and  then 
some,  as  illustrated  above. 

Other  than  that,  I  agree 
with  Mr.  Campbell’s  con¬ 
clusion  that  many  bit-level 
tricks  of  the  8-bit  era  are 
outdated  and  should  he  re¬ 
placed  by  newer  and  faster 
algorithms  more  appropri¬ 
ate  for  16/32-bit  proces¬ 
sors.  1  hope  to  find  exactly 
such  articles  in  future  is¬ 
sues  of  DDJ. 

Thomas  Wieland 
8676  Anthony,  ^5 
Pierrefonds,  PQ  H84  2B6 
Canada 


8080  Simulator 

Dear  DDJ, 

Hats  off  to  Jim  Cathey  for 
such  a  nice  and  useful 
piece  of  MC68000  code.  [See 
"COM:  An  8080  Simulator 
for  the  MC68000,”  January 
1986.]  After  I  had  typed  in 
the  code  (only  one  typo 
and  an  easy  to  find  one  at 
that),  I  couldn't  resist  add¬ 
ing  Z80  relative  jumps  and 
djnz  [Listing  Five,  page  58]. 

In  an  attempt  to  improve 
on  the  simulator's  speed, 
and  remembering  an  old 
trick  from  FORTH  compiler 
writing  days,  I  expanded 
mloop,  which  I  duly 
dubbed  NEXT,  at  the  end  of 


every  opcode  simulation, 
thereby  gaining  eight  t-cy- 
cles  per  simulated  8080  in¬ 
struction  as  well  as  freeing 
a6  for  other  purposes  (I 
promptly  used  it  to  point  to 
pseudo-HL). 

If  your  system  is  config¬ 
ured  with  CP/M-68K  above 
the  TPA  in  such  a  way  that 
the  simulator  runs  below 
$8000,  you  can  even  go  a 
step  further  by  having  a 
jump  table  ( optabl )  in  the 
shape  of  dc.ws  and  a  NEXT 
that  looks  like  that  shown 
in  Table  1,  left. 

Together  with  various 
minor  alterations  too  volu¬ 
minous  to  present  here, 
this  last  modification  sped 
up  the  simulator  to  such  an 
extent  that  it  now  runs 
slightly  faster  than  SoftDe- 
sign's  Z80  emulator,  alas 
without  providing  full  Z80 
support.  As  many  CP/M-80 
programs  don't  use  the  ex¬ 
tra  Z80  instructions  any¬ 
way,  this  restriction  is  sel¬ 
dom  felt. 

In  order  to  spare  other 
CP/M-68K  users  a  set  of  blis¬ 
tered  fingers,  I  will  gladly 
copy  the  source  for  anyone 
who  provides  a  formatted 
8-inch  or  5V4-inch  floppy 
disk  (please  give  fcb  and 
skew  details  if  not  8-inch 
SSSD). 

Edmund  Ramm 

Postfach  38 

D-2358  Kaltenkirchen 

West  Germany 

Corrections 

Dear  DDJ, 

The  C  implementation  of 
Bresenham's  line-drawing 
algorithm  that  appeared  in 
the  May  1986  issue  contains 
several  errors.  [See  "Simple 
Plots  with  the  Enhanced 
Graphics  Adapter”  by  Na- 
bajyoti  Barkakati.]  These 
errors  cause  the  routine 
v_draw  to  fail  in  the  first 
and  third  quadrants.  I  have 
enclosed  a  corrected  ver¬ 
sion,  C—draw  [Listing  Six, 
page  62], 

In  v—draw,  a  statement 


moveq 

#0,d0 

*  clr  hi  word 

move.b 

(pseudopc)-(- ,d0 

*  fetch  next  opcode 

add.w 

dO.dO 

*  dO  <~  offset  into  word  table 

move.w 

0(opptr,d0.w),a0 

’  dO  max  is  $ff  <<  1  ($1fe) 

jmp 

(aO) 

*  exec  opcode 

Table  1:  Improved  NEXT  routine  for  8080  simulator 
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on  line  75  is  missing  alto¬ 
gether.  This  causes  the  rou¬ 
tine  to  break  in  a  not  so  sub¬ 
tle  manner;  I  assume  the 
omission  is  a  misprint. 
However,  initialization  of 
the  decision  variable  d 
(lines  34  and  80)  is  incom¬ 
plete,  resulting  in  some¬ 
what  more  obscure  prob¬ 
lems.  The  value  to  which  d 
must  be  initialized  depends 
upon  whether  the  line 
slope  is  positive  or  negative. 
If  the  initialization  is  han¬ 
dled  incorrectly,  symmetry 
is  destroyed  and  endpoint 
overrun  errors  are  intro¬ 
duced.  These  problems 
may  not  show  up  unless  the 
routine  is  tested  at  all  the 
boundary  conditions. 

The  line-drawing  rou¬ 
tine  runs  rather  slowly 
when  the  BIOS  point-plot- 
ting  routine  is  used,  even 
on  an  IBM  PC/AT.  Possibly 
the  use  of  Bruce  Smith’s  as¬ 
sembly-language  point¬ 
plotting  algorithm,  pub¬ 
lished  in  the  January  1985 
16-Bit  Software  Toolbox, 
would  speed  things  up. 

Joseph  N.  Mente 

Titanic  CodeWorks 

916  Olive  Rd. 

Homewood,  IL  60430 

Listing  One  of  Everett  Car¬ 
ter's  article,  "Forth  Goes  to 
Sea,”  (July  1986)  was  trun¬ 
cated.  The  rest  of  the  listing 
begins  on  page  50. 


DDJ 

(Listings  begin  nn  page  56.) 
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Directory  Traversal,  Trailing  "Zs,  and  Horrifying  Experiences 


Directory  Traversal 

his  month  I’m  going  to  look  at 
another  sort  of  tree — a  directo¬ 
ry  tree.  The  program  presented  here 
does  several  things,  depending  on 
how  it's  invoked.  If  the  program  is 
named  whereis.exe,  then  the  com¬ 
mand  whereis  <fname>  will  search 
the  entire  directory  tree  for  a  file 
called  fname,  printing  the  full  path 
name  of  the  file  when  it’s  found. 
Wildcard  characters  are  recognized 
in  the  name  (as  in  whereis  *.c ).  Be 
careful  if  you're  running  this  pro¬ 
gram  under  the  shell.  You’ll  have  to 
escape  the  wildcards  to  prevent  the 
shell  from  expanding  them  ( whereis 
"*.c" or  whereis \*.c  ). 

By  renaming  the  same  program  to 
dtree.exe,  several  functions  are  add¬ 
ed.  The  basic  command  syntax  is: 

dtree  [root]  [— f<name>]  [— s]  [— d] 
[— e  cmd  arg  .  . .] 

The  root  indicates  where  to  begin  the 
directory  traversal.  If  it's  not  speci¬ 
fied,  then  /  is  used.  Thus,  dtree  (with 
no  arguments)  descends  recursively 
through  the  entire  directory  tree, 
starting  from  the  root  directory, 
printing  a  list  of  all  the  directories  on 
your  disk.  Dtree  <dname>  prints  a 
list  of  all  directories  at  or  below 
<dname>  in  the  directory  tree.  So 
dtree  /  works  in  the  same  way  as 


by  Allen  Holub 


dtree  without  arguments  does.  Dtree 
/src  prints  a  list  of  all  subdirectories 
below  /src  (including  the  subdirec¬ 
tories  of  the  subdirectories).  Table 
1  ,  page  16,  shows  a  sample  output 
from  my  own  disk. 

The  —  d  command-line  switch 
causes  a  graphic  representation  of  the 
directory  tree  to  be  printed  rather 
than  a  simple  list  of  the  names.  If  —  s  is 
specified  too,  short  names  are  used  in¬ 


stead  of  the  full  path  name.  An  exam¬ 
ple  is  given  in  Table  2,  page  16.  When 
the  program’s  output  is  redirected  to  a 
file,  it's  printed  as  shown  (with  plus 
signs  and  dashes).  If  output  goes  to 
stdout,  the  IBM  box-drawing  charac¬ 
ters  are  used  so  that  you  have  a  pretti¬ 
er  picture  on  the  screen. 

The  — e  switch  is  used  to  execute 
commands.  All  command-line  argu¬ 
ments  that  follow  —  e  are  taken  as  a 
command  that  will  be  executed  from 
each  directory  as  it's  visited.  A  space 
must  follow  the  e.  For  example: 

dtree  /  — e  Is  —1 

prints  a  list  of  every  file  in  every  di¬ 
rectory  on  the  disk  using  the  Is  long 
format  (that  is,  because  the  —l  fol¬ 
lows  the  — e  on  the  command  line, 
it's  passed  to  Is  rather  than  being  in¬ 
terpreted  by  dtree).  The  directory 
name  is  printed  too  (just  before  the 
command  is  executed).  If  you  need  to 
execute  either  a  batch  file  or  a  com¬ 
mand  that's  part  of  the  shell,  you 
have  to  invoke  the  shell  explicitly. 
Examples  are: 

dtree  /  —  e  command  /c  dir 
dtree  /  —  e  command  /c  batchfile 

arg  arg  arg 

dtree  /  —  e  sh  batchfile  arg  arg  arg 
dtree  .  —  e  sh  cp  "*.c"  a: 

The  first  example  does  the  same  as 
dtree  —e  Is  does  except  that  the  dir 
command  (that’s  internal  to  COM- 
MAND.COM)  is  used.  The  second  exam¬ 
ple  executes  an  MS-DOS  batch  file;  the 
arguments  following  the  file  name 
are  passed  to  the  batch  file.  The  third 


example  does  the  same,  but  my  own 
shell  (as  distributed  by  DDJ)  is  used 
rather  than  COMMAND.COM.  The  last 
example  backs  up  all  .c  files  in  an  en¬ 
tire  system — that  is,  it  copies  all  .c 
files  in  the  current  directory  and  any 
subdirectories  to  the  a:  drive.  The  ex¬ 
plicit  invocation  of  the  shell  is  neces¬ 
sary  because  wildcard  expansion 
must  be  done  in  each  directory  as  it's 
visited,  and  this  expansion  is  done  by 
the  shell,  not  by  cp.  Had  you  said: 

dtree  .  — e  cp  *.c  a: 

the  *.c  would  have  been  expanded 
by  the  shell  to  all  files  in  the  current 
directory  that  end  in  .c.  Dtree  would 
copy  these  and  then  descend  to  a  sub¬ 
directory  and  try  to  find  files  having 
the  same  names  as  the  ones  in  the 
parent  (because  the  *.c  is  expanded 
by  the  shell  before  dtree  ever  sees  the 
command  line). 

The  switch  —f<name>  (no  space 
between  f  and  <name>  )  causes  the 
program  to  search  for  the  file  called 
<name>.  So  dtree  /  —f<name> 
does  the  same  thing  as  whereis 
<name>  does.  Using  dtree  rather 
than  whereis  has  two  advantages. 
First,  dtree  can  start  the  search  at  any 
directory,  but  whereis  always  starts 
at  the  root.  So: 

dtree  /src  —  ffoo.c 

finds  foo.c  only  if  it  exists  at  or  below 
/src  in  the  directory  tree.  The  second 
advantage  comes  from  using  — / and 
— e  together  on  a  single  command 
line.  Here,  the  command  is  executed 
only  if  the  file  is  found.  For  example, 
if  you’re  running  under  sh  (rather 
than  COMMAND.COM)  using  the  rm 
program  provided  with  the  /util 
package  to  remove  files: 

dtree  /  —  ffoo  —  e  rm  foo 

Finds  all  occurrences  of  the  file  foo 
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on  the  disk  and  deletes  them,  and: 

dtree  /src/trees  “  —  f  *.bak”  —  e 

sh  —  c  rm  *.bak' 

deletes  all  .bak  files  in  the  /src/trees 
directory  (and  any  subdirectories  of 
/src/trees  ).  The  —/argument  has  to 
be  quoted  to  prevent  the  shell  from 
expanding  it  (dtree  expands  the  wild¬ 
cards  itself  and  —  f  can  take  only  one 


/  src 

/src/getargs 

/src/grep 

/src/nr 

/src/nr/hyphen 

/src/red 

/src/shell 

/src/shell/util 

/src/shell/util2 

/src/sm 

/src/small-c 

/src/sml— tool 

/src/tools 

/src/tools/doc 

/src/tools/lattice 

/src/tools/old 

/src/tools/trees 

/src/tools/trees/old 

/src/util 


Table  1:  Output  from  dtree  /src 


src 

+ — getargs 
+ — grep 

4. — nr 

I  + — hyphen 

1 

l 

+ — red 
+ — shell 
I  + — util 

I  + — uti!2 

I 

1 

+ — sm 
+ — small-c 
+ — sml-tool 
+ — tools 
I  + — doc 

I  +  — lattice 

I  + — old 

I  + — trees 

I  + — old 


+ — util 


Table  2:  Output  from  dtree  /  src 
—  d  —  s>file 


argument).  Similarly,  rm  doesn’t  ex¬ 
pand  wildcards  so  you  must  invoke  a 
shell  to  do  it.  The  *.bak  has  to  be 
quoted  so  that  the  subshell  will  do  the 
expansion  instead  of  the  current  shell. 

Because  the  delete  and  copy  func¬ 
tions  are  built  into  COMMAND.COM, 
you  can  say: 

dtree  /src  — f  *.bak  —  e  command  /c 

copy  *.c  a: 

to  do  the  equivalent  operation  from 
outside  the  shell.  You  don’t  have  to 
quote  any  arguments  because  COM- 
MAND.COM  won’t  expand  them;  copy, 
on  the  other  hand,  will. 

Dtree. c 

The  source  for  dtreet  )  is  in  Listing 
One  (page  62).  The  modus  operandi  of 
the  program  is  determined  in  main(  ) 
on  lines  380  —  394.  Main(  )  examines 
argv[0]  to  see  by  what  name  it  was 
invoked.  If  whereis  is  used,  the  if 
clause  is  executed;  if  anything  other 
than  whereis  is  used,  then  the  else 
clause  is  executed.  Note  that  argv/O ] 
isn’t  supported  by  DOS,  Version  2.x,  so 
this  automatic  configuration  will 
work  only  if  you’re  using  DOS  3.x  or  if 
you're  running  the  shell  (the 
reargvt )  function  will  give  you  ac¬ 
cess  to  argv/O] ). 

The  main(  )  routine  also  deter¬ 
mines  which  character  set  to  use  for 
tree  printing  (on  line  397).  It  does  this 
in  the  same  way  as  does  the  print  rou¬ 
tine  I  discussed  last  month.  The  same 
limitations  apply,  too  (that  is,  graph¬ 
ics  are  used  unless  standard  output  is 
redirected  to  a  file).  The  signaK  )  call 
on  line  405  is  necessary  because  the 
traversal  algorithm  actually  changes 
the  current  directory  as  it  traverses. 
The  signaK  )  call  sets  up  the  interrupt 
system  so  that  when  a  "C  is  encoun¬ 
tered,  the  current  directory  will  be 
set  back  to  whatever  directory  you 
started  from  when  the  program  boot¬ 
ed.  The  actual  resetting  is  done  in  on- 
intr(  )  on  lines  361  —  366. 

Dtree (  )  can't  use  getargs  because  it 
uses  a  position-dependent  command¬ 
line  switch  (— e).  So  the  program’s  ar¬ 
guments  are  processed  by  hand  in 
doargsi  )  on  lines  270  —  332.  It  works 
pretty  much  the  same  as  getargs(  ) 
does,  setting  global  variables  to  corre¬ 
spond  to  encountered  command-line 
switches  and  compressing  argv  to  re¬ 
move  all  command-line  switches. 


Note  that  all  argv  entries  following 
— e  on  the  command  line  aren't  ana¬ 
lyzed  (that’s  the  test  for  Args  on  line 
295;  Args  is  NULL  if  a  —  e  hasn’t  been 
found). 

The  basic  traversal  algorithm  is 
done  by  prnt(  )  (on  lines  174  —  232).  It 
uses  a  modified  version  of  the 
preorder  tree-printing  algorithm  that 
I  discussed  two  months  ago,  so  I 
won’t  cover  that  material  again. 
However,  instead  of  using  a  basic 
tree-traversal  algorithm: 

trav(  root ) 

{ 

print!  root ); 
trav  ( left ); 
trav  (  right ); 

> 

which  can  be  restated  for  multiway 
tree  traversal  as: 

trav(  root ) 

{ 

print!  root  ); 
for(  each  child  ) 
trav(  child  ); 

} 

dtree  uses: 

trav(  current  directory ) 

{ 

print!  current  directory's  name  ); 
get  list  of  all  subdirectories; 
for(  each  subdirectory ) 
trav(  subdirectory  ); 

} 

The  code  on  lines  188—192  just 
prints  vertical  bars  in  the  appropri¬ 
ate  places,  provided  you're  printing  a 
picture  of  the  tree  (that  is,  —  d  is  speci¬ 
fied  on  the  command  line,  causing 
Draw  to  be  true).  If  you’re  searching 
for  a  file,  the  if  statement  on  lines 
194  —  198  is  executed.  The  directory 
name  is  not  printed.  Rather,  if  the  file 
exists,  you  execute  the  command  tail. 
Eyecutet  )  won’t  do  anything  if  — e 
isn’t  found  on  the  command  line.  If 
you’re  not  looking  for  a  specific  file, 
the  else  clause  on  lines  199  —  203 
prints  the  current  directory  name 
and  then  executes  the  command  tail. 

Prntf  jgets  the  list  of  subdirectories 
using  the  same  dirt  )  subroutine 
that's  used  by  the  shell  (the  code  for 
all  these  routines  and  for  the  mydir.h 
file  that’s  #  included  on  line  4  are  in 
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the  March  1986  C  Chest.  Mk—dir(  ) 
creates  a  DIRECTORY  structure  on  line 
205.  This  structure  is  initialized  on 
lines  211  —  215  so  that  dir(  )  will  get  a 
sorted  list  of  subdirectories,  using  the 
full  path  name  of  each  directory  in 
the  list.  Dir(  )  itself  is  called  on  line 
219;  the  recursive  traversal  of  each 
subdirectory  is  done  by  the  while 
loop  on  lines  221—225;  and  memory 
used  by  the  the  DIRECTORY  structure 
is  freed  on  line  230  [with  the  del 
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Find(  )  (on  lines  137—170)  uses  the 
same  directory  routines  to  look  for  a 
file.  It  will  expand  any  wildcard 
characters  in  the  file  spec  and  print 
the  whole  list  of  matching  files.  The 
remainder  of  the  code  you’ve  al¬ 
ready  seen,  either  last  month  or  the 
month  before,  so  I  won't  cover  it 
again  here. 

Fixing  ~ Z-Terminated  Files 

Back  in  May,  Ray  Duncan  mentioned 
a  problem  with  'Z-terminated  files 
being  read  by  the  Microsoft  Macro 


Assembler,  Version  4.0  (16-Bit  Soft¬ 
ware  Toolbox,  p.109).  The  include 
function  ignores  the  end-of-file  mark 
( ~Z )  and  uses  the  file  size,  so  it  will 
kick  out  error  messages  if  you  create 
a  file  with  any  editor  that  terminates 
its  files  with  ~Zs  rather  than  just  mak¬ 
ing  the  files  the  correct  length. 
Mince,  Vedit,  and  WordStar  (in  docu¬ 
ment  mode)  are  three  of  these  edi¬ 
tors.  You  often  see  this  sort  of  pad¬ 
ding  in  programs  that  were 
originally  written  for  CP/M  or  MS-DOS, 
Version  1  (where  ~Z  is  the  only  way 
to  end  a  file).  Microsoft  has  been  try¬ 
ing  to  get  rid  of  the  'Z  end-of-file 
marker  since  it  introduced  Version  2 
of  MS-DOS,  and  I  guess  it's  finally  play¬ 
ing  hardball. 

This  ~Z  problem  is  responsible  for 
a  lot  of  weird  behavior  on  the  part  of 
the  shell,  too.  The  formatted  I/O  rou¬ 
tines  in  Version  3.0  of  the  Microsoft  C 
compiler  get  hopelessly  confused 
when  they  try  to  read  a  'Z- term  mat¬ 
ed  file.  So  if  you  try  to  execute  a 
Vedit-created  batch  file  from  the 
shell,  strange  things  start  happening 
(characters  mysteriously  appear  and 
disappear,  error  messages  such  as 
“stdout:  no  room  left  on  device”  are 
printed,  and  so  on). 

Unfortunately,  the  fix  that  Ray 
gave  in  his  column  (enter,  write,  and 
then  exit  from  EDUN)  doesn't  seem  to 
work  all  the  time  (or  so  say  friends 
who’ve  tried  it),  and  it  turns  out  to  be 
almost  impossible  to  fix  this  problem 
in  Microsoft-compiled  programs 
without  going  to  unformatted  binary 
input  (that  is,  open(  ),  read(  ),  and  so 
on).  So  I  wrote  a  utility  called  fix  to 
deal  with  it  (see  Listing  Two,  page  68). 

Fix  removes  all  trailing  ~Zs  from  a 
text  file  (actually  it  truncates  the  file 
at  the  first  ~Z  it  finds).  Usage  is: 

fix  file  [file  . . .  ] 

where  the  command  line  holds  a  list 
of  files  to  fix.  The  program  renames 
the  files  specified  on  the  input  line  to 
xxx.bak,  where  xxx  is  the  original 
root  part  of  the  file  name.  It  then 
overwrites  the  original  file,  remov¬ 
ing  the  trailing  “Zs. 

The  program  is  very  short  and 
pretty  much  self-explanatory.  Note 
that  the  ctlc(  )  and  reargvf  )  calls  on 
lines  54  and  55  are  useful  only  if 
you're  running  under  the  shell  and 
they’re  supplied  along  with  the  shell. 
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Don’t  include  these  calls  if  you're  us¬ 
ing  COMMAND.COM. 

A  Tale  of  Woe 

My  friend  Bill  Wong,  who  lives  across 
the  street,  has  gallantly  volunteered  to 
beta  test  the  shell  as  I  bring  up  the 
new  version.  He  was  having  prob¬ 
lems  with  it  the  other  day,  and  we 
thought  these  problems  might  be  DOS- 
related  (he’s  running  Version  3.0  rath¬ 
er  than  3.1),  so  we  decided  to  upgrade 
the  DOS  version  on  his  hard  disk.  Earli¬ 
er  versions  of  DOS  (pre-3.1)  made  it  im¬ 
possible  to  create  a  system  disk  except 
by  formatting  the  disk  with  the  /s  flag 
set  ( copy  won’t  copy  system  files). 
This,  of  course,  forced  you  to  back  up, 
format,  and  then  restore  your  entire 
hard  disk  to  install  a  new  version  of 
DOS.  Version  3.1  comes  with  a  utility 
called  sys  that  can  transfer  a  system  to 
a  hard  disk,  but  I  had  forgotten  that 
this  utility  existed. 

So,  I  tried  to  install  the  new  DOS  ver¬ 
sion  on  Bill's  disk  by  removing  the 
hidden  and  system  attributes  from 
IBMBIO.COM  and  IBMDOS.COM  and 
then  copying  them  over  to  the  hard 
disk  in  the  normal  way.  I’ve  a  pro¬ 
gram  (called  chmod)  that  can  change 
these  attributes  ( attrib  can  change 
only  the  read-only  attribute).  Files 
successfully  transferred,  I  pressed 
Ctl-Alt-Del,  and  to  my  horror,  the  sys¬ 
tem  wouldn’t  boot.  It  didn't  even 
print  an  error  message — it  just  hung. 
"Oh  God,”  I  said  to  myself,  "I’ve  de¬ 
stroyed  Bill’s  hard  disk.”  Fortunately, 
things  weren’t  quite  that  bad.  The 
system  booted  from  the  floppy  with 
no  trouble.  We  could  at  least  get  the 
thing  running  again  to  try  to  find  out 
what  the  problem  was. 

To  make  a  long  story  short,  we 
fooled  around  for  more  than  an 
hour,  trying  everything  we  could 
think  of  (including  running  the  sys 
program,  now  rediscovered  by  us). 
Nothing  worked.  No  amount  of  copy¬ 
ing  fixed  anything.  Changing  attri¬ 
butes  didn’t  help.  Sys  said  that  it  had 
transferred  the  system,  but  it  still 
wouldn’t  boot  from  the  hard  disk.  So, 
in  desperation  we  deleted  the  entire 
root  directory  (including  the  system 
files)  and  tried  to  run  sys  again.  Now 
it  started  giving  us  "No  room  for  sys¬ 
tem  on  destination  disk"  error  mes¬ 


sages.  The  disk  was  only  two-thirds 
full,  so  there  was  obviously  some 
other  problem. 

Finally  I  threw  in  the  towel  and  de¬ 
cided  to  call  Microsoft.  It  told  me  that 
it  does  not  support  end-users  of  DOS 
and  that  I’d  have  to  call  IBM.  IBM  told 
me  that  it  does  not  support  end-users 
of  DOS  and  that  I’d  have  to  call  the 
store  that  sold  me  the  computer. 
ComputerLand  told  me  that  it  had  no 
idea  what  the  problem  was,  though  it 
could  guess.  The  person  I  talked  to 
suggested  reading  the  DOS  Technical 
Reference.  So,  it  seems  there  is  no 
technical  support  available  for  MS- 
DOS — from  anyone. 

I  dug  out  the  Technical  Reference 
and  actually  did  find  something 
there.  It  was  even  in  the  index  (under 
system  reset).  When  MS-DOS  boots: 
"The  boot  record  then  checks  the 
root  directory  to  assure  that  the  first 
two  files  are  IBMBIO.COM  and  IBMDOS 
.COM.  These  two  files  must  be  the  first 
two  files,  and  they  must  be  in  that 
order  (IBMBIO.COM  first,  with  its  sec¬ 
tors  in  continuous  order).”  So,  my 
theory  is  that  when  you  open  a  file 
for  overwrite,  DOS  frees  up  the  associ¬ 
ated  FAT  entries  and  directory  space. 
That  is,  it  doesn't  just  overwrite  an 
existing  file  with  new  data;  it  throws 
away  the  existing  file  and  then  starts 
from  scratch,  putting  the  copy  wher¬ 
ever  it  feels  like.  So  the  two  boot  files 
ended  up  in  the  wrong  place.  Mean¬ 
while  all  our  thrashing  around  on 
the  disk  ended  up  putting  something 
into  the  sectors  that  IBMBIO.COM 
wanted  to  occupy.  This  explains  sys’ 
inappropriate  error  message.  There’s 
plenty  of  room  on  the  disk,  but 
there’s  probably  no  room  on  track  0. 1 
still  don’t  understand  why  sys  told  us 
that  the  system  had  been  transferred 
successfully  the  first  few  times  we 
tried  to  use  it.  I  suspect  this  has  some¬ 
thing  to  do  with  directory  entries  for 
IBMBIO.COM  and  IBMDOS.COM  already 
existing  but  pointing  at  the  wrong 
place  on  the  disk.  It  seems  to  me  that 
sys  should  check  for  things  such  as 
that.  It  obviously  doesn’t.  I  also  don't 
understand,  if  the  positions  of  IBM¬ 
BIO.COM  and  IBMDOS.COM  on  the  disk 
are  so  important,  why  you  can  delete 
them  at  all.  To  my  mind  they 
shouldn’t  even  be  in  the  directory 
system  because  you  can’t  treat  them 
like  you  can  any  other  file. 

I’m  sure  there's  a  lesson  to  be 


learned  from  all  this,  but  I’m  not  sure 
what  it  is.  Your  only  recourse  is  to 
back  up,  reformat  the  hard  disk,  and 
restore.  Looked  at  in  a  truly  Polyanna 
fashion,  at  least  disk  accesses  will 
speed  up  because  all  the  file  frag¬ 
mentation  will  be  eliminated. 

To  add  injury  to  insult,  bringing  up 
Version  3.1  didn’t  fix  the  problem 
with  the  shell  (which  turned  out  to  be 
the  ~Z  problem  that  I  described  earli¬ 
er).  Aren’t  computers  wonderful? 

Availability 

The  listings  from  this  month  are  all 
available  on  CompuServe  (type  go 
ddj).  The  chmod  program,  used  to 
change  file  attributes,  is  now  distrib¬ 
uted  by  DDJ  as  part  of  Version  1.1  of 
the  /util  package.  This  package  also 
includes  the  rm  and  cp  utilities  used 
in  the  examples.  If  you  have  an  earli¬ 
er  version,  you  can  get  an  upgrade 
from  DDJ  for  $6.  The  fix  program  is 
distributed  with  Version  2.0  of  the 
shell  (available  from  DDJ,  upgrades 
are  $6,  too)  and  is  also  available  on 
CompuServe.  The  directory-related 
routines  used  by  dtree.c  are  also  part 
of  the  shell.  They  were  originally 
published  in  this  column  in  March 
1986  (the  listing  begins  on  page  56  of 
that  issue).  Note  that  the  mydir.h  file 
on  the  shell  distribution  disk  is  called 
dir.h  in  that  listing. 

An  IBM  PC-compatible  disk  contain¬ 
ing  the  complete  sources  for  dtree.c 
and  fix.c  (including  the  directory  rou¬ 
tines)  is  available  for  $25  from  Soft¬ 
ware  Engineering  Consultants,  P.O. 
Box  5679,  Berkeley,  CA  94705. 

DDJ 

(Listings  begin  on  page  62.) 
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ARTICLES 


Curve  Fitting  with 

Cubic  Splines 


Before  com¬ 
puter-aided 
drafting 
workstations  com¬ 
pletely  replace  the 
draftsman's  pencil 
and  paper,  let’s  exam¬ 
ine  one  of  the  drafts¬ 
man’s  tools:  the 
spline.  Presented  with  data  in  the  form  of  points  on  an 
x— y  plane,  the  draftsman  uses  a  spline — a  flexible  strip  of 
metal  or  plastic — to  draw  a  smooth  curve  between  them. 

The  technique  is  very  simple.  After  plotting  the  data  on 
a  sheet  of  paper,  an  appropriately  sized  spline  is  held  in 
place  at  these  points  (referred  to  as  "knots”)  with  weights 
or  pins.  The  draftsman  then  traces  the  curve  formed  by 
the  spline.  For  any  given  set  of  knots,  the  curve  generated 
is  independent  of  the  spline  chosen  and  is  thus  exactly 
reproducible. 

From  mechanical  engineering,  elementary  beam  the¬ 
ory  shows  that  if  the  spline  is  not  too  severely  stressed,  it 
will  conform  to  a  curve  described  by  a  set  of  cubic  poly¬ 
nomial  equations,  one  between  each  pair  of  adjacent 
knots.  Adjacent  polynomials  meet  at  their  common  end¬ 
points  (the  knots),  and  their  slopes  and  rates  of  curvature 
at  these  points  are  equal.  Stated  in  mathematical  terms, 
these  polynomials  join  continuously  at  the  knots  with 
continuous  first  and  second  derivatives. 

Knowing  this,  you  can  develop  a  mathematical  model 
of  the  draftsman’s  splines  and  from  this  model  construct 
a  computer  program  for  interpolating  a  smooth  curve 
between  a  set  of  knots.  With  a  bit  of  care  in  choosing 
algorithms,  such  a  program  can  quickly  and  accurately 
generate  a  curve  for  a  thousand  or  more  data  points  on 
the  smallest  of  personal  computers.  It  can  even  be  adapt- 


byHeart  Software,  620  Ballantree  Rd.,  West  Vancouver,  BC 
V7S  1W3,  Canada 


ed  to  interpolate  a 
smooth  surface  be¬ 
tween  points  plotted 
in  three  dimensions. 

Developing  the 
model  involves  basic 
calculus  and  matrix 
theory.  If  you  are  un¬ 
familiar  with  such 
mathematics,  rest  assured  that  the  resultant  algorithms 
are  very  easy  to  program  and  using  a  cubic  spline  pro¬ 
gram  requires  no  understanding  of  the  underlying  math¬ 
ematical  theory.  Give  the  program  a  set  of  knots,  and  it 
will  dutifully  interpolate  a  smooth  curve  in  all  (well,  al¬ 
most)  cases. 

Why  then  discuss  the  mathematics  of  cubic  splines  at 
all?  There  are  two  answers.  One  is  that  seeing  how  the 
algorithms  are  developed  gives  you  the  confidence  to  use 
them.  The  other  is  that  there  may  be  cases  in  which  the 
algorithms  will  not  perform  exactly  as  desired.  Knowing 
their  theory  may  enable  you  to  create  a  modified  algo¬ 
rithm  to  fit  the  problem  at  hand. 

A  Simple  Explanation 

Some  of  the  math  involved  in  spline  calculations  may  be  a 
bit  daunting  if  you  haven’t  had  training  in  calculus  and 
matrix  mathematics.  For  those  who  want  to  get  the  gist  of 
it  without  getting  tangled  up  in  equations,  here's  a  short 
summary. 

Because  a  spline  is  really  nothing  more  than  the  graphs 
of  a  set  of  contiguous  (endpoint-adjacent)  cubic  equations, 
all  you  need  to  know  to  draw  it  are  the  parameters  of 
each  of  the  equations.  Naturally,  there  will  be  one  such 
equation  for  each  segment  of  the  spline. 

Because  you  know  that  the  endpoints  of  each  segment 
will  coincide  with  the  endpoints  of  the  adjacent  ones,  and 
you  know  that  the  slopes  of  both  curves  will  be  the  same 
at  the  joining  points,  it  is  possible  to  derive  the  equations 


by  Ian  E.  Ashdown 


The  program  can  generate  a  curve 
for  a  thousand  or  more  data 
points. 
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Furthermore,  let’s  define  y’[i]  and  y”[i]  as  the  first  and 
second  derivatives  of  y(x)  at  x  =  x(ij.  Knowing  that  the  se;t 
of  functions  tli](x)  must  join  at  their  endpoints  (the  knots 
of  the  spline)  and  also  that  their  first  and  second  deriva¬ 
tives  are  continuous  at  these  points,  you  have  the  follow¬ 
ing  continuity  conditions: 


of  the  segment  curves  because,  for  any  set  of  two  points 
and  two  slopes,  there  is  one  and  only  one  cubic  curve 
segment  that  passes  through  the  two  points  with  the  giv¬ 
en  slopes.  Because  each  segment  of  the  spline  shares  the 
same  slope  at  its  endpoints  as  its  neighbors,  you  know 
that  its  first  derivative  (slope)  will  be  the  same  at  that 
point.  Because  the  curves  are  the  graphs  of  cubic  polyno¬ 
mials,  you  know  their  second  derivatives  (change  in 
slope)  will  be  straight  lines.  Because  (from  the  definition 
of  the  spline  curve)  the  slope  changes  smoothly  over  the 
length  of  the  curve,  you  know  that  the  graph  of  the  sec¬ 
ond  derivatives  of  the  spline  equations  will  consist  of  a 
series  of  straight  lines  joined  together  at  their  endpoints. 


Because  each  function  Hi](x)  is  a  cubic  polynomial,  it 
follows  that  its  second  derivative  is  a  linear  function  (a 
straight  line)  between  its  endpoints.  If  you  define: 


A  Rigorous  Explanation 

Beginning  in  this  section,  the  math  will  gel  quite  involved. 
If  you're  not  into  heavy  math,  you  might  want  to  skip 
down  to  the  sections  on  the  actual  algorithms  or  you  might 
want  to  skim  through  the  math  sections.  It’s  not  necessary 
to  have  a  full  understanding  of  the  math  in  order  to  make 
the  spline  program  work  properly,  but  it  helps. 

Starting  with  a  set  of  data  points  (the  knots)  stated  as 
ordered  horizontal  coordinates  x[i]  (i  =  1, . . .  ,n)  and  cor¬ 
responding  vertical  coordinates  y[i],  define  the  curve-to- 
be  as  the  composite  function: 


then  linear  interpolation  gives  you: 


Integrating  this  equation  twice  and  selecting  the  con¬ 
stants  of  integration  such  that  the  continuity  conditions 
are  satisfied,  you  can  derive  the  interpolation  equation 
shown  in  Table  1,  page  26. 

Remember  this  equation — you'll  use  it  later  to  interpo¬ 
late  the  curve  defined  by  y(x)  between  the  given  knots. 
But  first  you  need  to  calculate  the  unknown  coefficients 
y”[i]  for  all  i  between  1  and  n. 

Differentiating  and  evaluating  the  interpolation  liqua¬ 
tion  for  x(i] yields: 


where  each  function  flil(x)  is  a  cubic  polynomial  of  the 
form: 


where  a,  b,  c,  and  d  are  constants.  In  other  words,  y(x)  is 
really  a  set  of  functions,  each  of  which  is  defined  over  an 
interval  between  two  adjacent  knots  at  (x[ i  1,  y[il>  and 
(xli  +  l],  yli  +  ll). 


, ...  v[i  +  t|  — ylil  hli] 

fli](x[t])=  • _ : _ - _  <2  y  hi  +  y  [i  +  l)) 
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f[i](x)  =  y[i]  *  (*[1+1]  —  x)  +  y[i  + 1]  *  (x  —  x[i]) 


—  *  l  y”[i]  *  /  Wj+1]~x)  - 

e  y  y  h[i] 

/  xp+1]-x  \\  +  /  (x-x[iB 

^  m  f  f  ^  hp] 

M)) 

for  i  =  1  , . . .  ,n 


Table  1:  Interpolation  equation 


and 

f'[i— l](x[i])  =  yU]  ~  +M1--1]  «(y"[i-l]  +  2*y”[i]) 

h[i  —  1]  6 

Because  the  first  derivatives  of  the  functions  at  their 
endpoints  are  continuous,  these  two  equations  are  equiv¬ 
alent.  You  can  rearrange  the  terms  of  their  right-hand 
sides  to  get: 

h[i  —  l]  *  y”[i — 1]  +  2*(h[i-l]  +  h[i])*y”[i]  +  h[i]*y"[i+l] 

=  *  /y[i+H  -  y[i]  _y[i]  -  yli-U  \ 

\  m  h[i — i]  ; 

for  i  =  2, .  .  .  ,n  —  1. 

Expressed  in  matrix  form,  the  above  equations  show  an 


h[1] 

c[2] 

h[2] 

0 

0 

0 

y”[i] 

= 

d[2] 

0 

h[2] 

c[3] 

h[3] 

0 

0 

y”[2] 

d[3] 

0 

0 

h[3] 

c[4] 

h[4] 

0 

y”[3] 

d[4] 

0 

0 

0 

h[4] 

c[5] 

h[5] 

y"[4] 

d[5] 

— 

y”[5] 

y  ”[6] 

where 

c[i]  =  2  *  (h[i — 1]  +  h[i]) 


d[i]  =  6  * 


( 


y[i+1]-y[i]  _  y[i]  —  y[i— 1] 


hp] 


hp— 1] 


) 


Table  2:  f'[i](  X  [i])  and  f'[i— 1](  X  [i]j  expressed  in  matrix  form  for  n  =  6 


c[2] 

h[2] 

0 

0 

0 

y"[2] 

= 

d[2] 

h[2] 

c[3] 

h[3] 

0 

0 

y’[3] 

d[3] 

0 

h[3] 

C[4] 

0 

0 

y”[4] 

d[4] 

0 

0 

h[n— 3]  c[n— 2] 

h[n— 2] 

y”[n— 2] 

d[n— 2] 

0 

0 

0  h[n — 2] 

c[n — 1  ] _ 

_y”[n  1  ]_ 

_d[n  —  1  ]_ 

where 


c[2]  =  (2  +  j)  *  h[1]  +  2  *  h[2] 

c[i]  =  2  * (h[i  — 1]  +  h[i])  fori  =  3 . n-2 

c[n  —  1  ]  =  2*h[n-2]  +  (2  +  K)  *  h[n— 1] 

d[i]  =  6 *  /y[i+1]-y[i]  _yw-y[i-i]\  fori  =  2 . n_! 

^  h[i]  h[i-1]  J 


Table  3:  Matrix  form  of  nonperiodic  spline  function 
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interesting  diagonal  symmetry  that  you  can  take  good 
advantage  of  later.  Using  n  =  6  as  an  example,  they  look 
like  those  shown  in  Table  2,  page  26. 

A  Variety  of  End  Conditions 

So  far,  you  have  n  unknowns  y”[i]  but  only  n  — 2  condi¬ 
tions  as  expressed  by  the  above  equations.  Two  more  con¬ 
ditions  are  required  to  obtain  a  unique  solution  for  your 
curve  y(x).  Several  variations  are  possible;  I'll  look  at  two 
of  the  more  useful  ones  here. 

The  first  is  to  specify  that: 

y”[l]  =  j*y”[2] 

and 

y"[n]  =  k  *  y”[n  — 1] 

where  j  and  k  are  arbitrary  constants.  With  a  bit  of  matrix 
manipulation,  you  get  the  equations  shown  in  Table  3, 
page  26. 

If  the  values  of  j  and  k  are  zero,  you  have  y”[l]  =  y”[n] 
=  0.  This  is  equivalent  to  a  spline  whose  ends  are  not 
constrained  beyond  the  end  knots  and  is  known  as  the 
“natural”  cubic  spline.  A  nonzero  value  for  j  or  k  is  equiv¬ 
alent  to  bending  an  end  of  the  draftsman’s  spline  and  will 
affect  all  of  the  interior  cubic  polynomial  functions.  The 
effect  on  the  interior  polynomials,  however,  rapidly  de¬ 
creases  as  you  move  away  from  the  endpoints. 

For  some  sets  of  knots,  a  nonzero  value  of  j  or  k  will 
result  in  a  smoother  interpolating  curve  at  its  correspond¬ 
ing  end.  A  value  of  0.5  is  often  appropriate.  Be  fore¬ 
warned,  however,  that  for  some  negative  values  the 
curve  will  be  discontinuous.  As  it  approaches  these  val¬ 
ues,  the  end  of  the  curve  begins  to  oscillate,  the  peaks 
becoming  larger  and  larger  until  they  reach  infinity  at 
the  exact  values. 

The  above  set  of  linear  equations  can  be  solved  using 
Gaussian  elimination.  You  must  be  careful,  however.  In 


/*  Reduce  matrix  to  upper  triangular  form  */ 

for  i  =  2  to  i  =  n— 2 
begin 

c[i+1]  =  c[i+1]  —  h[i]  *  h[i]/c[i] 
d[i+1]  =  d[i+1]  —  d[i]  *  h[i]/c[i] 
end 

/*  Solve  using  back  substitution  */ 

y”[n — 1]  =  d[n — 1  ]/c[n — 1  ] 

fori  =  n— 2toi  =  2 
begin 

y"[i]  =  (d[i]-h[i]*y"[i+1])/c[i] 
end 

y”[1]  =  j  *  y”[2]  /*  End  conditions  7 

Y  ”[n]  =  k  *  y”[n— 1] 


Table  4:  Algorithm  1:  Nonperiodic  spline  coefficient 
determination 
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its  most  genera]  form,  this  method  can  require  prodigious 
amounts  of  memory  and  millions  of  floating-point  com¬ 
putations.  Given  1,000  unknowns,  Gaussian  elimination 
needs  storage  for  more  than  1  million  floating-point  num¬ 
bers  and  performs  some  334  million  multiplications  and 
divisions!  The  loss  of  accuracy  because  of  so  many  calcu¬ 
lations  can  render  the  results  meaningless. 

Fortunately,  the  coefficient  matrix  described  here  is 
very  sparse  and  symmetrical.  The  nonzero  elements  can 
be  stored  in  a  few  linear  arrays  and  the  remainder  ig¬ 
nored.  By  observing  how  Gaussian  elimination  solves  the 
equations,  you  can  modify  the  method  to  eliminate  oper¬ 
ations  involving  multiplication  by  and  addition  of  zero. 
The  result  is  Algorithm  1  (Table  4,  page  27),  which  has 
very  reasonable  memory  requirements  and  execution 
times — a  cubic  spline  problem  with  1,000  knots  can  be 
solved  quickly  on  most  personal  computers,  even  those 
with  less  than  64K  of  memory! 

In  practice,  array  y”[  ]  would  be  used  initially  to  store 
the  elements  of  array  d[  ].  Then,  as  the  elements  of  y"[  ] 
are  solved  during  back  substitution,  they  overlay  the  val¬ 
ues  of  d[  ].  To  implement  this  space-saving  technique  in 
Algorithm  1,  change  every  instance  of  d[  ]  to  y”[  ]. 

The  second  variation  is  more  interesting  and  comes 
from  the  need  to  interpolate  data  extracted  from  periodic 
phenomena.  If  you  plot  any  periodic  data  in  polar  coordi¬ 
nates,  a  smooth  curve  between  them  forms  a  closed  curve, 
with  the  endpoints  of  the  curve  meeting.  Plotting  the  same 
data  in  rectilinear  coordinates  with  the  horizontal  coordi¬ 
nates  expressed  over  360  degrees,  it's  easy  to  see  that  you 
can  model  the  curve  with  a  cubic  spline  function. 

Because  the  curve  is  periodic,  the  endpoint  vertical  co¬ 
ordinates  are  by  definition  equal.  In  other  words,  y[l]  = 


y[n].  You  need  to  specify  the  end  conditions  such  that  the 
first  and  second  derivatives  of  the  curve  are  continuous 
with  respect  to  each  other  at  these  points.  Stated  in  math¬ 
ematical  terms,  y’[l]  =  y'[n]  and  y”[l]  =  y”[n]. 

The  second  derivatives  are  easy — they  can  be  ex¬ 
pressed  directly  in  matrix  form.  To  use  the  first  deriva¬ 
tives  of  y(x)  at  the  endpoints,  you  need  an  equation  that 
relates  them  to  y(x)  and  its  second  derivative.  Going  back 
to  the  derivations  for  f’[i](x[i))  and  f’[i  — l](x[i])  and  evaluat¬ 
ing  them  for  x[l]  and  x[n]  respectively,  you  have: 

fllWU  =  yl2l~  yl11  *  (2  *  y"[i]  +  y”[2]) 

h[l]  6 

and 

f’[n  — lXx[n])=  *n]  ~  ytn-l]  +^,y.1n-1)+2yin]l 
h[n  — 1]  6 

But  y’[l]  =  y’[n],  so: 

K»  /y[2]  -  y[l]_y[n]  -  y[n-l]  \ 

\  h[l]  h[n  — 1]  / 

h[n  — 1]*  (y'’[n  — l]+2’y”[n])  +  h[ir(2*y”[l]+y”[2]> 

Again  with  some  matrix  manipulation,  you  get  the  equa¬ 
tions  shown  in  Table  5,  below.  These  equations  can  be 
solved  efficiently  and  quickly  with  another  modified  ver¬ 
sion  of  Gaussian  elimination,  as  shown  in  Table  6,  page  30. 

Other  end  conditions  are  possible.  You  can,  for  exam¬ 
ple,  specify  the  slope  of  the  spline  at  its  endpoints  by 
specifying  the  first  derivatives  at  y[l]  and  y[n].  You  can 


c[2] 

h[2] 

0 

0 

h[1] 

y”[2] 

= 

d[2] 

h[2] 

c[3] 

h[3] 

0 

0 

y”[3] 

d[3] 

0 

h[3] 

c[4] 

0 

0 

y”[4] 

d[4] 

0 

0 

h[n— 2]  c[n— 1] 

h[n — 1] 

y”[n  1 ] 

d[n— 1] 

h[1] 

0 

0  h[n— 1] 

c[n] 

y  ”[n] 

d[n] 

where 


c[i]  =  2  *  (h[i— 1]  +  h[i])  fori  =  2 . n-1 

c[n]  =  2  *  (h[1]  +  h[n— 1]) 


d[i]  =  6  * 


d[n]  =  6  * 


(y[i+1]-y[i] 
h[i] 

(y[2]  -  y[i] 
h[i] 


y[i]  y[i  1 1 
h[i-i] 

y[n]  -  y[n-1] 
h[n-1) 


) 


for  i 


) 


2, . . .  ,n— 1 


Table  S:  Matrix  form  of  periodic  spline  function 
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also  specify  a  linear  combination  of  first  and  second  de¬ 
rivatives  at  the  endpoints.  The  two  examples  presented 
here,  however,  will  generally  prove  the  most  useful  for 
interpolative  curve  fitting. 

Specifying  the  end  conditions  and  solving  the  appropri¬ 
ate  set  of  linear  equations  gives  you  the  coefficients  you 
need  to  solve  your  interpolation  equation.  (Note  that  this 
equation  remains  the  same  no  matter  what  end  conditions 
have  been  specified.)  For  any  given  value  of  x  within  the 
range  of  values  spanned  by  the  knots,  you  need  only  deter¬ 
mine  the  two  knots  between  which  the  value  lies.  This 
gives  you  the  value  of  i  to  insert  in  the  interpolation  equa¬ 
tion  and  with  it  the  appropriate  coefficients  y”[i]  and 


/*  Initialize  array  ef  ]  as  nth  column  of  matrix  M[  ][  ]  7 

e[2]  =  h[1] 
fori  =  3  to  i  =  n— 2 
begin 

e[i]  =  0 
end 

e[n— 1]  =  h[n— 1] 
e[n]  =  c[n] 

/’  Initialize  variable  f  as  matrix  element  M[n][1]  7 
f  =  h[1] 

/*  Reduce  matrix  to  upper  triangular  form  7 

for  i  =  2  to  i  —  n— 2 
begin 

c[i  +  1]  =  c[i+1]  -  h[i]  *  h[i]/c[i] 
d[i+1]  =  d[i+1]  —  d[i]  *  h[i]/c[i] 
e[i+1]  =  e[i+1]-e[i]*h[i]/c[i] 
d[n]  =  d[n]  -  dp]  *  f/c[i] 
e[n]  =  e[n]  -  e[i]  *  f/c[i] 

f  =  —  f  *  h[i]/c[i]  /*  Now  matrix  element  M[n][i]  7 
end 

f  =  f  +  h[n — 1  ]  /*  Now  matrix  element  M[n][n — 1  ]  7 
d[n]  =  d[n]  -  d[n — 1  ]  *  f/c[n — 1  ] 
e[n]  =  e[n]  -  e[n— 1]  *  f/c[n — 1  ] 

/*  Solve  using  back  substitution  */ 

y”[n]  =  d[n]/e[n] 

y"[n— 1]  =  (d[n —  1  ]  —  e[n — 1]  *  y" [n])/c[n  - 1  ] 
fori  =  n— 2toi  =  2 
begin 

y”[i]  =  (d[i]  -  h[i]  *y”[i+1]  -  e[i]  *  y”[n])/c[i] 
end 

y”[1]  =  y”[n]  /*  End  condition  7 


Table  G:  Algorithm  2:  Periodic  spline  coefficient 
determination 


y”[i+l]  to  use  in  solving  for  the  corresponding  y  coordinate. 

What  about  the  related  problem  of  fitting  a  smooth  sur¬ 
face  to  data  plotted  in  three  dimensions?  If  the  data  is  regu¬ 
larly  spaced  in  two  of  those  dimensions  (say  the  x — y  plane), 
you  can  calculate  a  family  of  curves  in  parallel  x—z  planes. 
Each  curve  is  the  intersection  of  the  x—z  plane  with  the 
surface.  Then,  for  any  perpendicular  y— z  plane,  your 
knots  are  the  intersection  of  the  x—z  plane  curves  with  the 
y— z  plane.  From  these,  you  can  calculate  the  intersection 
of  your  surface  with  the  y — z  plane.  With  this  method,  you 
can  determine  any  point  on  the  surface  uniquely. 

Final  Words 

I  could  have  demonstrated  the  above  algorithms  using  a 
small  BASIC  program;  however,  the  Unix  operating  sys¬ 
tem  offers  a  utility  called  spline  that  is  much  more  com¬ 
prehensive.  Heeding  once  again  Richard  Stallman’s  call 
(“The  GNU  Manifesto,”  DDJ,  March  1985)  for  placing  Unix 
in  the  public  domain  (“FGREP,”  DDJ,  September  1985,  was 
my  previous  response),  the  accompanying  "demonstra¬ 
tion”  program  (SPLINE.C)  is  a  full  emulation  of  the  Unix 
spline  utility.  (See  Listing  One,  page  72.) 

If  you  would  rather  not  spend  an  evening  or  two  enter¬ 
ing  and  (inevitably)  debugging  SPLINE.C,  you  can  purchase 
machine-readable  versions  for  $35  from  byHeart  Soft¬ 
ware,  620  Ballantree  Rd.,  West  Vancouver,  BC  V7S  1W3, 
Canada.  Supported  disk  formats  are  CP/M  8-inch  SSSD  and 
MS-DOS  (2.x)  514-inch  DSDD.  Included  on  the  disk  are  the 
source  code  in  C  for  SPLINE.C  and  FGREP.C,  their  execut¬ 
able  programs,  and  the  text  from  this  article  and  “Parallel 
Pattern  Matching  and  FGREP”  (DDJ,  September  1985). 

Cubic  splines  are  an  elegant  solution  to  the  problem  of 
fitting  curves  to  a  set  of  given  points  in  an  x— y  plane.  An 
understanding  of  the  mathematics  used  to  develop  them 
is  not  essential.  The  simplicity  and  efficiency  of  the  algo¬ 
rithms  involved  should  encourage  anyone  interested  in 
graphics  or  data  analysis  to  add  cubic  splines  to  their  soft¬ 
ware  toolboxes. 
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A  General  First-Order 
Sorting  Algorithm 


Most  widely  used  sorting  al¬ 
gorithms,  such  as  the  Shell 
sort  and  quicksort,  require 
a  sorting  time  approximately  propor¬ 
tional  to  nlog2n,  where  n  is  the  num¬ 
ber  of  sort  keys,  whereas  the  bubble 
sort  requires  a  time  proportional  to 
n2.  Often  it  is  stated  erroneously  that 
it  has  been  proved  that  no  sorting  al¬ 
gorithm  can  improve  on  an  nlog2n 
time.  The  proof  refers  only  to  algo¬ 
rithms  based  on  exchanges,  howev¬ 
er,  as  Knuth  states  clearly  in  volume  3 
of  his  series  The  Art  of  Computer 
Programming. 

There  is  a  sort  algorithm  called  the 
radix  sort  that  is  not  based  on  ex¬ 
changes.  This  sort  has  been  known 
and  used  since  long  before  the  time 
of  electronic  computers  and  was  gen¬ 
erally  used  for  sorting  punched 
cards,  but  it  does  not  seem  to  have 
been  widely  adapted  for  computer 
use.  The  time  required  to  do  such  a 
sort  is  proportional  to  n. 

In  seeking  a  reason  for  the  slighting 
of  this  algorithm,  which  I  have  used 
successfully  on  a  variety  of  comput¬ 
ers  for  about  20  years,  I  have  come  to 
the  following  conclusion.  There  must 
be  an  intuitive  feeling  on  the  part  of 
programmers  that,  whereas  sorts  re¬ 
quiring  time  k,n  will  always  be  faster 
than  those  requiring  k2n  log2n  when 
the  value  of  n  is  sufficiently  great 
(where  k,  and  k2  are  arbitrary  con¬ 
stants),  for  practical  values  of  n  that 
fit  into  a  computer's  RAM,  kt  is  suffi¬ 
ciently  greater  than  k2  to  nullify  the 
advantage.  As  I  will  demonstrate,  this 
assumption  is  invalid  in  many  cases. 

Robert  A.  Mclvor,  3100  Carling  Ave., 
Apt.  920,  Nepean,  ON  K2B  6J6,  Canada 


by  Robert  A.  Mclvor 

This  linear-time  sort 
ivas  once  used  on 
punched  cards. 


How  the  Radix  Sort  Works 

The  basis  of  the  radix  sort  algorithm 
is  to  divide  the  sort  keys  into  two  lists, 
with  their  placement  in  a  list  being 
dependent  on  whether  the  least  sig¬ 
nificant  bit  is  set  or  not.  The  two  lists 
are  then  concatenated  with  the  list  in 
which  the  bit  is  not  set  placed  first. 
This  step  is  repeated  for  each  bit  in 
each  sort  key,  working  from  the  least 
significant  end  to  the  most  significant 
end.  When  this  procedure  is  com¬ 
plete,  the  file  is  sorted. 

The  chief  disadvantage  of  this 
method  when  compared  to  exchange 
sorts  is  that  the  time  required  for  com¬ 
pletion  has  the  same  dependence  on 
the  number  of  bytes  in  the  key  as  it 
does  for  the  number  of  keys — that  is, 
it  takes  the  same  time  to  sort  10,000  1- 
byte  records  and  1,000  10-byte  re¬ 
cords.  Exchange  sorts,  on  the  other 
hand,  are  much  less  dependent  on 
key  length  than  on  the  number  of 
keys  because  it  is  usually  unnecessary 
to  compare  every  byte  in  two  keys  to 
determine  which  is  the  greater. 

Another  possible  disadvantage  of 
the  algorithm  as  presented  here  (a 
sort  algorithm  for  linked  lists)  is  the 
additional  space  overhead  required. 
Each  key  must  have  an  additional 
2—4  bytes  allotted  for  a  pointer  ad¬ 
dress.  Although  this  is  perhaps  un¬ 
reasonable  for  1-byte  sort  keys,  the 


disadvantage  becomes  less  and  less 
significant  with  longer  sort  keys.  Fur¬ 
thermore,  if  the  data  to  be  sorted  is 
already  in  a  linked  list,  no  additional 
space  is  required.  For  sorts  in  which 
keys  must  be  extracted  from  a  record 
and  manipulated  to  perform  special 
sorts,  such  as  sorting  signed  numbers, 
sorting  in  reverse  order,  or  sorting  in 
a  special  collation  order,  forming  a 
linked  list  of  the  sort  keys  does  not 
usually  entail  much  additional  effort. 

The  Test  Programs 

Listing  One,  page  86,  is  the  radix  sort 
as  coded  for  the  Macintosh  in  Aztec  C. 
The  include  files  are  needed  to  pro¬ 
vide  the  definitions  of  Randoml  )  and 
TickCountl  )  used  in  the  timing  rou¬ 
tine.  The  routine  MajcApplZonei  ) 
provides  space  in  the  application 
heap  for  the  sort  keys.  It  must  be 
called  before  anything  else,  and  the 
Imalloc  must  be  given  a  noncalculat- 
ed  number  or  the  exit  branch  of  in¬ 
sufficient  space  is  taken.  Also,  the  call 
seems  to  be  required  in  the  routine  in 
which  the  allocation  occurs.  RAM 
disks  and  cache  programs  for  the 
Macintosh  may  have  adjusted  the  ap¬ 
plication  heap,  leaving  no  space  for 
allocation.  Allocation  is  necessary  for 
record  counts  in  the  thousands  be¬ 
cause  the  space  permitted  for  data 
declared  in  the  program  is  limited. 
KEY SI Z  (the  size  of  the  sort  key)  is  de¬ 
clared  at  compile  time  to  avoid  edit¬ 
ing  for  each  change. 

The  sort  program  is  passed  the  key 
size  and  the  pointer  to  the  first  re¬ 
cord.  Two  additional  pointers  (first 
and  last )  follow  the  two  lists  created 
at  each  pass,  whose  heads  are  given 
by  the  pointers  start  and  start2.  The 
pointer  temp  follows  the  combined 
list  during  each  pass.  Each  bit  from 
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Number 
of  Records 


Bytes  in  Key 


4000  74  148 

5000  93  185 

6000  112  222 

7000  131  259 

8000  149  296 

9000  167  333 

10000  186  370 

Times  are  in  60ths  of  a  second. 


Table  1:  Execution  times  of  radix  sort  on  Macintosh 


Number 

of  Records 

Bytes  in  Key 

1 

2 

3  4 

5 

6 

7 

8 

9 

10 

11 

12 

1000 

104 

129 

146  162 

176 

203 

205 

229 

254 

250 

240 

290 

2000 

256 

321 

344  389 

446 

509 

502 

515 

599 

584 

617 

685 

3000 

388 

537 

562  623 

717 

783 

822 

848 

933 

1034 

069 

095 

4000 

570 

775 

857  966 

1136 

1245 

1185 

1255 

1475 

1464 

1571 

1685 

5000 

778 

957 

1149  1228 

1516 

1554 

1549 

1630 

1909 

1929 

2112 

2148 

6000 

930 

1240 

333  1462 

1788 

1902 

1936 

1942 

2205 

2410 

2552 

2762 

7000 

1044 

1547 

1645  1774 

2034 

2287 

2471 

2437 

2771 

3062 

3170 

3295 

8000 

1347 

930 

2111  2429 

2806 

2859 

2975 

3087 

3616 

3625 

3855 

4240 

9000 

1511 

2069 

2212  2483 

3008 

3257 

3057 

3270 

3856 

4111 

4482 

4563 

10000 

1736 

2400 

2639  2899 

3544 

3648 

3845 

4270 

4668 

4695 

4688 

5216 

Table  2:  Execution  times  of  Shell  sort  on 

Macintosh 

Key  Count 

Sort  Key  Length  in  Bytes 

1  2 

3 

4 

5 

6 

7 

8 

9 

10 

1000 

26.7  30.3 

33.2 

34.6 

37.2 

39.8 

42.5 

46.0 

47.5 

48.1 

5.4  10.8 

16.2 

21.6 

27.0 

32.4 

37.8 

43.2 

48.6 

54.0 

2000 

60.7  68.2 

81.2 

85.4 

94.4 

101.0 

105.0 

118.0 

118.0 

118.2 

10.8  21.6 

32.4 

43.2 

54.0 

64.8 

75.6 

86.4 

97.2 

108.0 

3000 

92.1  132.0 

198.0 

16.2  32.4 

162.0 

4000 

138.0  188.0 

21.6  43.2 

5000 

188.0  267.0 

27.0  54.0 

239.0 

32.4 
264.0 

37.8 
328.0 

43.2 

406.0 

48.6 

438.0 

54.0 

459.0 

59.4  (calculated) 
535.0 

64.8  (calculated) 


Top  value  is  for  shell.  Bottom  value  is  for  radix. 

Table  3:  Comparative  sort  time  in  seconds  for  Shell  sort  and  radix  sort  on  Z80 
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least  to  most  significant  is  isolated  in 
turn,  and  the  byte  is  added  to  the  first 
and  last  lists  depending  on  whether  it 
is  0  or  1.  When  the  end  of  the  temp  list 
is  reached,  the  last  list  is  terminated 
with  a  0  pointer,  and  the  last  member 
of  the  first  list  is  pointed  to  the  head 
of  the  last  list  lstart2).  When  all  bits 
have  been  traversed,  the  pointer 
start,  which  points  to  the  head  of  the 
sorted  list,  is  returned.  In  addition, 
checks  are  made  for  empty  lists,  and 
the  appropriate  action  is  taken. 

I  compared  the  radix  sort  algorithm 
times  with  those  obtained  from  the 
Shell  sort  algorithm  given  on  page  116 
of  The  C  Programming  Language  by 
Kernighan  and  Ritchie.  I’ve  provided 
a  listing  of  my  version  of  the  Shell  sort 
for  comparison  (Listing  Two,  page  87). 
The  initialization,  of  course,  is  differ¬ 
ent  for  the  Macintosh. 

Some  Test  Results 

In  both  the  radix  and  the  Shell  sorts,  a 
random  function  was  used  to  pro¬ 


vide  data  for  sorting.  The  times  for 
the  radix  sort,  unlike  those  for  the 
Shell  sort,  are  data  independent.  Ta¬ 
bles  1  and  2,  page  33,  show  the  sort 
times  for  the  radix  and  Shell  sorts  on 
a  512K  Macintosh. 

I  also  programmed  the  algorithms 
in  BDS  C  for  a  Z80  computer  running 
at  2  MHz.  In  both  cases  the  radix  sort 
is  superior  for  sort  keys  shorter  than 
12  bytes  when  the  number  of  records 
exceeds  1,000.  For  10,000  1-byte  re¬ 
cords,  the  radix  sort  is  more  than 
nine  times  faster.  The  crossover  point 
for  12-byte  keys  occurs  at  approxi¬ 
mately  500  records,  and  for  keys  of  7 
bytes  or  less,  the  crossover  is  at  100  or 
fewer  records.  Table  3,  page  33, 
shows  the  results  for  the  Z80  system. 

The  execution  time  of  the  radix 
sort  for  the  Z80  system  can  be  ex¬ 
pressed  by  the  formula  (5.4X10~3)mn 
seconds,  where  m  is  the  number  of 
bytes  in  the  sort  key  and  n  the  num¬ 
ber  of  keys  to  be  sorted.  The  Macin¬ 
tosh  execution  time  was 
(3.11X10_4)mn  seconds — more  than 
17  times  faster.  The  ratio  of  times  for 
the  Shell  sort  was  similar. 


The  radix  sort  algorithm  was  also 
coded  in  Z80  assembly  language.  The 
run  times  are  approximately  six 
times  faster — the  measured  time  for 
the  radix  sort  was  (9.1X10~4)mn  sec¬ 
onds  at  2  MHz. 

You  might  think  that  by  masking 
two  bits  at  a  time  and  dividing  the 
keys  into  four  lists,  an  additional  time 
savings  of  about  50  percent  would  be 
achieved.  In  fact,  the  saving  is  only 
about  17  percent  because  of  the  in¬ 
creased  overhead  in  the  inner  loop. 
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REVIEWS 


Turbo  Prolog: 
The  Language 


he  story  was  too  good  to  be 
true.  I  had  to  believe  it. 

A  software  developer  of 
my  acquaintance  had  designed  an  AI 
product  and  was  searching  for  the 
best  development  environment  for 
its  implementation.  Having  worked 
with  PROLOG,  he  knew  he  wanted  to 
use  it,  if  he  could  only  find  an  imple¬ 
mentation  that  met  his  needs.  Bor¬ 
land,  he  heard,  had  acquired  a  fast 
PROLOG  compiler — not  an  interpret¬ 
er,  but  a  compiler — and  would  be 
selling  it  for  less  than  $100.  Even 
though  price  was  not  his  biggest  con¬ 
cern,  he  felt  he  owed  it  to  prudence 
to  check  this  out.  He  called  Borland. 

Because  he  had  a  product  in  the 
works,  the  developer's  questions 
were  specific  and  technical,  just  as, 
because  Borland  had  not  yet  released 
the  product  and  had  not  developed  it 
in-house,  the  answers  he  got  initially 
were  vague  and  unsatisfying.  Perse¬ 
vering,  he  finally  penetrated  deep 
within  the  company  to  one  program¬ 
mer  who  really  knew  the  product, 
the  in-house  expert.  Although  the 
programmer  was  knowledgeable  and 
forthright,  some  of  his  answers  sur¬ 
prised  the  developer,  who  conse¬ 
quently  posed  even  more  probing 
questions  about  the  features  and  capa¬ 
bilities  of  the  implementation,  elicit¬ 
ing  even  more — to  the  developer — 
surprising  answers.  Finally,  the  pro¬ 
grammer  blurted  out,  “Well,  you 
know  it’s  not  PROLOG;  it's  Turbo 
Prolog.” 

Apocryphal,  no  doubt.  One  of  the 
goals  of  this  review  will  be  to  decide 
what  poetic  truth  there  may  be  in  the 
story. 


Michael  Swaine,  501  Galveston  Dr., 
Redwood  City,  CA  94063. 


by  Michael  Swaine 


The  cut  operator  is 
the  feature  PROLOG 
most  needs  to  lose. 


“Core”  PROLOG 

PROLOG  is  a  declarative  as  opposed  to 
an  imperative  language,  meaning 
that  a  program  consists  of  a  set  of 
statements  of  fact  rather  than  of  a  list 
of  instructions.  The  language  itself 
has  the  ability  to  do  some  of  what  in 
other  languages  is  the  programmer’s 
job  because  PROLOG  embodies  an  in¬ 
ference  engine  based  on  the  tech¬ 
niques  of  resolution  and  unification. 
Resolution  as  a  language  basis  is 
known  to  be  logically  complete  in  the 
sense  that  it  can  generate  any  of  the 
logical  implications  of  the  facts  and 
rules  in  a  knowledge  base.  The  im¬ 
perative  mode,  the  flow  of  control, 
and  the  logical  inference  process  in  a 
PROLOG  program  are  all  handled  on 
an  application-independent  basis  by 
the  interpreter — or,  now  that  PRO¬ 
LOG  compilers  are  coming  into  being, 
at  any  rate  not  by  the  programmer. 
In  principle,  the  programmer  simply 
throws  statements  at  PROLOG,  and 
PROLOG  deduces  what  is  deducible 
(prompted  by  questions,  referred  to 
in  PROLOG  as  goals). 

If  the  above  description  makes  the 
programmer’s  job  sound  too  simple, 
note  that  the  statements  can  be  con¬ 
tingencies  on  variables,  such  as  these 
two  statements: 

grandfather(X,G)  :- 


father(P,G),  mother(X,P). 
grandfather(X,G)  :- 

father(P,G),  father(X,P). 

which  state  that  the  grandfather  re¬ 
lationship  holds  between  entities  X 
and  G  if  the  father  relationship  holds 
between  P  and  G  and  the  mother  re¬ 
lationship  holds  between  X  and  P,  or 
if  the  father  relationship  holds  be¬ 
tween  P  and  G  and  the  father  rela¬ 
tionship  also  holds  between  X  and  P. 
These  rules,  together  with  a  database 
of  facts  such  as  the  following  about 
parents  and  their  children: 

mothedjohn,  rita). 
fatherljacob,  eli). 
father(rita,  luigi). 
father(john,  jacob). 

permit  automatic  deduction  of  impli¬ 
cations,  as  in  the  following  dialogue: 

you:  grandfather(john,G) 

program:  G  =  eli 
program:  G  =  luigi 

in  which  you  ask  for  and  receive  the 
names  of  John's  grandparents. 

Despite  the  curious  fact  that  the  or¬ 
der  of  statements  (for  example,  the  or¬ 
der  of  the  four  statements  about  par¬ 
enthood  above)  is  often  irrelevant  to 
the  successful  execution  of  PROLOG 
programs,  it  is  quite  relevant  to  their 
efficient  execution,  and  a  PROLOG  pro¬ 
grammer  has  to  expend  some  effort 
structuring  programs  for  efficiency. 

For  a  solid  presentation  of  PROLOG, 
you  should  read  Programming  in  Pro¬ 
log,  second  edition,  by  W.  F.  Clocksin 
and  C.  F.  Mellish.  A  good  introduction 
for  programmers  is  Dave  Cortesi’s 
“Tour  of  PROLOG”  ( DDJ ,  March  1985). 
Details  of  these  and  other  sources  are 
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listed  at  the  end  of  this  review. 

What  you  won’t  find  anywhere  is 
the  official  definition  of  the  language. 
Not  only  is  there  no  such  thing  as  stan¬ 
dard  PROLOG,  but  it's  also  not  even 
clear  that  PROLOG  is  a  language  by  ev¬ 
eryone’s  definition.  The  closest  thing 
we  have  to  an  official,  broadly  accept¬ 
ed  definition  is  Clocksin  and  Mellish’s 
"core”  PROLOG.  Clocksin  and  Mellish, 
though,  are  more  descriptive  than 
prescriptive  regarding  linguistic  di¬ 
versity  and  even  seem  to  acknowl¬ 
edge  that  PROLOG  may  be  less  impor¬ 
tant  as  a  language  in  itself  than  for  the 
more  powerful  languages  that  will  be 
developed  in  it  or  from  it.  PROLOG, 
they  say  in  the  preface  to  the  second 
edition  of  their  book,  "is  now  seen  as  a 
potential  basis  for  an  important  new 
generation  of  programming  lan¬ 
guages  and  systems.” 

PROLOG  as  it  now  stands  has  some 
deficiencies,  and  we  have  reason  to 
look  forward  to  that  new  generation 
of  programming  languages.  For  one 
thing,  one  of  the  few  mechanisms  for 
limiting  explicitly  the  search  space  for 
solutions  is  the  fairly  awkward  and 
implicit  technique  of  ordering  clauses 
and  conjuncts.  Another  mechanism  is 
the  cut  operator,  which  Clocksin  and 
Mellish  identify  as  the  feature  PROLOG 
most  needs  to  lose. 

Then  there  are  the  limitations  of 
resolution,  as  discussed  by  Michael  R. 
Genesereth  and  Matthew  L.  Ginsberg 
("Logic  Programming,”  Communica¬ 
tions  of  the  ACM,  September  1985).  A 
good  logic  programming  system, 
they  point  out,  needs  to  be  able  to 
"draw  conclusions  from  uncertain 
data,  reason  analogically,  and  gener¬ 
alize  its  knowledge  appropriately.” 
That’s  not  resolution,  and  it's  not 
PROLOG. 

What  is  PROLOG,  officially?  On  page 
111  of  their  book,  Clocksin  and  Mel¬ 
lish  erect  a  "core”  PROLOG,  built  of 
the  features  most  often  found  in  ex¬ 
isting  implementations,  on  top  of 
"pure”  PROLOG;  the  built-in  predi¬ 
cates  many  people  regard  as  an  inte¬ 
gral  part  of  the  language  proper  are 
in  fact  part  of  the  patchwork  core, 
not  the  pure  essence.  The  body  of 
PROLOG  explicitly  put  forth  in  Clock¬ 
sin  and  Mellish  is  not  a  full  language, 
and  implementers  have  extended  it 
as  they  saw  fit.  Finally,  although 
Clocksin  and  Mellish  have  neverthe¬ 
less  cobbled  together  some  sort  of  av¬ 


erage  implementation  in  their  core 
PROLOG,  a  separate  strand  of  develop¬ 
ment  is  represented  by  micro-PRO- 
LOG,  a  version  with  a  radically  differ¬ 
ent  syntax,  described  in  micro- 
PROLOG:  Programming  in  Logic  by  K. 
L.  Clark  and  F.  G.  McCabe. 

Despite  the  limitations  of  resolu¬ 
tion  and  the  lack  of  definition  of  the 
PROLOG  language,  powerful  and  effi¬ 
cient  implementations  of  PROLOG 
have  been  developed  in  Europe,  Aus¬ 
tralia,  Japan,  and  the  United  States. 
Several  PC-based  PROLOGS  now  exist 
(see  the  box  below),  one  of  the  most 
interesting  of  which,  at  least  in  terms 
of  claims  being  made  about  its  speed, 
is  Borland's  Turbo  Prolog.  Judging  by 
the  discussions  on  DDJ's  CompuServe 
forum,  there  is  much  difference  of 
opinion  about  the  product. 

Because  there  is  no  clear  standard 
against  which  to  weigh  Turbo  Pro¬ 
log,  and  because  vendors  of  other 
personal-computer-based  PROLOG 
implementations  seem  to  have  had 
something  else  in  mind  when  they 
developed  their  products,  it  makes 
sense  to  look  at  Turbo  Prolog  in  isola¬ 
tion;  DDJ  does,  however,  plan  to  fol¬ 
low  up  on  this  review  with  a  compar¬ 
ative  review  of  PROLOG 
implementations.  This  review  focus¬ 
es  on  Borland's  Turbo  Prolog  from 


several  directions:  as  an  implementa¬ 
tion  of  PROLOG,  using  Clocksin  and 
Mellish  core  PROLOG  as  a  soft  stan¬ 
dard;  as  a  language  and  software  de¬ 
velopment  environment  in  its  own 
right;  as  a  learning  environment;  and 
as  a  phenomenon  in  the  world  of 
software  tools.  On  the  way,  it  ad¬ 
dresses  some  of  the  claims  being 
made  about  Turbo  Prolog. 

Claim  1:  Not  Full  PROLOG 

Turbo  Prolog  is  not  full  PROLOG. 

You  hear  this  claim  often,  most  of¬ 
ten  from  PROLOG  purists  and  Borland 
competitors.  It's  certainly  true,  even 
by  a  fairly  flexible  definition  of  the 
language,  that  Turbo  Prolog  lacks 
some  of  the  requisite  elements  of  a 
full  PROLOG  implementation.  The  left 
column  of  Table  1,  page  38,  shows  the 
major  features  of  core  PROLOG  that 
are  missing  in  Turbo  Prolog.  Many 
syntactical  differences  are  left  out  of 
the  table;  Turbo  Prolog  largely  ig¬ 
nores  core  PROLOG  I/O,  substituting 
its  own  rich  collection  of  I/O  primi¬ 
tives,  screen-handling  functions,  and 
graphics  commands.  The  Borland 
syntax  is  eclectic. 

Turbo  Prolog  does,  however,  pro¬ 
vide  the  bulk  of  what  makes  up  core 
PROLOG.  (Henceforth  I’ll  drop  the 
word  core,  but  keep  in  mind  that  I 


MS-DOS  PROLOG 
Implementations 


Ada  PROLOG 

Automated  Design  Associates 
1570  Arran  Way 
Dresher,  PA  19025 
(215)  646-4894 

Arity/J?ROLOG 
Arity  Corp. 

336  Baker  Ave. 

Concord,  MA  07142 

Turbo  Prolog 
Borland  International 
4585  Scotts  Valley  Dr. 

Scotts  Valley,  CA  95066 
(408)  438-8400 

PROLOG/i  and  PROLOG/m 
Chalcedony  Software 
5580  La  Jolla  Blvd.,  #126B 
La  Jolla,  CA  92037 
(619)  483-8513 


PROLOG1  and  PROLOG2 
Expert  Systems  International 
1150  First  Ave. 

King  of  Prussia,  PA  19406 
(215)  337-2300 

MPROLOG  P500 
Logicware 
5000  Birch  St. 

Newport  Beach,  CA  9260 
(714)  476-3634 

LPA  Micro-PROLOG  Professional 
Programming  Logic  Systems 
31  Crescent  Dr. 

Milford,  CT  06460 
(203)  877-7988 

PROLOG-86 
Solution  Systems 
335B  Washington  St. 

Norwell,  MA  02061 
(617)  659-1571 
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mean  this  soft  standard  when  I  refer 
to  PROLOG.)  Turbo  Prolog  is  a  declara¬ 
tive  language  built  around  a  resolu¬ 
tion-based  inference  engine.  The  im¬ 
plementation  uses  recursion  and 
backtracking  and  supports  the  usual 
PROLOG  flow-of-control  tools  of  cut 
and  fail  and  the  explicit  ordering  of 
clauses  and  conjuncts  to  control  pro¬ 
gram  flow.  Turbo  Prolog  also  allows 
the  programmer  additional  control 
via  a  compiler  directive  that  checks 
for  possible  nondeterministic 
clauses.  It  supports,  with  some  excep¬ 
tions  and  extensions,  Clocksin  and 
Mellish  syntax. 

Perhaps  the  greatest  shortcoming 
of  T urbo  Prolog  as  an  implementation 
of  PROLOG  is  the  lack  of  what  might  be 
called  "metalinguistic”  functions  and 
operators.  Some  of  these  supplied  in 
PROLOG  are  arg,  functor,  name,  op, 
clause,  and  call  and  the  univ  operator. 
In  general,  these  functions  allow  the 
PROLOG  program  to  examine  itself,  to 
operate  on  code  as  data,  and  to  con¬ 
struct  new  clauses  and  goals  un¬ 
dreamt  of  by  the  programmer. 


Of  these,  some  are  less  important 
than  others;  op  allows  extension  of 
the  operators  of  the  language  so  that, 
for  example,  you  could  define  '  to  be 
the  exponentiation  operator  that  Bor¬ 
land  didn't  supply.  This  function  is  a 
handy  tool,  allowing  the  program¬ 
mer  to  define  the  arity  and  structure 
(for  example,  two-argument  infix) 
for  new  operators.  But  as  Clocksin 
and  Mellish  point  out,  this  capability 
is  ultimately  nothing  more  than  a  de¬ 
vice  for  prettying  up  I/O;  it  adds  no 
additional  computational  power. 

Also,  to  some  extent  the  metalin¬ 
guistic  predicates  and  operators  are 
interchangeable  or  can  be  defined  in 
terms  of  one  another.  You  don’t  abso¬ 
lutely  need  the  univ  operator  if  you 
have  both  functor  and  arg,  and  vice 
versa.  But  either  the  univ  operator  or 
the  combination  of  functor  and  arg  is 
needed  to  map  data  structures  and 
clauses  (code  elements)  into  one  an¬ 
other  so  that  in  PROLOG  code  is  truly 
data. 

As  an  example  of  the  power  of 
these  metalinguistic  constructs,  con¬ 
sider  the  following  metainterpreter 
for  PROLOG,  adapted  from  Henryk 
Jan  Komorowski  and  Shigeo  Omori’s 


Features  in  “core”  PROLOG  and  not  in  Tur¬ 
bo  Prolog 

“metalinguistic’’  features:  =..  (univ),  arg, 
call,  clause,  functor,  gensym,  name,  op. 
I/O:  getO,  get,  put,  read,  tab,  display,  tell,  tell¬ 
ing,  told,  user,  see,  seeing,  seen, 
reconsult. 


Features  in  Turbo  Prolog  and  not  in  “core” 
PROLOG 

arithmetic:  bitand,  bitnot,  bitxor,  bitor,  bitleft, 
bitright. 

I/O:  readln,  readchar,  readint,  readreal,  read- 
term,  writedevice,  writef,  about  a  dozen 
file  functions,  and  a  wealth  of  screen  han¬ 
dling  functions. 

string  handling  and  type  conversion: 
about  a  dozen  functions. 

system  access:  bios,  system,  membyte, 
memword,  portbyte,  ptr_dword,  storage, 
date,  time. 


Table  1:  Major  feature  differences  between  "core”  PROLOG  and  Turbo  Prolog 


goal 

makewindow(1,7,7,“Source”,0,0,20,35), 
write(“Which  file  to  copy  ?”), 
cursor(3,8),readln(X), 

makewindow(2,7, 7, "Destination", 0,40, 20, 35), 
write(“What  name  for  the  copy  ?”), 
cursor(3,8),readln(Y), 
concat(X,"  ”,X1),concat(X1,Y,Z), 
concatf'copy  ”,Z,W), 

make  windo  w(3 ,7 ,7 , '  ‘  Process’  ’,14,15,8,50), 

write(“  Copying  “,X,”  to  ”,Y),  cursor(2,3), 
system(W). 


Table  2:  A  Borland  routine  that  gives  users  a  window  to  DOS 


article  “A  Model  and  an  Implementa¬ 
tion  of  a  Logic  Programming  Envi¬ 
ronment,”  in  the  Proceedings  of  the 
ACM  SIGPLAN  85  Symposium  on  Lan¬ 
guage  Issues  in  Programming  Envi¬ 
ronments.  This  code  is  also  adapted 
from  Clocksin  and  Mellish. 

prove(true) :- !. 
prove! P,  <morePs>)  :- 

prove(P),  prove!  <morePs>). 
prove(P)  :- 

clause(P,  Body),  prove(Body). 

These  clauses  mean  succeed  when 
the  argument  is  true;  to  prove  a  con¬ 
junction,  prove  the  first  clause,  then 
prove  the  rest;  and  to  prove  one 
thing,  find  a  clause  in  the  database 
with  that  thing  as  its  head  and  prove 
the  body  of  the  clause.  This  metain¬ 
terpreter  allows  the  programmer  to 
redefine  the  action  of  the  PROLOG  in¬ 
terpreter,  and  it’s  the  function  clause, 
with  its  ability  to  examine  code  as 
data,  that  permits  this. 

This  predicate  prove  is  a  simple  ver¬ 
sion  of  the  PROLOG  call.  The  Turbo 
Prolog  manual  (p.  151)  also  defines  an 
interpreter  (called  call )  that  uses  Tur¬ 
bo  Prolog's  call-by-reference  capabili¬ 
ty.  The  listing  (unfortunately  compli¬ 
cated  by  several  typographical  errors) 
suggests  how  you  might  build  the 
missing  metalinguistic  elements. 

Nevertheless,  the  claim  that  Turbo 
Prolog  is  not  full  PROLOG  is  justified, 
and  that  places  limits  on  what  you 
can  do  with  it.  Complex  applications 
developed  under  existing  PROLOG 
versions  may  require  significant  re¬ 
thinking  before  they  can  be  ported  to 
Turbo.  On  the  other  hand,  Turbo  Pro¬ 
log  does  provide  something  that 
other  PROLOGS  may  not  in  its  support 
of  DOS  calls  and  machine-language 
functions.  This  low-level  support 
suggests  that  anything  missing  from 
the  compiler  can  be  supplied — if 
you're  willing  to  write  it  yourself. 

What  may  prove  to  be  as  great  a 
hindrance  to  experienced  PROLOG 
programmers  using  Turbo  Prolog, 
though,  are  the  features  the  language 
has  that,  from  a  purist's  point  of 
view,  it  shouldn't  have.  These  fea¬ 
tures  are  also  the  greatest  advantage 
Turbo  Prolog  might  claim  over  more 
faithful  implementations. 

Claim  2:  Yen  Language 

Turbo  Prolog  is  not  PROLOG  at  all  but 
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a  new  language. 

"It's  not  PROLOG;  it's  Turbo  Pro¬ 
log." — apocryphal  Borland 

programmer. 

The  right-hand  column  of  Table  1 
points  out  another  way  in  which  Bor¬ 
land's  compiler  deviates  from  PRO¬ 
LOG:  by  extending  it  and  by  being  in 
some  senses  a  richer  language.  Turbo 
Prolog  allows  access  to  memory,  I/O 
ports  ,  and  BIOS  routines  via  a  bios 
predicate  and  to  DOS  via  a  predicate 
called  system.  Using  the  system  pred¬ 
icate  and  the  strong  display  facilities 
of  Turbo  Prolog,  the  programmer 
can  easily  give  the  user  a  window  to 
DOS.  The  program  shown  in  Table  2, 
page  38,  is  a  Borland-supplied,  win¬ 
dow-oriented,  file  copy  routine  that 
shows  the  system  predicate  in  action. 
As  you  see,  it  is  virtually  devoid  of 
any  PROLOG  declarative  flavor. 

Because  Turbo  Prolog  is  compiled, 
certain  features  Clocksin  and  Mellish 
describe,  such  as  trace,  are  imple¬ 


mented  in  Turbo  as  compiler  direc¬ 
tives.  Turbo  Prolog  also  has  some 
compiler  directives  expressly  con¬ 
ceived  to  help  assess  efficiency  of 
program  structure  in  PROLOG,  such 
as  check— determ,  check— cmpio, 
nowarnings,  and  diagnostics.  These 
tools,  which  do  such  things  as  elimi¬ 
nating  tail  recursions  and  flagging 
possibly  nondeterministic  clauses, 
are  needed  in  a  language  that  pro¬ 
vides  as  few  explicit  controls  on  pro¬ 
gram  flow  as  does  PROLOG.  Turbo 
Prolog  also  maintains  the  program¬ 
mer's  variable  names  for  postcompi¬ 
lation  editing  of  source  code. 

You  can,  according  to  Borland  (I 
haven’t  tested  this),  incorporate  in 
your  Turbo  Prolog  programs  subrou¬ 
tines  written  in  8088  assembly  lan¬ 
guage,  FORTRAN,  C,  or  Pascal  (but  not 
Turbo  Pascal,  yet).  That  alone  won't 
make  the  routines  PROLOG-like,  of 
course.  If  you  want  to  write  compo¬ 
nents  in  some  other  language  and 
have  them  perform  PROLOG  pur¬ 
poses,  you  may  have  to  work  a  little: 
a  single  three-argument  predicate 


could  conceivably  require  nine  sepa¬ 
rate  routines  if  implemented  in  as¬ 
sembly  language  because  each  per¬ 
mutation  of  instantiated  and 
uninstantiated  arguments  could  re¬ 
quire  different  action. 

Some  of  Turbo  Prolog’s  deviations 
from  PROLOG  style — for  example, 
Turbo  Prolog's  strict  data  typing — 
force  rethinking  of  program  logic. 
You  could  argue  that  strict  data  typing 
violates  PROLOG  design  and  limits  use¬ 
fulness  and  portability.  Borland's 
manual  defends  the  practice  in  terms 
of  creating  a  more  secure  program  de¬ 
velopment  environment  and  reduc¬ 
ing  space  requirements  for  the 
language. 

There  are  other  arguments  for  us¬ 
ing  some  kind  of  data  typing  in  PRO¬ 
LOG:  Daniel  Brand's  article  "On  Typ¬ 
ing  in  Prolog,”  in  the  January  1986 
ACM  SIGPLAN  Notices  presents  argu¬ 
ments  for  at  least  one  model  of  typed 
PROLOG.  Brand  claims  his  model  has 
the  advantages  of  improved  program 
readability,  reduced  computation 
time  because  of  fewer  and  shorter 
clauses  and  reduced  search  space, 
and  reduced  need  for  the  cut  opera¬ 
tor.  It  requires  an  enhanced  unifica¬ 
tion  algorithm  that  checks  data  types 
before  unifying  clauses.  This  slows 
things  down  a  little,  but  Brand  thinks 
the  cumulative  effect  is  faster  code. 
Turbo  Prolog's  approach  is  different 
but  shares  some  of  these  advantages. 

A  related  limitation  of  Turbo  Pro¬ 
log  is  the  constraint  that  you  can  only 
assert  facts,  not  rules,  and  this  also  re- 
tricts  the  product’s  usefulness. 

Is  Turbo  Prolog  truly  PROLOG?  If 
you  need  the  full  metalinguistic 
power  of  the  core  predicates  that 
Clocksin  and  Mellish  sketch  out  in 
Chapter  6  of  their  book,  or  if  you  will 
be  porting  a  complex  existing  PRO¬ 
LOG  system  to  the  PC — no.  Otherwise, 
consider  this  just  a  particularly  devi¬ 
ant  dialect  among  other  deviations. 
The  reason  for  Turbo  Prolog’s  devi¬ 
ations  from  Clocksin  and  Mellish  is 
clear:  the  programmers  wanted  to 
make  it  fast. 

Claim  3:  Faster 

Turbo  Prolog  is  faster  than  the  Japa¬ 
nese  fifth-generation  language  sys¬ 
tems. 

This  claim  comes  from  the  Turbo 
Prolog  manual  (p.  4):  "Turbo  Prolog 
runs  on  a  computer  costing  about 
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$2000,  yet,  in  a  comparison  made  in 
1984  using  an  earlier  version  of  the 
system,  it  produced  programs  that 
executed  faster  than  those  produced 
by  the  prototype  of  the  Japanese 
Fifth  Generation  computer.”  And 
from  the  March  3  press  release,  Tur¬ 
bo  Prolog  "outperforms  other  exist¬ 
ing  PROLOG  language  tools  by  factors 
of  up  to  10,000.” 

The  developers  of  the  compiler 
that  Borland  is  marketing  in  the  Unit¬ 
ed  States  as  Turbo  Prolog  sacrificed 
power  and  portability  for  speed. 
How  much  speed  did  they  buy? 

The  speed  of  AI  languages  is  mea¬ 
sured  in  UPS  (logical  instructions  per 
second).  It's  reasonable  that  a  fifth- 
generation  language  should  have  a 
different  unit  for  measuring  perfor¬ 
mance  from  that  used  in  evaluating 
third-generation  languages.  The  first- 
through  fifth-generation  language 
classification  is  chiefly  a  matter  of  the 
power  of  a  typical  instruction.  A  fifth- 
generation  logical  instruction  ought  to 
do  more  than  a  third-generation  in¬ 
struction  does — so  the  theory  goes. 
Turbo  Prolog  has  many  instructions 
that  PROLOG  lacks,  but  these  are  all 
third-generation  (or  possibly,  in  the 
case  of  the  graphics  operations, 
fourth-generation)  instructions. 

To  give  a  true  picture  of  what  LIPS 
measure  as  compared  with  non-logi- 
cal  IPS  would  require  fairly  detailed 
analysis  of  some  large  tasks,  lifting 
out  components  that  are  and  are  not 
good  candidates  for  backtracking 
and  resolution.  The  picture  would  be 
complicated  by  subtle  differences  in 
the  goals  of  the  declarative  and  im¬ 
perative  modes  of  programming: 
How  do  you  compare  speed  if  you 
don’t  agree  about  what  constitutes 
acceptable  user  input,  for  example? 

What  I’m  doing  here  is  much  less 
than  this;  I’m  providing  the  results  of 
a  typical  benchmark  for  imperative 
programming  with  a  rough  bound 
on  the  number  of  logical  instructions 
it  requires  in  Turbo  Prolog. 

The  results  don’t  support  Borland’s 
extravagant  claims.  The  benchmark  I 
ran  was  a  simple  recursive  version  of 
the  sieve  of  Eratosthenes.  Generating 
all  primes  less  than  n  should  take  on 
the  order  of  n2  operations  or  less:  for 
primes  less  than  100,  that’s  on  the  or¬ 


der  of  10,000  LIPS  as  a  rough  bound. 
The  Turbo  Prolog  result,  0.5  second 
for  all  primes  less  than  100,  should  be 
compared  with  results  for  your  fa¬ 
vorite  imperative  language  and  for 
other  PROLOG  implementations.  (I  got 
a  value  of  19  seconds  for  another, 
particularly  slow,  interpreted  imple¬ 
mentation  of  PROLOG.)  Turbo  Prolog 
was  fast,  but  nowhere  near  10,000 
times  as  fast  as  the  slowest  competi¬ 
tor  I  could  find.  Furthermore,  be¬ 
cause  the  Symbolics  PROLOG  machine 
is  projected  to  run  at  100,000  LIPS,  I 
don't  think  that  any  claim  of  speed 
for  Turbo  Prolog  comparable  to 
speed  for  serious  fifth-generation 
machines  need  be  taken  seriously. 

Finally,  Turbo  Prolog  lacks  virtual 
memory,  a  feature  of  some  other  mi¬ 
crocomputer  implementations.  I  sus¬ 
pect  that  the  fast  benchmark  results 
Borland  alludes  to  are  based  on  ac¬ 
cesses  to  databases  in  RAM. 

Turbo  Prolog  requires  an  IBM  PC  or 
compatible  with  PC-DOS  or  MS-DOS  2.0 
or  later  and  384K  RAM.  I  tested  it  with 
an  AT&T  6300  with  640K  RAM.  I  also 
brought  it  up  on  a  MacCharlie  Plus 
with  640K  RAM  as  a  128K  Switcher  ap¬ 
plication  on  a  512K  Hyperdrive  Mac. 

Borland’s  speed  claims  are  perhaps 
extravagant,  but  Turbo  Prolog  cer¬ 
tainly  produces  fast  code,  particular¬ 
ly  when  databases  are  small  enough 
to  reside  in  RAM. 

Claim  4:  Difficult 

PROLOG  is  difficult  to  understand, 
learn,  and  use,  and  Turbo  Prolog  is  in 
this  respect  an  implementation  of 
PROLOG. 

This  one  is  common  among  experi¬ 
enced  programmers.  I  support  Mor- 
ein’s  law,  passed  by  Robert  Morein, 
the  author  of  A.D.A.  PROLOG,  a  year  or 
so  ago,  which  states  the  following:  If 
it’s  hard  in  FORTRAN,  it's  easy  in  PRO¬ 
LOG.  If  it’s  hard  in  PROLOG,  it’s  easy  in 
FORTRAN. 

I  think,  but  will  not  try  to  defend 
this  opinion,  that  PROLOG  is  no  harder 
than  FORTRAN.  I  find  Turbo  Prolog  to 
be  an  excellent  learning  environ¬ 
ment,  although  it’s  arguable  just 
what  the  learner  is  learning  when 
learning  Turbo  Prolog. 

Turbo  Prolog  has  an  excellent  user 
interface,  with  multiple  windows  for 
editing,  tracing,  output,  and  mes¬ 
sages  and  pull-down  menus  for  ac¬ 
cessing  DOS,  configuring  the  system, 


and  selecting  the  destination  for  com¬ 
pilation  (RAM,  disk).  It’s  a  compiler 
with  the  interactive  feel  of  an  inter¬ 
preter.  It  has  the  same  editor  Borland 
puts  in  all  its  products — fine  if  you 
like  WordStar,  but  more  to  the  point, 
instantly  familiar  to  millions  of  peo¬ 
ple.  This  is  the  user  interface  Borland 
will  put  into  the  next  version  of  Tur¬ 
bo  Pascal,  projected  for  release  in  the 
second  quarter  of  next  year. 

The  manual  is  a  decent  tool  for 
learning  Turbo  Prolog  or  the  begin¬ 
nings  of  PROLOG.  To  go  beyond,  a 
book  on  the  language  is  necessary. 
The  manual  contains  abundant  ex¬ 
amples  of  code,  both  short  illustrative 
segments  and  full  programs.  After 
developing  the  difficult  topic  of  the 
cut  operator,  the  manual  gives  practi¬ 
cal,  rule-of-thumb  advice  for  its  use. 
The  manual’s  chief  defects  as  a  learn¬ 
ing  tool  are  an  inadequate  index,  ex¬ 
cessive  errors,  and  the  lack  of  ade¬ 
quate  acknowledgment  of  devia¬ 
tions  from  Clocksin  and  Mellish  core 
PROLOG.  For  that  matter,  I  could  find 
no  references  to  Clocksin  and  Mellish 
or  any  other  book  on  PROLOG.  Never¬ 
theless,  it’s  generally  good  tutorial 
documentation  and,  if  cleaned  up  for 
the  next  printing,  should  be  useful  to 
most  people  interested  in  getting 
started  with  PROLOG. 

I  conducted  an  informal  test  of  ease 
of  learning,  teaching  a  novice  the  ru¬ 
diments  of  Pascal  and  of  PROLOG  us¬ 
ing  the  Turbo  Pascal  and  Turbo  Pro¬ 
log  manuals  as  texts.  Although  I  have 
taught  Pascal  professionally  and 
know  it  much  better  than  I  do  PRO¬ 
LOG,  I  saw  no  difference  in  ease  of 
acquiring  the  concepts. 

Claim  S:  Sorry  Excuse  for  Code 

Turbo  Prolog  is  a  "sorry  excuse  for 
coding”  from  "a  couple  of  Danish 
folks.” 

PC  Week  made  this  claim  in  the 
May  27,  1986,  issue  under  its  house 
pseudonym  Spencer  F.  Katt. 

It’s  true  that  Turbo  Prolog  is  a  Dan¬ 
ish  product,  as  is  Turbo  Pascal;  nearly 
all  Borland  products  are  European. 
Borland  is  oddly  secretive  about  the 
fact  that  it  is  primarily  in  the  business 
of  software  acquisition  and  distribu¬ 
tion;  Borland's  Independent  Contrac¬ 
tor  Nondisclosure  Agreement  (which 
I  have  not  signed)  defines  as  trade  se¬ 
cret  "all  information  concerning  the 
identity  or  whereabouts  of  key  devel- 
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opers  of  Company  products,  past  or 
current.”  Reflex  may  be  the  one  Bor¬ 
land  product  widely  known  to  have 
been  acquired. 

It’s  not  true,  however,  that  Turbo 
Prolog  is  poorly  written.  This  is  a 
good  piece  of  coding.  It  produces  sur¬ 
prisingly  fast  compiled  code.  The 
user  interface  is  better  than  Turbo 
Pascal's  current  interface  for  rapid 
development  of  small  routines.  And 
the  links  to  DOS  and  other  languages 
and  the  tools  for  optimization  make 


this  product  more  than  a  toy. 

The  applications  for  which  Turbo 
Prolog  is  most  appropriate  may  be 
applications  that  are  on  the  border  of 
artificial  intelligence  rather  than  in 
the  mainstream.  As  the  manual  sug¬ 
gests,  it  could  serve  as  a  good  specifi¬ 
cation  language.  The  speed  of  the 
compiled  code  and  the  fifth-genera¬ 
tion  richness  of  the  instructions  may 
make  it  a  good  database  development 
language,  whereas  the  lack  of  meta¬ 
linguistic  power  may  make  it  a  poor 
candidate  for  abstract  problem  solv¬ 
ing.  In  any  case,  it  has  the  Turbo  Pas¬ 
cal  strengths  for  quick  development 
and  testing  of  small  modules.  The 
product  has  a  place. 

Claim  G:  Half-Million  Sales 

Borland  will  sell  half  a  million  copies 
of  Turbo  Prolog  in  the  next  two 
years. 

That’s  what  Philippe  Kahn  claims. 
Well,  actually  he  says  there  may  be 
that  many  people  using  the  prod¬ 
uct — not  the  same  thing,  quite. 

It’s  possible.  Logic  programming  is 
in  vogue,  and  Borland  has  built  a  rep¬ 
utation  with  Turbo  Pascal  that  could 
transfer  to  Turbo  Prolog.  Novice  Tur¬ 
bo  Pascal  users  didn't  care  about  its 
deviations  from  the  standard,  and 
novice  Turbo  Prolog  users  will  be 
even  less  sensitive  to  the  less-con- 
straining  soft  standard  for  PROLOG. 
Of  course,  Turbo  Prolog  is  not  the 
only  PROLOG,  nor  this  time  has  Bor¬ 
land  got  the  cheapest  product.  But  if 
any  PROLOG  is  as  successful  as  Kahn 
hopes  his  will  be,  it  will  be  good  news 
for  all  PROLOG  developers. 

Some  companies  are  beginning  to 
look  upon  Borland  as  the  company 
that  opens  markets  for  them.  On  May 
20,  less  than  three  weeks  after  Turbo 
Prolog  became  available,  Arity  an¬ 
nounced  its  trade-in  plan.  Buy  Arity’s 
$795  PROLOG  development  system, 
and  the  firm  will  give  you  $50  for 
page  213  of  your  Turbo  Prolog  man¬ 
ual  as  proof  of  purchase  (that's  the 
page  that  explains  that  there  is  no 
simple  way  of  interfacing  Turbo  Pro¬ 
log  modules  with  Turbo  Pascal  pro¬ 
grams).  The  program  is  due  to  expire 
about  the  time  you  read  this,  but  it 
presents  one  view,  the  view  Arity 
would  like  you  to  have,  of  Turbo  Pro¬ 
log’s  position:  a  beginner’s  language 
for  those  who  want  to  play  with  PRO¬ 
LOG  syntax  before  deciding  whether 


to  move  up  to  a  serious  development 
system.  It's  the  view  Logitech  would 
like  you  to  ha ve  of  T urbo  Pascal  vis-a- 
vis  Logitech’s  Modula-2,  which  is 
why  it  is  selling  a  product  that  lets 
you  translate  your  old  Turbo  Pascal 
programs  to  Modula-2. 

There  is  undoubtedly  some  truth  to 
this  perception.  It's  quite  possible 
that  Turbo  Prolog,  with  its  inviting 
user  interface,  will  open  up  a  large 
market  for  PROLOG  products. 

Logic  programming  has  been  pro¬ 
jected  to  be  the  dominant  form  of 
programming  in  the  next  century. 
The  next  century  begins  in  14  years 
and  4  months.  That  should  be  more 
than  enough  time  to  turn  PROLOG 
into  that  "important  new  generation 
of  programming  languages  and  sys¬ 
tems"  Clocksin  and  Mellish  envision, 
especially  if  Kahn's  prediction  of  half 
a  million  new  PROLOG  programmers 
is  even  half  right. 
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High-Speed  Thrills 

A  Review  of  Eight  Turbo  Boards 
for  the  IBM  PC 


Over  the  past  few  years,  most 
of  us  switched  from  our  old 
Z80  computers  using  the 
CP/M-80  operating  system  to  IBM  PCs 
(or  clones)  using  PC(MS)-DOS.  Then  we 
experienced  the  big  disappointment 
of  learning  that  the  new  machines 
weren't  quite  as  fast  as  the  old  ones 
were.  After  all,  most  of  us,  even  pro¬ 
grammers,  have  the  great  American 
dream:  “More  speed,  faster  is  better, 
drag  you  for  pink  slips  at  the  next 
stoplight!"  Finding  that  your  new 
computer  isn’t  as  fast  as  your  old  one 
can  damage  your  ego  more  than 
learning  your  brand  new,  expensive, 
foreign  sports  car  isn't  as  fast  as  your 
old  jalopy. 

When  IBM  announced  the  PC/AT, 
we  envisioned  the  enhanced  produc¬ 
tivity  and  throughput  the  original  PC 
had  seemed  to  promise  but  had  not 
produced.  After  all,  we  can  rational¬ 
ize  that  the  most  time-consuming 
part  of  program  development  is  the 
endless  debug-recompile-test  pro¬ 
cess.  If  we  have  faster  machines,  we 
can  shorten  the  software  develop¬ 
ment  process  and  we  can  save  mon¬ 
ey.  The  AT  rekindled  the  American 
dream:  lightning  fast  compiles;  the 
pleasure  of  being  power  users.  Most 
of  us,  though,  have  invested  too 
much  time  and  money  expanding 
our  old  PCs  and  PC/XTs  with  memory 
expansion  boards,  hard  disks,  and 
anything  else  we  could  stuff  into 
them  to  really  justify  junking  our  old 
PCs  and  XTs  to  buy  new  ATs. 

Early  1985  produced  rumors  of 
high-speed  computer  chips  and 
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We  used  six  applica¬ 
tions  programs  and 
five  benchmark  pro¬ 
grams  to  test  the 
boards. 


boards  that  could  speed  up  PCs  to 
match  the  AT’s  performance — well, 
almost  match  the  AT’s  performance. 
NEC  V20  rumors  promised  to  replace 
your  old  8088,  provide  complete  soft¬ 
ware  compatibility,  and  give  you  an 
85  percent  increase  in  processing 
speed — still  no  match  for  the  AT  but 
not  bad.  In  reality,  the  V20  provided 
what  may  be  an  18  percent  speed  in¬ 
crease  rather  than  the  dreamed  of  85 
percent  gain. 

Last  fall,  we  wandered  through 
Comdex  in  Las  Vegas  and  saw  proto¬ 
type  accelerator  boards  that  made 
PCs  run  not  just  as  fast  as  ATs  but 
even  faster — the  boards  were  soft¬ 
ware  compatible  with  both  ma¬ 
chines.  These  boards  are  now  becom¬ 
ing  one  of  the  most  popular  and 
desired  PC  and  XT  hardware  en¬ 
hancements.  In  this  article,  we'll  re¬ 
view  six  of  these  so-called  turbo 
boards  and  maybe  rekindle  your 
American  dream. 

The  Benchmarks 

Most  turbo  boards  utilize  on-board 
high-speed  memory  with  a  16-bit  in¬ 
terface,  a  high  clock  rate,  and  a  more 
efficient  CPU  to  produce  the  desired 


increase  in  throughput.  The  boards 
we  tested  for  this  article  produced 
processing  speeds  ranging  from  one 
and  a  half  times  the  speed  of  a  stan¬ 
dard  PC  to  well  beyond  the  speed  of  a 
standard  AT — even  beyond  the  speed 
of  an  AT  with  a  higher  clock  speed. 

Our  test  machine  was  an  IBM  PC 
containing: 

•  256K  RAM  on  the  motherboard 

•  AST  Six  Pac  with  384K  RAM 

•  two  floppies 

•  10-megabyte  internal  drive 

•  10-megabyte  IOMEGA  Bernoulli  Box 

•  STB  Graphics  Plus  and  Color  Monitor 

•  Mitsuba  Expansion  Unit 

We  used  the  following  programs  to 
test  the  turbo  boards’  PC  compatibil¬ 
ity:  BASICA,  Brief  Programmer's  Edi¬ 
tor,  dBASE  III,  Framework  II,  Micro¬ 
soft  C  3.0,  and  Microsoft  Link.  We’ve 
noted  where  any  didn’t  function 
properly. 

We  used  the  following  benchmark 
programs  compiled  with  the  Micro¬ 
soft  C  3.0  compiler: 

•  Compile/Link:  Compile  and  link  a 
425-line  C  program  with  a  RAM  disk 
for  the  TMP  work  area. 

•  Sieve  *  10:  Ten  loops  through  the  Er¬ 
atosthenes  Sieve  prime-number  pro¬ 
gram  (Listing  One,  page  88). 

•Sieve  *  100:  100  loops  through  the 
Sieve  program. 

•  Dhrystone:  The  Dhrystone  bench¬ 
mark  program  (Listing  Two,  page  88). 

•  The  Sysinfo  utility  included  in  Nor¬ 
ton's  Utilities,  Version  3.1. 

The  public-domain  utility  TIMEIT, 
written  by  Jack  Means,  timed  the  first 
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three  benchmarks.  Table  1,  below, 
contains  a  summary  of  our  results. 

Reinhold  P.  Weicker  originally  de¬ 
veloped  the  Dhrystone  program  us¬ 
ing  the  Ada  programming  language. 
A  careful  C  conversion  preserves  the 
Ada  likeness  at  the  expense  of  C  for¬ 
mat  and  at  the  same  time  demon¬ 
strates  the  versatility  of  C.  The  pro¬ 
gram  does  nothing  useful  but  is  a 
well-rounded  benchmark  program 
containing  dynamic  memory  alloca¬ 
tion  and  manipulation,  along  with 
some  number  crunching. 

The  Boards 

We'll  now  give  a  brief  description  of 
each  of  the  boards  we  used  in  our 
benchmark  tests  and  some  brief  com¬ 
ments  on  their  performance.  See  the 
list  of  companies  and  addresses  on 
page  49. 

QuadSprint 

Quadram's  QuadSprint  contains  an 
8086  microprocessor  running  at  9.54 
MHz.  This  board  takes  up  one  full- 
size  slot  and  replaces  the  8088  with  a 
jumper-type  ribbon  cable.  Because 
you  remove  the  8088  from  the  PC, 
you  have  to  de-install  the  board  in  or¬ 
der  to  return  to  native  mode.  Quad 
Sprint  needs  no  software  drivers  or 
special  programs  for  operation. 

The  QuadSprint  board  has  4K  RAM, 
high-speed  cache  memory  that  is 


software  switchable  with  a  small  BA¬ 
SIC  program,  which  is  listed  in  the 
manual.  The  program  uses  an  OUT 
command  to  send  a  value  to  the  speci¬ 
fied  port  (on  or  off).  The  board  was 
software  and  hardware  compatible 
with  all  our  tests.  QuadSprint  uses  the 
existing  PC  memory  via  the  8-bit  PC 
system  bus,  which  is  probably  why 
the  speed  increase  was  not  as  high  as 
that  of  some  of  the  other  8086  boards. 

PC  Turbocharger 

PC  Turbocharger  from  Univation 
uses  an  8086  microprocessor  running 
at  10  MHz.  The  board  takes  up  a  full 
slot  and  replaces  the  8088  with  a  rib¬ 
bon  cable.  The  company  provides  an 
8087  noise  suppressor  to  plug  into  the 
8087  socket  on  the  motherboard.  You 
must  replace  two  chips  on  the  board 
if  you  have  the  PC  Model  2  with  a 
256K  motherboard.  Failure  to  read 
the  documentation  prior  to  installa¬ 
tion  to  ensure  the  proper  chips  are  in 
place  may  scramble  the  data  on  your 
hard  disk! 

The  PC  Turbocharger  board 
doesn't  require  that  you  reboot  the 
system  to  change  speeds,  as  is  the 
case  with  some  of  the  other  boards. 

Univation  provides  several  utilities 
with  the  PC  Turbocharger,  including 
a  RAM  disk,  spooler,  and  cache — all 
have  user-definable  sizes.  The  com¬ 
pany  also  includes  a  memory  tester 


and  a  program  that  copies  ROM  to 
high-speed  RAM  for  fast  execution  of 
programs  that  make  BIOS  calls,  such 
as  BASICA.  Because  this  board  con¬ 
tains  its  own  memory,  we  neutral¬ 
ized  the  AST  Six  Pac  memory  by  set¬ 
ting  its  memory  jumpers  to  0. 

SpeedPac  286 

SpeedPac  286  from  Victor  Technolo¬ 
gy  contains  an  80286  microprocessor 
running  at  7.2  MHz.  The  board  takes 
up  one  half-size  slot  and  replaces  the 
8088  with  a  jumper-type  ribbon  ca¬ 
ble.  You  can’t  switch  back  to  stan¬ 
dard  mode,  and  you  must  set 
jumpers  to  indicate  available  memo¬ 
ry.  Because  the  board  has  no  memo¬ 
ry,  only  PC  memory  is  used.  The 
board  does,  however,  contain  a  high¬ 
speed  8K  cache  buffer  and  resident 
caching  software.  No  software  driv¬ 
ers  or  special  programs  are  neces¬ 
sary.  The  SpeedPac  286  has  a  socket 
for  an  80287  math  coprocessor. 

Victor  Technology  provides  special 
instructions  for  installing  dBASE  III. 
Because  you  can't  switch  back  to  PC 
mode,  many  types  of  protected  soft¬ 
ware  may  require  that  you  remove 
the  board  temporarily  when  install¬ 
ing  the  software  on  your  hard  disk. 
This  is  a  minor  inconvenience  in  ex¬ 
change  for  the  added  performance 
you  receive  for  this  board's  low  price. 
The  board  is  compatible  with  IBM's 


Comp/Link 

index 

seconds 

Sieve*  10 

index 

seconds 

Sieve*  100 

index 

seconds 

Dhrystone 

index 

loops/sec 

Sysinfo 

index 

IBM  PC 

Hill 

1.00 

1.00 

1.00 

1 

12.30 

107.60 

333 

IBM  PC/AT 

3.13 

5.60 

N/A 

N/A 

N/A 

1041 

PC  Turbo  286 

3.35 

4.55 

5 

8.40 

69.15 

23.62 

1666 

PC  Turbocharger 

1.83 

imw'iii1  i— 

2.39 

2.63 

2.20 

110.48 

44.99 

877 

Pfaster  286 

3.30 

3.79 

5.33 

5.17 

8.40 

70.19 

3.24 

20.16 

1724 

QuadSprint 

1.51 

1.62 

1.92 

1.97 

2 

153.41 

7.58 

56.08 

657 

SpeedPac  286 

2.08 

2.37 

3.43 

3.41 

6.60 

1 1 1 .45 

5.17 

31 .36 

1136 

286  Speed  Pack 

2.28 

3.28 

3.84 

7 

N/A 

5.39 

32.80 

1282 

Table  1:  Benchmark  summary 
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Enhanced  Graphics  Adapter. 

We  found  that  the  8088  replace¬ 
ment  cable  was  too  short  to  reach 
over  an  existing  board  in  the  first  slot. 
We  had  to  insert  the  SpeedPac  286 
board  in  the  slot  closest  to  the  8088 
socket,  which  is  not  a  disadvantage  in 
the  XT  where  the  half  slot  is  seldom 
used.  This  board  performed  very 
well  considering  that  it  was  using  ex¬ 
isting  200-ns  PC  memory  and  an  8-bit 
interface.  Victor  Technology  also  of¬ 
fers  a  60-day  money-back  guarantee. 
This  is  a  real  plus! 

286  Speed  Pack 

Classic  Technology  Corp.'s  286  Speed 
Pack  contains  an  80286  microproces¬ 
sor;  its  speed  is  not  documented.  The 
board  takes  up  one  full-size  slot  and 
replaces  the  8088  with  a  jumper-type 
ribbon  cable.  You  plug  the  PC’s  8088 
into  a  socket  on  the  board  and  change 
back  to  standard  mode  with  a  switch 
on  the  back  of  the  board.  Then  you 
must  reboot.  The  socket  is  positioned 


so  that  the  8088 's  label  reads  in  the 
opposite  way  from  the  labels  for  the 
rest  of  the  chips  on  the  board;  this 
could  cause  confusion,  even  though  it 
is  well  documented. 

You  must  set  a  jumper  on  the  286 
Speed  Pack  board  to  indicate  mother¬ 
board  type:  Model  1,  2,  or  XT.  The 
board  has  a  socket  for  an  80287  math 
coprocessor  and  has  its  own  RAM, 
which  may  be  expanded  to  4  mega¬ 
bytes.  This  board  is  designed  primari¬ 
ly  for  the  XT  and,  if  you  have  an  in¬ 
ternal  hard  disk,  requires  a  130-watt 
power  supply.  Because  our  test  com¬ 
puter  had  only  a  60-watt  power  sup¬ 
ply  and  an  internal  hard  disk,  we 
couldn't  run  the  PC  with  the  hard 
disk  installed.  We  also  didn't  run  the 
compile/link  benchmark.  When  in¬ 
stalled  in  an  XT,  286  Speed  Pack  uses 
the  first  64K  RAM  on  the  mother¬ 
board  to  hold  DOS;  all  other  applica¬ 
tions  run  in  the  high-speed  memory 
located  on  the  board  itself. 

The  286  Speed  Pack  board’s  bench¬ 
mark  times  were  inconsistent,  as  was 
the  case  with  most  of  the  boards;  we 
used  the  "best  case”  values.  Classic 


Technology  Corp.  also  provides  net¬ 
work  boards  that  allow  multiple 
workstations  to  be  attached  to  a  PC/ 
XT  containing  286  Speed  Pack.  This 
setup  gives  you  an  XT  file  server  with 
the  power  and  speed  of  an  AT  server. 

Piaster  286 

Pfaster  286  from  Phoenix  Computer 
Products  Corp.  uses  an  80286  micro¬ 
processor  running  at  8  MHz.  The 
board  takes  up  a  full  slot  and  is  the 
easiest  of  all  the  boards  to  install.  It 
uses  no  ribbon  cables,  and  you  leave 
the  8088  in  place.  Software  and  easily 
installed  device  drivers  activate  it. 
You  switch  to  the  standard  PC  mode 
with  a  program  called  PSLOW  and 
back  to  the  80286  mode  with  PFAST. 
Our  test  board  came  with  2-megabyte 
RAM,  but  it  is  also  available  with  only 
1  megabyte.  The  board  also  contains 
an  80287  math  coprocessor. 

Pfaster  286  supports  the  Lotus/In¬ 
tel/Microsoft  (LIM)  Extended  Memo¬ 
ry  Specification  (EMS)  and  comes  with 
a  RAM  disk  that  utilizes  the  extra  me¬ 
gabyte  of  memory  for  non-EMS  use. 

The  Pfaster  286  board  was  the  fast¬ 
est  in  many  of  the  tests,  but  the 
screen  I/O  seemed  jumpy  and  espe¬ 
cially  slow  with  programs  such  as 
Framework  II  that  write  directly  to 
the  video  memory.  The  Norton 
Sysinfo  results  were  inconsistent, 
ranging  from  6.1  to  8.4  in  the  PFAST 
mode. 

In  the  PFAST  mode,  Pfaster  286  uses 
motherboard  memory  for  caching, 
allowing  the  compile/link  bench¬ 
mark  to  outperform  an  8-MHz  IBM 
PC/AT  containing  a  high-speed  hard 
disk.  The  compile  time  was  much 
better  (51.74  seconds)  when  a  1-mega¬ 
byte  RAM  disk  was  used  to  hold  all  the 
necessary  files.  CHKDSK  revealed  that 
704K  RAM  was  available  after  the  1- 
megabyte  RAM  disk  was  defined  and 
the  8088  memory  was  set  aside  for 
caching. 

We  couldn't  convince  the  Brief  edi¬ 
tor  to  run  in  the  high-speed  mode — 
the  cursor  disappeared  and  charac¬ 
ters  were  lost  or  duplicated.  We  rec¬ 
ommend  this  board,  'which  seems 
well  implemented  and  versatile  de¬ 
spite  the  I/O  problem,  but  it's  expen¬ 
sive. 

PC  Turbo  286 

Orchid  Technology’s  PC  Turbo  286 
uses  an  80286  microprocessor  run- 
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ning  at  8  MHz  with  no  wait  states. 
The  board  takes  up  a  full  slot  but  re¬ 
quires  no  extra  cables  or  chip  remov¬ 
al.  You  activate  this  board  with  soft¬ 
ware  device  drivers  that  are  easy  to 
install  and  customize.  The  installa¬ 
tion  software  carefully  changes  your 
existing  AUTOEXEC.BAT  file  and 
doesn’t  disturb  any  commands, 
paths,  or  prompt  commands.  We 
found  the  software  installation  pro¬ 
cedures  to  be  very  professional;  they 
prompted  for  parameters  and  al¬ 
ways  explained  the  available  options. 
The  test  board  came  with  1-megabyte 
ram,  but  it  is  available  with  an  addi¬ 
tional  1  megabyte  on  a  daughter¬ 
board.  It  fully  supports  the  LIM  EMS. 

PC  Turbo  286 's  benchmark  times 
were  very  consistent,  and  all  test  soft¬ 
ware  per  formed  quite  well.  Screen 
I/O  was  extremely  fast,  and  there 
were  no  noticeable  differences  when 
we  used  the  Turbo  mode.  An  installa¬ 
tion  option  allows  an  increased 
screen  I/O  speed  for  nonflicker 
graphics  boards — for  example,  our 
test  PC's  STB  board.  With  the  software 
installed  for  the  flicker  option,  we 


found  the  resulting  screen  I/O  was  a 
little  slower  and  somewhat  jumpy, 
but  PC  Turbo  286  performed  much 
better  than  did  Pfaster  286. 

Fixed-disk  caching  (floppies,  too, 
with  a  command-line  option)  takes 
advantage  of  the  memory  on  the 
motherboard  while  the  board  is  op¬ 
erating  in  the  Turbo  mode.  RAM  disks 
and  spoolers  in  the  standard  PC 
memory  are  also  accessible  in  the 
Turbo  mode. 

PC  Turbo  286  supports  the  80287 
math  coprocessor,  but  our  evaluation 
unit  didn’t  have  one.  The  board  per¬ 
formed  flawlessly  with  all  hardware 
in  the  test  machine. 

Orchid  Technology’s  unit  can  also 
run  in  the  PC/AT  as  a  true  dual  pro¬ 
cessor.  Two  PC  Turbo  boards  in  a  PC 
or  XT  can  provide  the  same  effect. 
The  software  to  provide  access  to  the 
other  boards  was  in  development 
and  not  available  (but  was  document¬ 
ed)  for  our  tests,  however. 

Orchid  Technology’s  documenta¬ 
tion  is  complete  and  helpful,  which  is 
surprising  because  we  had  a  beta  ver¬ 
sion  of  the  board.  The  documentation 


PC  Turbo  286 

QuadSprint 

Orchid  Technology 

Quadram 

47790  Westinghouse  Dr. 

4355  International  Blvd. 

Fremont,  CA  94539 

Norcross,  GA  30093 

(415)  490-8586 

(404)  923-6666 

Price:  $1,195  (1  megabyte) 

Price:  $645 

$1,480  (2  megabytes) 

Reader  Service  Number  45 

Reader  Service  Number  48 

SpeedPac  286 

PC  Turbocharger 

Victor  Technology 

Univation  Inc. 

980  El  Pueblo  Rd. 

1037  N.  Fair  Oaks  Ave. 

Scotts  Valley,  CA  95066 

Sunnyvale,  CA  94089 

(408)  438-6680 

(408)  745-0180 

Price:  $595 

Price:  $595  (128K) 

$795  (640K) 

Reader  Service  Number  49 

Reader  Service  Number  46 

286  Speed  Pack 

Classic  Technology  Corp. 

Pfaster  286 

2090  Concourse  Dr. 

Phoenix  Computer  Products  Corp. 

San  Jose,  CA  95131 

320  Norwood  Park  Sbuth 

(408)  434-9333 

Norwood,  MA  02062 

Price:  $995 

(617)  762-5030 

Price:  $1,495  (1  megabyte) 

$1,895  (2-megabyte  unit 
evaluated) 

$2,395  (2  megabytes  w/ViaNet 
LAN  software) 

Reader  Service  Number  47 

Reader  Service  Number  50 

covers  jumper  settings  to  change  I/O 
addresses  and  interrupt  request  lines 
to  minimize  chances  of  unresolved 
hardware  conflicts. 

Try  It,  You  11  Like  It 

Using  these  boards,  we  found  micro¬ 
processor  speed  increases  from  two 
to  more  than  eight  times  the  speed  of 
the  8088  in  a  stock  PC  but  at  best  about 
a  five  times'  increase  in  actual 
throughput.  Standard  I/O  devices 
provide  the  primary  bottleneck.  Be¬ 
cause  of  software  enhancements, 
such  as  cache  and  RAM-disk  pro¬ 
grams  that  come  with  most  of  the 
boards,  you  can  achieve  the  actual 
throughput  of  an  IBM  PC/AT  and 
greatly  surpass  the  standard  PC.  We 
see  these  turbo  boards  as  serious  al¬ 
ternatives  to  an  AT  because  they  pro¬ 
vide  the  desired  performance  in¬ 
crease  and  save  money — it’s  much 
cheaper  to  upgrade  your  old  PC  or  XT 
with  one  of  these  boards  than  to  buy 
an  AT,  even  one  of  the  new,  cheap 
AT  clones. 

We  tested  two  categories  of 
boards — Intel  8086-based  (or  NEC  V30 
compatible)  and  Intel  80286-based. 
The  first  group  benchmarked  very 
closely,  and  choosing  a  winner  was 
difficult. 

All  the  installed  80286  boards  per¬ 
formed  consistently  faster  than  a 
stock  IBM  PC/AT.  For  raw  perfor¬ 
mance  and  overall  throughput  and 
compatibility,  Orchid  Technology’s 
PC  Turbo  286  was  a  clear  winner,  far 
surpassing  the  standard  IBM  PC/AT’s 
performance.  It  has  lightning-fast 
screen  I/O  and  a  reasonable  price  for 
an  AT  alternative,  and  it  fully  sup¬ 
ports  EMS.  If  price  is  the  primary  con¬ 
sideration,  look  at  Victor  Technolo¬ 
gy’s  SpeedPac  286.  It  can  attain  the 
speed  of  the  AT  without  expensive 
memory  replacement — its  perfor- 
With  public-domain  cache  and  RAM- 
disk  software,  this  board  could  pro¬ 
vide  the  throughput  you're  looking 
for. 
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Listing  One  (continued  from  July) 


FDB  HERE- 6 
LDX  SP 
LDA  SP0,X 
CCMA 

STA  SP0,X 
INCX 

LDA  SP0,X 
CCMA 

STA  SP0,X 
JMP  NEXT 


Link  to  HERE 


LDA  SP0,X 
INCX 

STA  LOAD +2 
INCX 

IDA  SP0,X 
INCX 
STX  SP 
CLRX 
JSR  LOAD 
JMP  NEXT 


drop  high  data  byte 
and  move  low  byte 


FCB  2 
FCC  '1+  ' 

FD  .  NOT3-6 
ONEP  LD/C  SP 
INCX 

LDA  SP0,X 
ADD  #1 
STA  SP0,X 
LDX  SP 
LDA  SP0,X 
ADC  #0 
STA  SP0,X 
JMP  NEXT 

FCB  3 
FCC  'HID' 

FDB  ONEP-6 
HLD3  LDA  #HLD 

DOUSE  ADD  #USER 
LDX  SP 
DECX 

STA  SP0,X 

CLRA 

DECX 

STA  SP0,X 
STX  SP 
JMP  NEXT 

FCB  5 
FCC  'STA' 

FDB  HLD3-6 
STA5  IDA  # STATE 
BRA  DOUSE 

it 

FCB  7 
FCC  'CON' 

FDB  STA5-6 
CON7  LDA  # CONTEXT 
BRA  DOUSE 

* 

FCB  7 
FCC  'CUR' 

FDB  CON7-6 
CUR7  LDA  # CURRENT 
BRA  DOUSE 

* 

FCB  5 
FCC  'FOR' 

FDB  CUR7-6 
FOR5  IDA  #  FORTH 
BRA  DOUSE 

FCB-  1 
FCC  ' !  ' 

FDB  FOR5-6 
STO  IDX  SP 

LDA  SP0,X 
INCX 

STA  LOAD+1 
LDA  SP0,X 
INCX 

STA  LOAD +2 
IDA  SP0,X 
INCX 
STX  SP 
CLRX 
JSR  LOAD 
LDX  SP 
LDA  SP0,X 
INCX 
STX  SP 
LDX  #1 
JSR  LOAD 
JMP  NEXT 

★ 

FCB  2 
FCC  'C!  ' 

FDB  STO- 6 
CSTO  LDX  SP 

LDA  SP0,X 
INCX 

STA  LOAD+1 


Link  to  NOT 


point  to  low  byte 


now  the  high  byte 


link  to  1+ 

(fall  through  to  DOUSE) 

Does  the  common  part  of  the 
execution  of  a  user  variable 


link  to  HID 


link  to  STATE 


link  to  CONTEXT 


link  to  CURRENT 


link  to  FORTH 
move  addr  to  Load 


now  move  data  to  addr 
high  byte  first 


now  the  low  byte 


link  to  ! 

move  addr  to  Load 


FCB  1 
FCC  ' ,  ' 

FDB  CSTO-6 
CCMA  LDA  DP 

STA  LOAD+1 
IDA  DP+1 
STA  LOAD +2 
LDX  SP 
IDA  SP0,X 
INCX 
STX  SP 
CLRX 
JSR  LOAD 
IDX  SP 
LDA  SP0,X 
INCX 
STX  SP 
LDX  #1 
JSR  LOAD 
LDA  #2 

INCDP  ADD  DP+1 
STA  DP+1 
LDA  DP 
ADC  #0 
STA  DP 
JMP  NEXT 

★ 

FCB  2 
FCC  'C,  ' 
FDB  COMA-6 
CCOMA  IDA  DP 

STA  LOAD+1 
IDA  DP+1 
STA  LOAD+2 
LDX  SP 
INCX 

LDA  SP0,X 
INCX 
STX  SP 
CLRX 
JSR  LOAD 
LDA  #1 
BRA  INCDP 

* 

FCB  3 
FCC  'DUP' 
FDB  CCCMA-6 
DUP 3  LDX  SP 

IDA  SP0,X 

DECX 

DECX 

STA  SP0,X 
LDX  SP 
INCX 

LDA  SP0,X 

DECX 

DECX 

STA  SP0,X 
DECX 
STX  SP 
JMP  NEXT 

* 

FCB  2 
FCC  '+!  ' 
FDB  DUP3-6 
PLSTO  LDX  SP 

LDA  SP0,X 
INCX 

STA  LOAD+1 
STA  GET+1 
LDA  SP0,X 
INCX 

STA  LOAD+2 
STA  GET+2 
STX  SP 
IDX  #1 
JSR  GET 
IDX  SP 
INCX 

ADD  SP0,X 
IDX  #1 
JSR  LOAD 


link  to  C! 
move  DP  to  Load 


move  data  to  DP 
high  byte 


low  byte 


move  data  to  DP 
drop  high  byte 
get  low  byte 


bump  DP  by  1 


get  high  byte 

and  bump  SP  to  point  to  new  location 

then  store  it 

get  low  byte 

bump  SP  for  it  too 

and  store  it 
update  SP 


link  to  DUP 

move  Addr  to  Load  and  Get 


get  low  byte  of  addr  data 
get  low  byte  of  number 


and  save  it  back 
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Listing  On©  (listing  continued) 

CLRX 

The  same  for  the  high  byte 

FDB  QIMM 

JSR  GET 

FDB  NOT3 

LDX  SP 

FDB  ZBRAN 

ADC  SP0,X 

FDB  $0010 

CLRX 

FDB  STA5 

JSR  LOAD 

FDB  FTCH 

INC  SP 

update  SP 

FDB  ZBRAN 

INC  SP 

FDB  $0008 

JMP  NEXT 

FDB  COMA 

★ 

FDB  BRAN 

FCB  6 

LATEST 

FDB  $FFE6 

FCC  'LAT' 

FDB  EXE7 

FDB  PLSTO-6 

link  to  + ! 

FDB  BRAN 

LAT6 

JMP  DOCOL 

FDB  $FFE0 

FDB  CUR7 

FDB  HERE 

FDB  FTCH 

FDB  NUM8 

FDB  FTCH 

FDB  ZBRAN 

FDB  EXIT 

FDB  $0014 

★ 

FDB  STA5 

FCB  5 

ALLOT 

FDB  FTCH 

FCC  'ALL* 

FDB  ZBRAN 

FDB  LAT6-6 

link  to  LATEST 

FDB  $FFD0 

ALL5 

JMP  DOCOL 

FDB  COMP 

FDB  DP 2 

FDB  LIT3 

FDB  PLSTO 

FDB  COMA 

FDB  EXIT 

FDB  BRAN 

* 

FDB  $FFC6 

FCB  3 

LIT 

FDB  QUES 

FCC  'LIT' 

FDB  BRAN 

FDB  ALL5-6 

FDB  $FFBA 

LIT3 

LDA  IP 

move  IP  to  Get 

* 

STA  GET+1 

* 

POWER  ON 

RESET  ROUTINE 

IDA  IP+1 

* 

STA  GET+2 

FCB  4 

COLD 

LDX  #1 

move  low  byte  to  stack 

FCC  'COL' 

JSR  GET 

FDB  LIT3-6 

link  to  LIT 

LDX  SP 

* 

DECX 

COLD 

BSET3  $05 

STA  SP0,X 

BSET3  PUT 

STX  SP 

IDX  #$3F 

Move  the  default  RAM  data 

CLRX 

and  then  the  high  byte 

SDAT 

LDA  ROM,  X 

JSR  GET 

STA  0,X 

IDX  SP 

DECX  - 

DECX 

CPX  #$20 

STA  SP0,X 

BNE  SDAT 

STX  SP 

LDX  #$80 

Move  the  self-modifying  code 

IDA  #2 

now  bump  IP 

SREPT 

LDA  ROM,  X 

to  its  executable  location 

ADD  IP+1 

STA  0,X 

(done  in  two  steps  to  avoid  the 

STA  IP+1 

INCX 

CPUs  stack:  40-7F) 

CLRA 

BNE  SREPT 

ADC  IP 

CLRX 

STA  IP 

SREP2 

LDA  ROM+$100,X 

(moving  200  HEX  bytes) 

JMP  NEXT 

STA  $100, X 

* 

DECX 

QIMM 

LDX  SP 

Tests  for  IMMEDIATE 

BNE  SREP2 

INCX 

using  count  byte 

LDA  SP0,X 

from  <FIND> 

* 

Calculate  the  HIGH 

and  LOW  BYTES  of  OUTER 

TSTA 

* 

BMI  QID 

HO 

EQU  OUTER/$100*$100 

CLRA 

LO 

EQU  OUTER-HO 

BRA  QSKIP 

HOI 

EQU  OUTER/$100 

QID 

IDA  #$FF 

* 

QSKIP 

STA  SP0,X 

LDA  #LO 

Load  the  default 

DECX 

STA  START+1 

Outer  Interpreter 

STA  SP0,X 

LDA  #H01 

into  START 

JMP  NEXT 

STA  START 

* 

* 

Calculate  the  HIGH 

and  LCW  BYTES  of  Latest  entry 

MESS 

FCB  67 

* 

FCC  'RAFOS 

HCR 

EQU  LATEST/$100*$100  j 

FCC  'FORTH 

LCR 

EQU  LATEST-HCR 

FCC  'VI. O' 

H1CR 

EQU  LATEST/$100 

FCB  CR 

IDA  #H1CR 

Initialize  FORTH 

FCB  LF 

STA  USER+FORTH 

FCC  'A  TEAM 

ROSSBY  PRODUCTION' 

LDA  #LCR 

* 

STA  USER+FORTH+1 

FCB  CR 

* 

FCB  LF 

* 

FCC  ' (C)  EVERETT  CARTER  1986' 

* 

Calculate  the  HIGH 

and  LOW  BYTES  of  MESS 

LOK 

FCB  3 

H 

EQU  MESS/$100*$100 

OK 

FCC  '  OK' 

The  FORTH  prompt 

L 

EQU  MESS-H 

★ 

HI 

EQU  MESS/ $100 

* 

DEFAULT  OUTER  INTERPRETER 

CLRX 

★ 

LDA  #L 

Push  start  up  message 

★ 

DECX 

OUTER 

FDB  COU5 

STA  SP0,X 

FDB  TYPE 

LDA  #H1 

FDB  INLINE 

DECX 

FDB  DFND 

STA  SP0,X 

FDB  ZBRAN 

STX  SP 

Initialize  Stack  Pointer 

FDB  $001E 
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FORTH  AT  SEA 


Listing  One  (listing  continued) 

WARM  LDA  #$80  Initialize  input  terminators 


WARM  LDA  #$80 

STA  TIB+$7E 

STA  TIB+$7F 

CLR  USER+STATE 

CLR  USER+STATE+1 

CLR  RP 

JSR  CRLF 

LDA  START 

STA  IP 

IDA  START+1 

STA  IP+1 

JMP  NEXT 

★ 

* 

FCB  4 
FCC  'SWA' 

FDB  COID-6 
SWAP  IDX  SP 

LDA  SP0,X 
INCX 
STA  PH 
LDA  SP0,X 
INCX 
STA  PL 
LDA  SP0,X 
INCX 
STA  QH 
LDA  SP0,X 
STA  QL 
IDA  PL 
STA  SP0,X 
IDA  PH 
DECX 

STA  SP0,X 
IDA  QL 
DECX 

STA  SP0,X 
IDA  QH 
DECX 

STA  SP0,X 
JMP  NEXT 

* 

FCB  3 
FCC  ' SP ! ' 

FDB  SWAP-6 
SPSTO  CLR  SP 

JMP  NEXT 


Put  system  in  EXECUTION  state 
Initialize  Return  Stack  pointer 
Load  the  IP 


link  to  COID 


OUTCHAR  EQU  PUTC 
STA  ATEMP 
STX  XTEMP 
LDA  #9 
STA  COUNT 
CLRX 
CLC 
SEI 

BRA  PUTC 2 
PUTC  5  ROR  CHAR 

PUTC2  BCC  PUTC3 

BSET3  PUT 
BRA  PUTC 4 
PUTC3  BCLR3  PUT 

BRA  PUTC4 

PUTC4  JSR  DELAY,  X 

DEC  COUNT 
BNE  PUTC5 
BSET2  PUT 
BSET3  PUT 
CLI 

BSR  DELAY 
IDX  XTEMP 
IDA  ATEMP 
RTS 


WAIT - PRECISE  DELAY 

A  AND  X  ARE  ZERO  AT  EXIT. 


link  to  SWAP 


SERIAL  I/O  ROUTINES 


WAIT  LDA  #1 
DELAY  EQU  WAIT 

AND  fill 
TAX 

LDX  DELAYS,  X 
LDA  #$F9 
DEL3  ADD  #$08 

DEL2  DECA 

BNE  DEL2 
TSTX 

BSET1  PUT 
DECX 
BNE  DEL3 
LDA  #0 
RTS 

* 

DELAYS  FCB  $20 

FCB  $08 
FCB  $01 


ADJUST  FOR  FIRST  TIME 


300  BAUD 
1200  BAUD 
9600  BAUD 


GETCHAR/GETC - GET  A  CHARACTER  FRCM  THE  TERMINAL 

A  GETS  THE  CHARACTER  TYPED,  X  IS  UNCHANGED 


IDA  #CR 
JSR  OUTCHAR 
IDA  #LF 
JSR  OUTCHAR 
RTS 


GETCHAR  EQU  GETC 
LDA  #8 


STA  COUNT 

CLI 

SEI 

BRSET2  PUT,GETC4 
IDA  PUT 
AND  # ! 11 
TAX 

LDX  DELAYS,  X 
LDA  #4 
DECA 

BNE  GETC 2 

TSTA 

DECX 

BNE  GETC3 

BRSET2  PUT,GETC4 

TST  ,X 

TST  ,X 

BSR  DELAY 

BRCLR2  PUT,GETC6 

TST  ,X 

ROR  CHAR 

DEC  COUNT 

BNE  GETC 7 

CLI 

BSR  DELAY 
IDA  CHAR 
AND  #$7F 
IDX  XTEMP 
RTS 


load  Baud  delay 


link  to  SP! 


link  to  CR 


FCB  2 
FCC  'CR  ' 
FDB  SPSTO-6 

CR2  BSR  CRLF 
JMP  NEXT 

* 

FCB  6 
FCC  'CRE' 
FDB  CR2-6 

CRE6  JMP  DOCOL 
FDB  BL2 
FDB  WORD 
FDB  LIT3 
FDB  #04 
FDB  ALL5 
FDB  LAT6 
FDB  COMA 
FDB  CUR7 
FDB  FTCH 
FDB  STO 
FDB  EXIT 


************************************************************* 


INTERRUPT  VECTORS 


Mask  the  eighth  bit. 


OUTCHAR/PUTC - PRINT  A  ON  THE  TERMINAL 


X  AND  A  UNCHANGED 


ORG 

MEMSIZ-10 

START  OF  VECTORS 

FDB 

WTIME 

TIMER  IRQ  VECTOR  FROM  WAIT  STATE 

FDB 

WTIME+3 

ALTERNATE  TIMER  VECTOR 

FDB 

WTIME+6 

IRQ  VECTOR. 

FDB 

WARM 

SWI  TO  FORTH  INITIALIZATION  POINT 

FDB 

COLD 

POWER  ON  VECTOR 

END 

End  Listing 
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LETTERS 


Listing  One  (Text  begins  on  page  10.) 

Program  Square root; 

( 

Squareroot  algorithm  £  testprogram;  DDJ  March  1986,  p.122 

Features:  -  sqrt  routine  in  68000  machine  language; 

-  long  integer  loopcount; 

} 

const  (  Iteration  count  for  test  loop  } 

NNR  -  6E4;  (  real,  for  printing  of  statistics  ) 

NNS  -  '60000';  {  string,  for  assignment  to  long  integer  ) 

type  long  -  record 

low, high  :  integer; 
end; 

var  finished  :  boolean;  (  flag  for  loop  ) 

number,  limit  :  long;  {  loop  count,  loop  limit  ) 

sqrrt,  i  square  root  result  ) 

sqrrto,  (  last  displayed  square  root  ) 

tl,t2  :  integer; {  parameters  for  Bystera  time  ) 

timel,  time2  :  real;  (  start,  end  time  ) 

(  -  ROUTINES  FOR  LONG  (32-BIT)  INTEGER  SUPPORT  -  ) 

procedure  lg_clr(var  ltlong);  external; 

1  Clears  long  integer  1  ) 

procedure  lg_asn_DU ( s : string;  var  l:long);  external; 

{  Assigns  the  unsigned  decimal  string  s  to  the  long  integer  1  ) 

procedure  lg_incl (var  l:long);  external; 

(  Increments  long  integer  1  by  1  ) 

procedure  lg_grt (a,b: long;  var  flag: boolean) ;  external; 

(  Compares  long  integers  a  and  b  and  assign  result  to  flag  ) 

{  -  SQUARE R JOT  ROUTINE  ) 

procedure  sqrt (number : long;  var  result : integer) ;  external; 

(  Calculates  square  root  of  'number'  and  returns  it  in  'result'  ) 

begin  (  main  ) 

sqrrto  :-  100; 

lg_clr (number) ;  {  number  :-  0  | 

lg_asn_DU (NNS, limit) ;  (limit  NNS  ) 
finished  :-  false; 

write ( 'Start. . . ' ) ; 

time(tl,t2);  timel  t2;  (  get  start  time  ) 

while  not  finished  do  (  calculate  sqrt (number)  ) 
begin 

sqrt (number, sqrrt) ; 

( 

if  sqrrt  <>  sqrrto 
then  begin 

write  ('Number  -  ', number .high: 6, '  |  ', number . low: 6) ; 

writeln('  -  Sqrt  -  ', sqrrt: 4); 

sqrrto  sqrrt; 
end; 

lg_incl (number) ;  (  number  :-  number  +  1  } 

lg_grt (number, limit, finished) ;  (  finished  :-  (number  >  limit)  ) 

end; 

time (tl, t2 ) ;  time2  t2;  (  get  end  time  ) 

writeln (' finished  !');  writeln; 

writeln( 'Time:  ' , (time2 -timel) /60, '  seconds') 


End  Listing  One 


Listing  Two 


Squareroot  algorithm;  DDJ  March  1986,  p.l 22 
68000  assembly  language  version 

Features:  -  equivalent  to  compiler-generated  code; 
procedure  sqrt (number : long;  var  result : integer) ; 

■  Calculates  integer  square  root  of  'number*  and  returns  it  in  'result' 
*  Register  usage: 


DO  :  word  register 
D1  :  number 
D2  :  guessl 
D3  :  guess2 
D4  :  error 


A0  :  parameter  stack  pointer 
A1  :  scratch  register 


;2  words  of  parameters 


proc  sqrt, 2  ;2  words  of  ] 

*  Get  parameters  from  stack 

raove.l  (sp)+,a0  ;get  return  address 

move.w  2(sp),al  ;get  “number 

move . 1  (al),dl  ;get  number 

*  bra  Q15  ; -  for  timing  only 

beq  Q8  ;if  number-0,  skip 

*  Set  initial  values 

Q7  moveq  #l,d2  .-guessl  :-  1 


move.l  dl,d3 

Do  shifts  until  guessl  -  guess2 


; guessl  :-  1 

;guess2  :—  number 


50  •  Now 

51  • 

52  Qll 

53  Q13 


move.l 

d2,d0 

; guessl 

to  work  register 

asl .  1 

11,  dO 

.-guessl 

•  2 

cmp .  1 

d3,  dO 

; compare 

!  with  guess2 

bge 

Qll 

; branch 

if  guessl  *  2  >-  t 

asl.l 

11,  d2 

,-guessl 

:-  guessl  *  2 

asr  .1 

#1,  d3 

;guess2 

:-  guess2  /  2 

bra 

Q9 

Jo  divisions 

add .  1 

d3,d2 

.-guess  -. 

-  guessl  +  guess2 

asr .  1 

*l,d2 

; guessl 

:-  (guessl +guess2 

move.l 

dl,  dO 

; numbe  r 

to  work  register 

divs 

d2,d0 

.-  numbe  r 

/  guessl 

move .  w 

dO,  d3 

.-  guess2 

:-  number /guessl 

ext  .1 

d3 

; extend 

to  32  bits 

move.  1 

d2.d0 

.-  guessl 

to  work  register 

sub.  1 

d3,d0 

; guess 1- 

-guess2 

move.  1 

d0,d4 

; error  : 

-  guessl-guess2 

ble 

Q14 

;if  error  <-  0 

bra 

Q13 

.-loop  back  if  error  >  0 

move.  1 

d2,d0 

.-result 

guessl 

bra 

Q15 

moveq 

10,  dO 

; result 

:-  0 

result  £  return  to  caller 


(sp)  +,  al 
dO,  (al) 


“result 

.-store  result 


.-drop  “number 
; return  to  caller 


End  Listing  Two 


Listing  Three 


Squareroot  algorithm;  DDJ  March  1986,  p.122 
68000  assembly  language  version 
Features:  -  hand-optimized  machine  code; 

procedure  sqrt (number : integer;  var  result : integer) ; 

*  Calculates  square  root  of  'number'  and  returns  it  in  'result' 

*  Register  usage: 


DO  :  work  register,  error  A0  :  “result 

Di  :  number  Al  :  “number 

D2  :  guessl ,  result 
D3  :  guess2 

D4  :  temporary  storage  for  return  address 


.proc  sqrt, 2 
Get  parameters  from  stack 
moveq  #0,d2 


;2  words  of  parameters 

.-result  : -  0 - remove  for  timing 


(sp)+,d4  .-get  return  address 
(sp)+,a0  .-get  “result 


32  move.w  (sp)+, al 

33  move.l  (al) , dl 

34  * 

35  •  bra  Q1S  ; -  for  timing  only 

36  * 

37  beq  Q15 

38  • 

39  •  Set  initial  values 

40  • 

41  Q7  moveq  #l,d2 

42  move.l  dl,d3 

43  • 

44  •  Do  shifts  until  gue3Sl  -  guess2 

45  * 

46  Q9  asl.l  #l,d2 

47  cmp.l  d3,d2 

4  8  bge  Qll 

49  asr.l  #l,d3 

50  bra  Q9 

51  • 

52  Qll  asr.l  #l,d2 

53  • 

54  •  Now  do  divisions 

55  • 

56  Q13  add . 1  d3,d2 


Store  result  and  return  to 


.-get  “number 
.-get  number 


.-if  number-0,  then  result-0 


; guessl  :-  1 

;gueas2  :-  number 


.-guess)  :-  guessl  •  2 
; compare  with  gue ss2 
.-branch  if  guessl  *  2  >-  guoss2 
;guess2  :-  guess2  /  2 


.-adjust  guessl 


,-guessl  guessl  +  guess2 
,-guessl  :-  (guessl+guess2) /2 
;guess2  :—  number 
;guess2  :-  number  /  guessl 
.-extend  guess2  to  32  bits 
; guessl  to  work  register 
.-error  :-  guessl  -  guess2 
,-loop  back  if  error  >  0 


.•store  result 

.-move  return  address  to  adr-reg 
.-return  to  caller 

End  Listing  Three 
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Listing  Four 

(Listing  continued,  text  begins  on  page  lO.) 

1  * 

2  •  Squareroot  algorithm;  DDJ  November  1985,  p.88 
4  *  68000  assembly  language 

6  •  procedure  sqrt (number : long;  var  result : integer) ; 

8  *  Calculates  the  integer  squareroot  of  'number*  and  returns  it  in  'result' 


Listing  Five 


Register  usage 


number 
error  term 
estimate 
corrector  term 
loop  counter 


AO  :  scratch,  for  pointers 
A1  :  scratch,  for  pointers 


.proc  sqrt, 2 


move.w  6 (sp) , aO 

move.l  (a0),d0 


;2  words  of  parameters 


;get  “number 

;get  number  into  dO 


*  Calculate  squareroot 
sqrtl  asl.l  Il,d0 


•  •  Set  result  (  return  to  < 

exit  move.l  (sp)+,a0 

move.w  (sp) +, al 

i  move.w  d2, (al) 

addq.l  12, sp 

jmp  (aO) 


;set  loopcount, 16*2  -  32  bits 
.-clear  error  term 
.-clear  estimate 


.-get  2  leading  bits, 

.-one  at  a  time,  into 
.-the  error  term 

; estimate  •  2 

.-corrector  -  2  •  new  estimate 

.-branch  if  error  terra  <-  corrector 
.-otherwise,  add  low  bit  to  estimate 

,-and  calculate  new  error  term 

.-do  all  16  bit-pairs 


;get  return  address 
.-get  “result 

.-store  integer  result 
.-drop  “number 
.-return  to  caller 


move . b 

(pseudopc) +,d0 

*  dO  < —  distance 

subq.b 

11, regb  (regs) 

*  dec  b 

beq 

d  jnz2 

*  loop  count  expii 

ext  .w 

dO 

*  to  word 

ext  .1 

dO 

*  to  long 

add.l 

dO, pseudopc 

*  add  distance 

djnz2: 

NEXT 

jr: 

*  18  jr  e 

move . b 

(pseudopc)  f,  dO 

*  dO  < —  distance 

ext  .w 

dO 

*  to  word 

ext  .1 

dO 

*  to  long 

add.l 

dO, pseudopc 

*  add  distance 

NEXT 

jrnz: 

*  20  jr  nz,e 

move.b 

(pseudopc) +,d0 

*  dO  < —  distance 

btst 

16,  regf 

*  if  Z  bit  set 

bne 

jrnz2 

*  then  no  branch 

ext  .w 

dO 

*  to  word 

ext  .1 

dO 

*  to  long 

add.l 

dO, pseudopc 

*  add  distance 

jrnz2: 

NEXT 

jrz: 

*  28  jr  z,e 

move.b 

(pseudopc) +, dO 

*  dO  < —  distance 

btst 

16,  regf 

*  if  Z  bit  reset 

beq 

jrz2 

*  then  no  branch 

ext  .w 

dO 

*  to  word 

ext  .1 

dO 

*  to  long 

add.l 

dO, pseudopc 

*  add  distance 

jrz2: 

NEXT 

jrnc: 

*  30  jr  nc,e 

move.b 

(pseudopc) +,d0 

*  dO  < —  distance 

btst 

#0, regf 

*  if  C  bit  set 

bne 

jrnc2 

*  then  no  branch 

ext  .w 

dO 

*  to  word 

ext  .1 

dO 

*  to  long 

add.l 

dO, pseudopc 

*  add  distance 

End  Listing  Four 


(continued  on  page  60) 
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Listing  Five  (Listing  continued,  text  begii 


jrnc2: 

24 

else 

NEXT 

25 

( 

jrc: 

*  38  jr  c,e 

26 

x  =  xl; 

move.b 

(pseudopc) +,  dO 

*  dO  < —  distance 

27 

y  -  yi; 

btst 

V0, regf 

*  if  C  bit  reset 

28 

xend  =  x2; 

beq 

jrc2 

*  then  no  branch 

29 

dy  =  y2  -  yl; 

ext .  w 

dO 

■  to  word 

30 

) 

ext .  1 

dO 

*  to  long 

31 

incl  =  dy  «  1; 

add.l 

dO, pseudopc 

*  add  distance 

32 

inc2  =  (dy  -  dx)  «  1; 

jrc2: 

33 

inc3  =  (dy  +  dx)  «  1; 

NEXT 

34 

d  -  (dy  >=  0)  ?  incl  - 

End  Listing  Five 


Listing  Six 

1  /*  c_draw.c  * /  /*  jnm  5-27-86  rev.l  */ 

2 

3  /*  line  drawing  routine  using  Bresenham's  algorithm.  */ 


c_draw  (xl,  yl,  x2,  y2,  color) 
lnt  xl,  yl,  x2,  y2,  color; 


pcvwd  (y,  x,  colo 
x++; 

if  (d  >=  0) 

{ 

if  (dy  <-  0) 
d  +“  incl; 
else 
{ 

y++; 

d  +=  inc2; 

) 


/*  or  whatever  point  plotting 
/*  function  you  have  handy... 


int  incl,  inc2,  inc3,  xend,  yend; 
int  d,  x,  y,  dx,  dy; 

dx  =  abs  (x2  -  xl) ; 
dy  -  abs  (y2  -  yl); 
if  (dy  <=  dx) 

i  ( 

if  (xl  >  x2) 

I 

x  =  x2; 
y  =  y2; 
xend  =  xl; 
dy  =  yl  -  y2; 


if  (dy  >=  0) 
d  +“  incl; 
else 
{ 

y— ; 

d  +=  inc3; 
) 


else 

( 

if  (yl  >  y2) 

( 

y  -  y2; 
x  =  x2; 
yend  -  yl; 
dx  *  xl  -  x2; 


y  -  yi; 

x  =  xl; 
yend  =  y2 
dx  -  x2  -  xl; 

) 

incl  =  dx  «  1; 

inc2  *■  (dx  -  dy)  «  1; 

inc3  =  (dx  +  dy)  «  1; 

d  -  (dx  >-=  0)  ?  incl  -  dy:incl  +  dy; 

while  (y  <  yend) 

( 

pcvwd  (y,  x,  color) ; 

y+  +  ; 

if  (d  >=  0) 

1 

if  (dx  <=  0) 
d  +=  incl; 
else 
{ 


else 

i 

if  (dx  >-  0) 
d  +=  incl; 
else 
{ 


pcvwd  (y,  x,  color) ; 

} 


End  Listings 
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C  CHEST 


Listing  One  (Text  begins  on  page  14.) 


Listing  1  —  dtree. c 


1  # include  <stdio.h> 

2  # include  <ctype.h> 

3  # Include  <process.h> 

4  I include  <mydir.h> 

5  linclude  <slgnal.h> 

6 


/•  needed  by  spawn  () 
/*  needed  by  dlr() 

/"  needed  by  signal  () 


WHEREIS  and  DTREE 

A  general-purpose  directory  traversal  program.  If  invoked  with  name 
"wherels"  it  searches  for  a  file  in  the  directory  system.  If  invoked 
with  "dtreo"  it  does  the  above  and  can  also  print  the  directory  tree  < 
1  executes  a  program  in  each  directory.  See  usage  ()  and  wusageO  below 
1  for  more  details  about  the  command-line  syntax. 


else  1 f (  name  -  strrchr (dname,  '/')  ) 
name++; 

else 

name  -  dname; 
prlntf(  M%s\n“,  name  ); 


l  execute (  dname 
i  char  * dname; 
i  ( 

/* 


(C)  1986  Allen  I.  Holub.  All  rights  reserved. 


Execute  the  command  specified  on  the  command  line  from 
the  directory  we're  now  visiting.  This  routine  changes 
the  current  directory  but  doesn't  put  it  back. 

The  Args  vector  must  point  at  the  command  array. 


'  extern  DIRECTORY 
i  extern  void 
extern  void 
!  extern  char 


*mk_dir(  int  ); 
del_dlr (  DIRECTORY*  ); 
dir  (  char*,  DIRECTORY* 
•strrchr (  char*,  int  ); 


1 f (  Args  ) 

< 

chdlr(  dname  ); 

if(  spawnvp (PJKAIT,  *Args,  Args)  —  -1  ) 
perror (*Args) ; 


These  IBM  graphics  (box  drawing)  characters  are  used  only  if  the 
output  stream  is  stdout  and  isattyO  is  true  (it  will  be  false  if 
stdout  is  redirected) . 


T_RIGHT  + - 

\303  | 


VERT  |  (dash) 

\263  |  \304 


static  char  *Graph_chars( |  -  {  "\263“,  "\300\304\304\304\304\304" 

"\303\304\304\304\304\304" 


static  char  "Norm  chars (]  -  (  "+ - ",  "t - "  ); 

static  char  **Cset  -  Norm_chars; 


Idefine  VERT  Cset(O) 
I define  ELL  Cset(l) 
•define  T_RIGHT  Cset[2) 


Idefine  DSIZE  255 

static  char  Startdir (DSIZE+1 ] ;  /*  The  cwd  when  the  program  started 

static  char  Map[  64/8  );  /*  Bitmap  for  64  bits.  If  the 

/*  directory  tree  is  deeper  than 
/*  this,  we're  in  trouble. 

static  char  “Args  -  NULL;  /*  Thing  to  execute,  pass  to  spawnv 

static  int  Short_pname  -  0;  /•  Use  short  pathnames 

static  int  Draw  »  0;  /•  Draw  directory  tree 

static  char  ‘Flndfile  -  NULL;  /*  File  for  which  we're  searching 


bitmap  routines: 

testbit  (x)  Evaluates  TRUE  if  bit  x  is  set. 

setbut  (x,val)  Set  bit  x  if  val  is  TRUE,  else  clear  it. 


find(  dname  ) 


Look  for  the  Findflle  file  in  dname.  If  it's  there,  print 
the  full  path  and  file  names  and  return  1,  else  return  0. 


static  char 

char 

int 

int 

DIRECTORY 


pathname (DSIZE] ; 
*  *vects; 


sprir;tf(  pathname,  "%s/%s",  dname,  Flndfile  ); 

if (  ! (dp  -  mkdir (  64  ) )  ) 

{ 

printf  ("dtree:  Out  of  memory\n"); 
return  0; 

) 


dp->files  -  1; 
dp->sort  -  1; 
dp->path  -  1; 
dlr(  pathname,  dp  ); 


/*  Get  files  only 
/*  sort  the  list 

/*  and  include  the  full  path  name 
/•  Fill  the  DIRECTORY  structure 


vects  -  (char  **)  dp->dirv;  /* 
count  -  rval  -  dp->n files; 
while (  — count  >-  0  ) 

printf  (  "%s\n",  *vects++  ); 

del_dir(  dp  ) ; 
return  rval; 


. . .  and  print  it. 


•define  testbit (x)  (  Map(x  »  3]  4  (1  «  (x  4  0x07))  ) 


static  setblt (  c,  val  ) 
'  int  c,  val; 


static  prnt (  dname,  others  ) 


if  (  val  ) 

Map( c  »  3 |  |-  1  «  (c  4  0x07)  ; 

else 

Map [c  »  3]  4-  -(1  «  (c  4  0x07))  ; 


/*  Does  a  recursive  traversal  of  the  directory  tree  rooted  at 

*  dname.  "others"  is  true  if  the  calling  routine  has  more 

•  subdirectories  to  print. 


I  pline(  depth,  terminate  ) 

{ 

/*  Print  all  the  spaces  and  vertical  bars  in  a  graphic 

i  •  representation  of  a  tree.  Does  nothing  if  Draw  if  FALSE. 

)  */ 


lf{  .'Draw  ) 

return; 


for(l  -  0;  1  <  depth-1  ;  i++  ) 
printf (testbit (i)  ?  "%s 


if(  terminate  ) 

printf ("\n") ; 


DIRECTORY  *dp; 

char  **vect 

int  count; 

static  int  depth 

if(  ** depth  44  Draw  ) 


pline(  depth,  0  ); 

printf ("%sM,  others  ?  T_RIGHT  :  ELL  ); 


if(  Findflle  ) 

1 


if(  find(  dname  )) 

execute (  dname  ); 


pname  (  dname  ) ; 
execute  (  dname  ) ; 


/*  If  -f  was  set  don't 
/*  execute  a  -e  command 
/*  unless  we've  found  the 
/*  file.  find()  prints  the 
/*  filename  if  it  exists. 


/*  else  print  the  directory 
/*  name  and  execute  the  cmd 


i  pname (  dname  ) 

1  char  * dname; 


Print  a  directory  name  with  or  without  the  full  path 
spec  (depending  on  whether  Short_pname  is  set. 


if (  ! (dp  -  mk_di r (  32  ) >  ) 

l 

printf ("dtree:  Out  of  memory\n") ; 
return; 

) 


1 f (  !Short_pname  II  (dname (0)  -» 
pame  -  dname; 


'/'  44  !dname [1 ] )  ) 


dp->dirs  -  1 
dp->sort  -  1 
dp->exp  -  1 


Get  subdirectories 
and  sort  than. 

expand  subdirectories  rather  than 
printing  their  names. 
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C  CHEST 

C  CHEST 

Listing  One 

(Listing  continued,  text  begins  on  page  14.) 

215  dp->path  -  1;  /•  and  Include  tho  full  path  name.  */ 

23  6  dlr(  dname,  dp  ); 

217 

218  vects  -  (char  ••)  dp->dirv;  /»  pointer  to  Hat  of  subdirs  */ 

219  count  -  dp->ndirs;  /*  number  of  subdirs.  */ 

220 

221  whi  le  (  —count  >-  0  )  /*  visit  the  subdirs,  one  */ 

222  {  /*  at  a  time,  the  setblt  •/ 

223  setbit (  depth,  count  );  /•  call  is  used  for  •/ 

224  prnt  (  *vects++,  count  );  /•  printing  the  tree.  •/ 

225  ) 

226 

227  if(  (others  )  /*  If  there  aren't  any  */ 

228  pllne(  depth,  1  );  /*  subdirs  in  the  parent,  */ 

229  /*  output  a  blank  line  */ 

230  del_dir (  dp  ) ; 

231  — depth; 

232  } 

233 

234  /* - •/ 

235 

236  char  "dodot (  str  ) 

237  char  "str; 

238  { 

239  /*  If  str  has  no  dots  in  it,  return  str,  else  get  the  pathname 

240  •  refered  to  by  str  (ie.  whatever  name  is  indicated  by 

241  •  .  or  ..  or  ../..  etc.)  and  return  a  pointer  to  that  string. 

242  ■/ 

243 

244  static  char  root_name(  DSI2C  ); 

245  char  *p; 

246 

247  if(  Istrchr (  str,  '.*  )  ) 

248  return  str; 

249 

250  if(  chdir(str)  | |  !getcwd(root  name,  DSIZE)  ) 

251  ( 

252  fprintf (stderr,  “Can’t  find  %s,  aborting\n",  str  ); 

253  exit  (  1  ); 

254  } 

255 

256  for(  p  -  root_name;  »p  ;  p++  )  /*  Map  the  name  from  DOS  */ 

257  (  ~  /*  style  to  UNIX  style  by  */• 

258  if(  *p  —  'W  )  /*  mapping  upper  to  lower  •/ 

259  *p  -  '/';  /*  case  and  changing  \  to  */ 

260  else  /*  /  */ 

261  *p  -  tolower(  *p  ); 

262  ) 

263 

264  chdlr(  Startdir  );  /*  Restore  the  original  */ 

265  return  root  name  ;  /*  working  directory  */ 

266  } 

267 

268  /* -  */ 

269 

270  doargs  (  argc,  argv  ) 

271  char  “argv; 

272  ( 

273  /»  Does  several  things.  First,  it  shifts  all  the  arguments  down 

274  *  one  notch,  overwriting  the  original  argv(O).  Next,  it 

275  *  puts  a  NULL  into  argv (argc-1 | ,  finally  it  processes  (and 

276  *  removes  from  argv)  all  command  line  switches.  Switch  processing 

277  *  stops  after  a  -e  is  encountered  (but  the  compression  continues) . 

278  *  Argc,  decremented  to  reflect  all  this  stuff,  is  returned. 

279 

280  •  We  can't  use  getargs()  in  the  program  because  -e  is 

281  *  position  dependant. 

282  •/ 

283 

284  register  int  nargc; 

285  register  char  “nargv; 

286 

287  llfdef  DEBUG 

288  char  “v  -  argv; 

289  int  c; 

290  lendlf 

291 

292  nargc  -  0  ; 

293  for(  nargv  -  argv++;  — argc  >  0;  argv++  ) 

294  { 

295  if(  “argv  !-  ||  Args  ) 

296  ( 

297  "nargvtt  -  *argv  ; 

298  nargc++; 

299  ) 

300  else 

301  ( 

302  switch(  argv[0)[l)  ) 

303  ( 

304  case  'e': 

305  Args  -  nargv  ; 

306  *nargv++  -  »++argv  ; 

307  nargc  ++; 

308  putenv (“CMDLINE-")  ; 

309  break; 

310 

311  case  • f ' :  Findfile  =  targv(0) [2) ;  break; 

312  case  's':  Short_pname  -  1;  break; 

313  case  'd':  Draw  -1;  break; 

314  default  :  usage (); 

315  I 

316  ) 

317  ) 

318 

Listing  One 

(Listing  continued,  text  begins  on  page  14.) 

319  "argv  -  NULL  ;  /*  Add  a  NULL  as  the  last  entry  */ 

320 

321  lifucf  DEBUG 

322  printf("New  argv  is:\r.“); 

323 

324  for{  c  -  nargc;  — c  >-  0  ;  v++) 

325  printf ("<%s>  0x%x\n",  *v,  *v  ); 

326 

327  printf  ("\nFindf lle-<%s>,  Short_pname-%d,  Draw-%d,  *Args“0x%x\n", 

328  Findfile,  Short  pname,  Draw,  "Args); 

329  lendlf 

330 

331  return  nargc  ; 

332  } 

333 

334  /• - */ 

335 

336  Idefine  E(x)  fprintf (stderr,  “%s\nM,  x  ) 

337  usage  () 

338  | 

339  E(  "\nUsage  is:  dtree  root  ( — s ]  [— d )  (-f<name>)  [-e  arg  arg  arg)\n“); 

340  E("-e  Execute  rest  of  cmd  line  from  each  directory"  ); 

341  E("-f<name>  Find  file  called  <name>“  ); 

342  E(“-s  Use  short  path  names"  ); 

343  E("-d  Draw  directory  tree"  ); 

344  E("\nEach  switch  must  be  in  its  own  argument  (-sd  is  illegal,"); 

345  EC'you  must  say  -s  -d)  .  If  -f  and  -e  are  both  specified,  the  command"); 

346  EC'is  only  executed  if  the  indicated  file  is  found."); 

347  exit  (1) ; 

348  ) 

349 

350  wusage() 

351  ( 

352  E(  "\nUsage  is:  whereis  <f 1 lename>\n“) ; 

353  E(  "Only  one  file  name  is  permitted,  though  wildcards  are  recognized"); 

364  E(  "by  whereis  Itself,  so  you  must  escape  these  from  the  shell  as  in:"); 

365  E(  "\twhereis  \"*.c\"  or  whereis  \\*.c"  ); 

356  exit  (1) ; 

357  ) 

358 

359  /• - */ 

360 

361  onlntr() 

362  | 

363  /‘Called  when  a  'C  is  encountered:  V 

364  chdlr(  Startdir  );  /*  Get  back  to  starting  directory  •/ 

365  exit(0);  /•  before  exiting.  */ 

366  ) 

367 

368  /• - */ 

369 

370  main(  argc,  argv  ) 

371  char  “argv; 

372  ( 

373  /*  If  the  program  is  invoked  under  the  name  "whereis"  it 

374  *  treats  the  command  line:  whereis  <fname> 

375  *  as  if  you  had  said:  dtree  /  -f<fname> 

376  */ 

377 

378  reargv(  targe,  targv  );  /*  Redo  arg  list  if  running  under  shell  */ 

379 

380  if (  !strcmp(*argv,  "whereis")  ) 

381  ( 

382  if(  argc  !-  2  1 1  argv(l) (0)  —  '-'  ) 

363  wusage  () ; 

384 

335  Findfile  -  argv(l);  /*  Search  for  a  file.  V 

386  argc  -  0;  /*  Force  search  to  begin  at  /  */ 

387  ) 

388  else 

389  ( 

390  argc  -  doargs  (  argc,  argv  ); 

391  /*  argv (0J  (1)  (2)  ...  •/ 

392  if(  Args  tt  argc  <  2  )  /*  pathname  cmd  args  ...  */ 

393  usage  (); 

394  ) 

395 

396 

397  Cset  -  isatty (fileno(stdout) )  ?  Graph_chars  :  Norm_chars  ; 

398 

399  if(  ! get cwd (Startdir,  DSIZE)  ) 

4C0  ( 

401  fprintf (stderr,  "Can't  save  current  directory,  abort ing\n") ; 

4G2  exit {  1  ) ; 

403  ) 

404 

405  signal (  SIGINT,  onlntr  ); 

406  prnt  (  (argc  <  1  ||  argv  --  Args)  ?  "/"  :  dodot  (argv (0) ) ,  0  ); 

407  chdlr(  Startdir  ); 

408 

409  exit  (0) ; 

410  ) 

End  Listing  One 

Listing  Two 

Listing  2  —  fix.c 

1  (include  <stdio.h> 

2  (include  <fcntl.h> 

3  (include  <types.h> 

4  (include  <stat.h> 

5 

6  extern  char  *strrchr(); 
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_ C  CHEST _ 

Listing  Two  (Listing  continued;  text  begins  on  page  14.) 


BSIZE  (10  *  1024)  /•  Buffer  size 

CTLZ  Oxla  /»  EOF  marker  •/ 

SMODE  (0_RD0NLY  |  0_ BINARY  )  /*  read  £  write  modes  * / 

DMODE  (OWRONLY  |  O^B I NARY  |  0_TRUNC  |  0_CREAT  ) 


*bak (  name  ) 

•name; 

/•  Strips  extension  from  name  and  adds  .bak  extension,  returning  •/ 
/*  a  pointer  to  the  modified  name.  The  original  name  is  untouched  •/ 

static  char  buf[128),  *p; 

strncpy(  buf,  name,  128-5  ); 

1 f (  p  -  strrchr{buf,  '.•)  ) 

strcpy(  p+1,  "bak"  ); 

else 

strcat(  buf,  M.bakM  ); 


fprintf (stderr,  “Usage:  fix  file  [file. . . ) \n\n") ; 
fprintf  (stderr,  "Removes  trailing  AZ's  from  files. \n"); 
exit  {  1  ) ; 


i  maln(argc,  argv) 


static  char  buf(BSIZE); 

static  char  'srename; 

char  *p; 

register  int  got; 

register  int  src,  dest; 


/*  I  bytes  got  from  read 
/*  File  handles 


ctlc() ; 

reargv(  targe,  targv  ); 


if(  arge  <  2  II  argv[l][0j  -- 
usage  () ; 


/*  Fix  AC  Interrupt  handling  •/ 
/•  Remake  argv  from  CMDLINE  •/ 


for(  ttargv,  — arge;  — arge  >-  0;  ++argv  ) 

[ 

srename  -  bak (  *argv  );  /•  s rename  - 

unlink (  srename  );  /•  delete  xx 

rename (  srename,  *aryv  );  /•  rename  xx 


;.yyy  to  xxx.bak  •/ 


printf {"Fixing  %-2Cs  (creating  %s)\n",  *argv,  srename  ); 
it(  (src  -  open (srename,  SMODE))  —  -1  ) 


perror{  srename  ); 
continue; 


lf(  (dest  -  open (  *argv,  DMODE,  S_IWRITE  |  S_IRF_»iD))  —  -1  ) 


perror(  *argv  ); 
continue; 


while  (  got  -  read (src,  buf,  BSIZC)  ) 

[ 

if (  got  —  -1  ) 

( 

perror (  srename  ) ; 
break; 


for(  p  -  buf;  — got  >-  0  &&  «p  !=  CTL_Z  ;  pt+  ) 


got  -  p  -  buf  ;  /*  got  -  distance  to  AZ  */ 


if{  write (dest,  buf,  got)  !-  got  ) 


perror (  ‘argv  ); 
break; 


if (  *p  —  CTL_Z  ) 
break; 


close  (  src  )  ; 
close  (  dest  ) ; 


End  Listings 
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CUBIC  SPLINES 

Listing  On6  (Text  begins  on  page  24.) 

/*  SPLINE. C  -  Interpolate  Smooth  Curve 

*  arbitrarily  constrained  to 

be  greater  than  or 

* 

*  equal  to  zero. 

*  Version  2.00 

December  25th,  1985 

* 

* 

*  Credits:  The  above  description  is  a 

reworded  and  expanded 

*  Modifications: 

version  of  that  appearing  in  the  "UNIX  Programmer's 

* 

*  Manual",  copyright  1979,  1983  Bell  Laboratories. 

*  VI. 00  (85/11/01)  -  beta  test  release 

V 

*  V2.00  (85/12/25)  -  general  revision 

* 

/***  Definitions  ***/ 

*  Copyright  1985:  Ian  Ashdown 

* 

by Heart  Software 

# define  FALSE  0 

* 

620  Ballantree  Road 

•define  TRUE  1 

* 

West  Vancouver,  B.C. 

#define  MAX  SIZE  1000  /*  Input  point  array  limit  V 

* 

Canada  V7S  1W3 

* 

•define  ILL  ARG  0  /*  Error  codes  */ 

*  This  program 

may  be  copied  for  personal,  non-commercial  use 

•define  ILL  CMB  1 

*  only,  provided  that  the  above  copyright  notice  is  included  in 

•define  ILL  KVL  2 

*  all  copies  of  the  source  code.  Copying  for  any  other  use 

•define  ILL  NVL  3 

*  without  previously  obtaining  the  written  permission  of  the 

•define  ILL  OPT  4 

*  author  is  prohibited. 

•define  ILL  XVL  5 

* 

•define  INS  INP  6 

*  Synopsis: 

SPLINE  (option]  ... 

•define  MIS  KVL  7 

* 

•define  MIS  NVL  8 

*  Description: 

SPLINE  takes  pairs  of  numbers  from  the  standard 

•define  MIS  XVL  9 

* 

input  as  abscissae  and  ordinates  of  a  function. 

•define  MIS  YVL  10 

* 

(A  minimum  of  four  pairs  is  required.)  It 

•define  NMT  ORD  11 

* 

produces  a  similar  set,  which  is  approximately 

* 

equally  spaced  and  includes  the  input  set,  on  the 

•define  SQUARE (a)  a*a 

* 

standard  output.  The  cubic  spline  output  (R.W. 

•  define  CUBE  (a)  a*a*a 

* 

Hamming,  "Numerical  Methods  for  Scientists  and 

* 

Engineers",  2nd  ed.  349ff)  has  two  continuous 

/***  Typedefs  ***/ 

* 

derivatives  and  sufficiently  many  points  to  look 

* 

smooth  when  plotted. 

typedef  int  BOOL;  /*  Boolean  flag  V 

• 

The  following  options  are  recognized,  each  as  a 

/***  Include  Files  ***/ 

separate  argument: 

* 

•include  <stdio.h> 

* 

-a  Supply  abscissae  automatically  (they  are 

•include  <ctype.h> 

* 

missing  from  the  input);  spacing  is  given  by 

•include  <math.h> 

* 

the  next  argument  or  is  assumed  to  be  1  if 

* 

next  argument  is  not  a  number. 

/***  Main  Body  of  Program  ***/ 

* 

-k  The  constant  "k"  is  used  in  the  boundary 

int  main  (argc,  argv) 

* 

value  computation 

int  argc; 

•  * 

char  **argv; 

* 

ii 

>. 

( 

* 

0  In  n-1 

int  n  *  0, 

* 

is  set  by  the  next  argument.  By  default. 

i. 

* 

k  =  0.  A  value  of  k  =  0.5  often  results  in  a 

n  val  -  0, 

* 

smoother  curve  at  the  endpoints  than  the 

atoi  () ; 

« 

default  value.  Negative  values  for  k  are  not 

float  x (MAX  SIZE], 

* 

allowed.  Cannot  be  used  with  -p  option. 

y (MAX  SIZE]; 

* 

double  a  val  =  1.0, 

* 

-n  Next  argument  (which  must  be  an  integer) 

k  val  =  0.0, 

* 

specifies  the  number  of  intervals  that  are  to 

xl  val  =  0.0, 

* 

occur  between  the  lower  and  upper  "x"  limits. 

x2  val  *  0.0, 

* 

If  -n  option  is  not  given,  default  spacing  is 

x  intvl. 

* 

100  intervals. 

ix, 

* 

iy. 

* 

-p  Make  output  periodic,  i.e.  match  derivatives 

d2y (MAX  SIZE], 

* 

at  ends.  First  and  last  input  values  must 

h. 

* 

agree.  Cannot  be  used  with  -k  option. 

atof  () , 

* 

fabs  () , 

* 

-x  Next  1  (or  2)  arguments  are  lower  (and  upper) 

spl  int(); 

* 

"x"  limits.  Normally  these  limits  are 

char  buffer [257] , 

* 

calculated  from  the  data.  Automatic  abscissae 

*temp, 

* 

start  at  lower  limit  (default  0) .  If  either 

•gets  0 ; 

* 

argument  is  outside  of  the  range  of 

BOOL  aflag  -  FALSE,  /*  Command-line  option  flags  */ 

* 

abscissae,  it  is  ignored. 

kflag  =  FALSE, 

* 

pf lag  -=  FALSE, 

*  Diagnostics: 

When  data  is  not  strictly  monotone  in  "x",  SPLINE 

xlf lag  =  FALSE, 

* 

reproduces  the  input  without  interpolating  extra 

x2f lag  -  FALSE, 

* 

points. 

is  float  ()  ; 

* 

void  spl  coeff(). 

*  Bugs: 

A  limit  of  1000  input  points  is  silently 

enforced. 

error  ()  ; 

The  -n  option  has  not  been  implemented  in 

/*  Parse  the  command  line  for  user-selected  options  */ 

* 

accordance  with  the  "UNIX  Programmer's  Manual" 

* 

specification.  This  was  done  to  avoid  ambiguities 

whi le  ( — argc) 

* 

when  the  -n  option  follows  the  -x  option  with  one 

I 

* 

argument . 

temp  =  *++argv; 

* 

if(*temp  !*■'-')  /*  Check  for  legal 

option  flag  */ 

* 

At  certain  negative  values  for  the  -k  option  (for 

er,ror  (ILL  OPT,  *argv) ; 

* 

example,  k  equals  -4.0),  the  curve  becomes 

else 

* 

discontinuous.  The  -k  option  value  has  thus  been 

switch (toupper  (*++temp) ) 
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CUBIC  SPLINES 


Listing  One 


(Listing  continued,  text  begins  on  page  24.) 


case  'A':  /*  "-a"  option  */ 

aflag  =  TRUE; 

if(argc  >  1  &&  is_f loat  (*  (argv+1) ) ) 

{ 

argc — ; 
argv++; 

if((a_val  -  atof  (*argv) )  <**  0.00) 
error (ILL_ARG, *argv) ; 

) 

break; 

case  'K':  /*  "-k"  option  */ 

i f (pf lag  —  TRUE) 

error  (ILL_CMB,  NULL)  ; 
kf lag  *  TRUE; 

if  (argc  >  1  &&  is_float  (*  (argv+1) ) ) 

( 

argc — ; 
argv++; 

k_val  =  atof(*argv); 
if (k_val  <  0.00) 

error (ILL_KVL, *argv) ; 
break; 

} 

else 

error  (MIS_KVL,  NULL)  ; 
case  'N‘:  /*  M-n"  option  */ 

if  (argc  >  1) 

{ 

argc — ; 
argv++; 

if((n_val  «=  atoi(*argv))  <  1) 
errpr  (ILL_NVL,  *argv)  ; 
else 
break; 

} 

else 

error  (MISJJVL,  NULL)  ; 
case  'P':  /*  "-p"  option  */ 

if  (kf lag  ~  TRUE) 

error (ILL_CMB, NULL) ; 
pf lag  =  TRUE; 
break; 

case  'X' :  /*  "-x"  option  V 

xlflag  -=  TRUE; 

if  (argc  >  1  &&  is_float  (*  (argv+1) ) ) 

( 

argc — ; 
argv++; 

xl_val  =  atof(*argv); 

} 

else 

error  (MISJCVL,  NULL) ; 
if  (argc  >  1  &&  is_float  (*  (argv+1) ) ) 

{ 

x2flag  =  TRUE; 
argc — ; 
argv++; 

x2_val  *  atof(*argv); 
if (x2_val  <»  xl_val) 
error (ILL_XVL,  x2_val)  ; 

) 

break; 

default:  /*  "-n"  option  */ 

error (ILL_OPT, *argv) ; 

) 

} 

if (n_val  ==  0)  /*  Set  "n_val"  if  not  given  */ 

n_val  -  100; 

/*  Get  the  input  data  */ 

whiled)  /*  ...  while  there  is  more  input  data  */ 

{ 

if (aflag  — =  TRUE)  /*  Automatic  abscissae  were  called  for  V 

( 

if  (n  -=-  0) 

x [ 0 )  -  xl_val; 
else 

x[n)  »  x[n-l]  +  a_val; 

} 

else  /*  Abscissae  supplied  with  input  data  */ 

{ 

if  (gets  (buffer) ) 

x[n]  -  atof (buffer) ; 
else 
break; 

) 

if (get? (buffer) )  /*  Read  in  the  corresponding  ordinate  */ 

y[nl  -  atof  (buffer)  ; 


( 

if (aflag  -=  TRUE) 
break; 
else 

error (MIS_YVL, NULL) ; 

) 

if(++n  ==  MAX_SIZE)  /*  Maximum  amount  of  input  data?  V 
break; 

) 

if (n  <  4)  /*  Check  for  insufficient  input  data  */ 

error (INS_INP, NULL) ; 

/*  Check  for  non-monotonic  abscissae.  Output  input  data  set 

*  without  interpolation  if  true. 

V 

h  -  x[l]  -  x[0); 
for(i  -  1;  i  <  n-1;  1++-) 

if  (fabs(x[i+l)  -  x[i]  -  h)  >  0.0) 

{ 

for(i  “0;  i  <  n;  i++) 

print f ("%g\n%g\nM,x(i) ,y  [i ) ) ; 
exit  () ; 

) 

/*  Calculate  abscissa  interval.  Use  M-x"  option  values  if 

*  they  were  given  unless  they  fall  outside  the  range  of 

*  given  (or  calculated)  abscissae. 

*/ 

if (xlflag  —  FALSE  ||  xl_val  <  x[0J) 
xl_val  =  x[0); 

if  (x2f lag  ==  FALSE  ||  x2_val  >  x(n-l]) 
x2_val  -  x[n-lj; 

x_intvl  -  (x2_val  -  xl_val) /n_val; 

/*  Find  the  coefficients  */ 

if (pf lag  ==  FALSE) 

spl_coeff (y,d2y, h, n,k_val) ; 
else 

pspl_coef  f  (y,  d2y,  h,  n) ; 

/*  Interpolate  and  output  results  */ 

ix  -  xl_val; 
i  -  1; 

for(j  -  0;  j  <»  n_val;  j++) 
i 

while(ix  >-  x(i]  &&  i  <  n  -  1) 
i++; 

iy  -  spl_int  (ix,x,y,d2y,  h,  i); 
printf  ("tgXntgXn1',  ix,  iy)  ; 
ix  +=  x_intvl; 

) 


/***  Functions  ***/ 

/•  SPL_COEFF()  -  Calculate  spline  coefficients  and  return  in 

*  vector  Md2y[)".  Matrix  to  be  solved  has  the 

*  typical  form: 

*  +-  -+  +-  -+  +-  -+ 

*  I  4+k  1  0  0  |  |  yl"  |  -  m  *  |  y2  -  2*yl  +  yO  | 

*  I  1  4  1  0  |  |  y2"  |  I  y3  -  2*y2  +  yl  | 

*  I  0  1  4  0  |  |  y3"  |  |  y4  -  2*y3  +  y2  | 

*  |  0  0  1  4+k  |  |  y4"  |  |  y5  -  2*y4  +  y3  | 

*  +-  -+  +-  -+  +-  -+ 

*  where  k  -  k_val,  m  =  6.0/ (h*h)  and  yn"  is  the 

*  second  derivative  of  the  interpolated  function 

*  at  the  "nth"  abscissa,  yO"  -  k  *  yl"  and 

*  y5"  =  k  *  y4". 

•/ 

void  spl_coeff (y, d2y, h, n, k_val) 
float  y ( ) ; 
double  d2y[], 
h, 

k_val; 

int  n; 

( 

double  m, 

a[MAX_SIZE-U; 

int  i; 

/*  Set  up  the  (symmetric  tridiagonal)  matrix,  where  the  only 

(continued  on  next  page) 
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CUBIC  SPLINES 

UStinCj  On©  (Listing  continued,  text  begins  on  page  24.) 

*  elements  of  interest  are  those  on  the  diagonal.  These  are 

a [ i ]  =  4.0  -  m; 

*  stored  in  array  "a [ ) " .  Array  "d2y[]"  initially  holds  the 

b[i]  —  b (i-1 ]  *  m; 

*  constants  vector,  then  is  overlaid  with  the  calculated 

d2y [i ]  —  d2y [i-1]  *  m; 

*  variables  vector. 

b[n-l]  —  c  *  m  *  b [ 1—1 ] ; 

V 

cl2y(n-l]  —  c  *  m  *  d2y [  1—1 1 ; 

m  -  6.0/ (h*h) ; 

c  *  -c  *  m; 

) 

for (i  -  1;  i  <  n-1;  i++) 

c  +-  1.0; 

d2y[ij  -  m  *  (y[i+l]  -  2.0  *  y[l)  +  y[i-l]); 

b[n-l]  --  c  *  b[n-2] /a [n-2] ; 

a [1]  -  4.0  +  k_val; 

d2y [n-1 ]  —  c  *  d2y [n-2] /a [n-2 ] ; 

/*  Reduce  the  matrix  to  upper  triangular  form  */ 

/*  Solve  using  back  substitution  *7 

for (i  -  2;  i  <  n-2;  i++) 

d2y [0]  -  d2y [n-1 ]  /«  b[n-l); 

{ 

d2y [n-2 ]  =  (d2y[n-2]  -  b[n-2]  *  d2y [n-1] ) /a [n-2 ] ; 

a [ i ]  -  4.0  -  1.0/a  [ i— 1 ) ; 

for(i  =  n-3;  i  >  0;  i— ) 

d2y [ i )  —  d2y (i-1] /a [i-1] ; 

d2y [i ]  =  (d2y [i]  -  b[i]  *  d2y[n-l]  -  d2y[i+l] ) /a [i] ; 

a [n-2]  -  4.0  +  k  val  -  1.0/a[n-3]; 

d2y [n-2]  —  d2y[n-3]/a[n-3]; 

/*  SPL  INT  -  Interpolate  points  using  spline  function  */ 

d2y [n-2]  /-  a [n-2]; 

/*  Solve  using  back  substitution  */ 

double  spl_int  (ix,x,y,d2y,h,  i) 
float  x[], 

y  U; 

double  ix. 

for  (i  -  n-3;  i  >  0;  i— ) 

d2y[i)  -  (d2y(l)  -  d2y(i+l)) /a(l] ; 

d2y[]. 

/*  Solve  for  end  conditions  */ 

int  i; 

d2y[n-l]  *  d2y[n-2]  *  k  val; 

double  iy. 

d2y (0)  -  d2y [1]  *  k  val; 

tl. 

) 

t2; 

/*  psPL  COEFFO  -  Calculate  periodic  spline  coefficients  and 

tl  =  (ix  -  x [ 1—1 ] ) /h; 

*  return  in  vector  ''d2yn".  Matrix  to  be  solved 

t2  -  (x  [  1  ]  -  ix)  /h; 

*  has  the  typical  form: 

iy  -  y [i-1 1  *  t2  +  y[i|  *  tl  -  SQUARE (h)  *  (d2y [i-1]  *  (t2  - 

* 

CUBE (t 2) )  +  d2y [i]  *  (tl  -  CUBE  (tl) ) ) /6.0; 

*  +-  -+  +-  -+  +-  -+ 

return  iy; 

•  1  4  1  0  0  1  |  |  yl"  1  -  m  *  1  y2  -  2*yl  +  yO  1 

) 

*  |  1  4  1  0  0  |  |  y2"  |  1  y3  -  2*y2  +  yl  1 

*  1  0  1  4  1  0  II  y3"  |  1  y4  -  2*y3  +  y2  I 

/*  is  FLOAT  ()  -  Check  that  character  string  is  in  correct  floating 

*  |  0  0  1  4  1  |  I  y4“  1  1  y5  -  2*y4  +  y3  1 

*  point  format.  Return  TRUE  if  correct,  FALSE 

*  I  1  0  0  1  4  |  1  y5"  I  I  yl  -  yO  -  y5  +  y4  I 

*  otherwise.  The  algorithm  used  is  a  deterministic 

*  +-  -+  +-  -+  +-  ~+ 

*  finite  state  machine.  Using  the  regular 

*  expression  terminology  of  Unix's  "lex",  the 

*  where  m  -  6.0/ (h*h)  and  yn“  Is  the  second 

*  character  string  must  be  of  the  form: 

*  derivative  of  the  interpolated  function  at  the 

*  "nth"  abscissa  and  yO"  -  y5" . 

*  -?d*.?d*  (e | E (\+ 1  — ) ?d+) ? 

void  pspl  coef £  (y,d2y, h, n) 

*  where  d  -  0 | 1 | 2 | 3 |4 | 5 | 6| 7 | 8 | 9 

V 

float  y[]; 

double  d2y [] , 

BOOL  is  float (str) 

h; 

char  *str; 

int  n; 

( 

{ 

Int  c,  /*  Next  FSM  Input  character  */ 

double  c, 

state  *  0;  /*  Current  FSM  state  * / 

fabs  () ; 

while (c  -  *str++) 

static  double  a (MAX  SIZE-1], 

{ 

b(MAX  SIZE]; 

switch  (state) 

int  i; 

i 

/*  Check  for  matching  end  ordinates  */ 

case  0:  /*  FSM  State  0  */ 

switch (c) 

if (fabs (y [n-1]  -  y  [ 0 ] )  >  0.0) 

case  : 

error  (NMT  ORD,  NULL) ; 

state  “  1; 

break; 

/*  Set  up  the  matrix,  where  array  "a[]''  holds  the  diagonal 

case  ' . ' : 

*  elements,  Mb[]H  holds  those  elements  of  column  "n-1",  and 

state  =3; 

*  "c"  holds  the  current  element  of  interest  of  row  "n-1". 

break; 

*  Array  "d2y[]“  initially  holds  the  constants  vector,  then  is 

default: 

*  overlaid  with  the  calculated  variables  vector. 

if (isdigit  (c) ) 

*/ 

state  =  2; 

m  -  6.0/ (h*h) ; 

else 

return  FALSE; 

for(i  -  1;  i  <  n-1;  i++) 

break; 

d2y  ( i  ]  =  m  *  (y  [i  +  1]  -  2.0  *  y[i]  +  y  [i-1  ] ) ; 

i 

d2y[n-l]  -  m  *  (y [1 1  -  y[0]  -  y[n-l)  +  yln-2]); 

break; 

a [1 ]  -  4.0; 

case  1:  /*  FSM  State  1  */ 

b [ 1 ]  -  1.0; 

switch (c) 

b[n-2]  -  1.0; 

i 

b[n-l|  -  4.0; 

case  ' . ' : 

o 

■ 

o 

state  -  2; 

/*  Reduce  the  matrix  to  upper  triangular  form  */ 

break; 
default : 

for  (i  -  2;  1  <  n-1;  i++) 

if (isdigit  (c) ) 
state  -  2; 

m  -  1/a [i-1]; 
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else 

return  FALSE; 
break; 


break; 
case  2: 
switch (c) 


/*  FSM  State  2  */ 


state  -4; 
break; 
case  'e': 
case  'E': 
state  =  5; 
break; 
default: 

if (isdigit  (c) ) 
state  -  2; 
else 

return  FALSE; 
break; 


break; 
case  3: 

if  (isdigit  (c) ) 
state  -  4; 
else 

return  FALSE; 
break; 
case  4: 
switch (c) 


/*  FSM  State  3  */ 


/*  FSM  State  4  */ 


case  'e': 
case  ' E ' : 
state  -  5; 
break; 
default: 

if  (isdigit  (c)  ) 
state  -  4; 
else 

return  FALSE; 
break; 


case  ILL_NVL: 
fprintf (stderr, ' 
break; 

case  ILL_OPT: 
fprintf (stderr, 1 
break; 

case  ILL_XVL: 
fprintf (stderr, 1 
break; 

case  INS_INP: 
fprintf  (stderr, 1 
break; 

case  MIS_KVL: 
fprintf (stderr, 
break; 

case  MIS_NVL: 
fprintf (stderr, 
break; 

case  MIS_XVL: 
fprintf (stderr, 
break; 

case  MIS_YVL: 
fprintf  (stderr, 
break; 

case  NMT_ORD: 
fprintf (stderr, 
break; 

default: 

break; 

} 

fprintf (stderr, "  ** 
exit (2) ; 


Illegal  value  for  -n  option:  %s",str); 


Illegal  command  line  option:  %s",str); 


Illegal  value  for  -x  option:  %s",str); 


Insufficient  input  data") ; 


‘Missing  value  for  -k  option"); 


'Missing  value  for  -n  option"); 


'Missing  value  for  -x  option"); 


'Missing  ordinate  value"); 


'End  ordinates  do  not  match"); 


*\n\nUsage:  spline  f-aknpx) \n") ; 


/***  End  of  SPLINE. C  ***/ 


break; 
case  5: 
switch  (c) 


/*  FSM  State  5  V 


End  Listing 


state  -  6; 
break; 
default: 

if (isdigit  (c) ) 
state  -  7; 
else 

return  FALSE; 
break; 


break; 

case  6:  /*  FSM  State  6  */ 

if (isdigit (c)) 
state  -  7; 
else 

return  FALSE; 
break; 

case  7:  /*  FSM  State  7  */ 

if  (isdigit (c)) 
state  -  7; 
else 

return  FALSE; 
break; 


return  TRUE; 


/*  ERROR ()  -  Error  reporting.  Returns  an  exit  status  of  2  to  the 
*  parent  process. 


void  error  (n,  str) 
int  n; 
char  *str; 
l 

fprintf (stderr, M\007\n***  ERROR  -  ") ; 
switch (n) 


case  ILL_ARG: 

fprintf (stderr, "Argument  must  be  greater  than  zero:  %s", 
str)  ; 
break; 

case  ILL_CMB: 

fprintf (stderr, "Cannot  use  -k  option  with  -p  option"); 
break; 

case  ILL_KVL: 

fprintf (stderr,  "Illegal  value  for  -k  option:  %s",str); 
break; 
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SORTING  ALGORITHM 


Listing  One  (Text  begins  on  page  32.) 


/*  Listing  one  */ 

/‘Radix  sort  listing*/ 

/*  These  includes  are  necessary  to  get  the  proper  declarations  for  some  of 
the  Macintosh  routines  */ 
linclude  event. h 
linclude  quickdraw.h 

typedef  struct  {  /‘Define  a  structure  for  the  sort  keys*/ 

struct  sortrec  *ptr;  /‘Pointer  to  next  key*/ 

char  sortdat [KEYSIZ) ;  /*The  key,  containing  KEYSIZ  bytes*/ 

}  sortrec; 
char  *lmalloc(); 


sortrec  ‘begin, *first, ‘start, *temp; 
int  i,j,recno; 
long  tick; 
unsigned  char  dat; 

MaxApplZone () ;  /‘Get  maximum  size  application  heap*/ 

begin  -  (sortrec  *)  lmal loc (0x40000) ;  /‘Allocate  256K  for  sortrecs*/ 

/‘Check  if  allocation  was  successful  and  exit  if  not*/ 
if  (Ibegin)  ( 

print f ("\nNot  enough  memory  in  heap"); 

_exit  () ; 

} 

first  -  begin;  /‘Point  to  first  record*/ 

printf("How  many  recs  to  sort\n"); 

scanf  ("%d", &recno) ; 

for  (i=0;  icrecno;  ++i)  { 

first->ptr  «  first+1;  /‘Set  pointer  to  next  record  in  heap*/ 

for  (j=0;  j<  KEYSIZ;  ++j)  /‘Fill  with  KEYSIZ  random  bytes*/ 
f irst->sortdat [ j ]  =  (Random () &0x7fff) %256; 

++first;  /‘Point  to  next  sort  key  record*/ 

)  /‘All  records  allocated  and  filled*/ 

first->ptr  =  0;  /‘Terminate  the  linked  list*/ 

tick  -  TickCountO;  /‘Get  the  current  time*/ 

start  =  sort (KEYSIZ, begin) ;  /‘Sort  the  list*/ 

printf ("\nTickcount=%ld",TickCount () -tick) ;  /‘Print  elapsed  time*/ 


sortrec  ‘sort (a, b) 

int  a;  /‘number  of  bytes  in  the  sort  key*/ 

sortrec  *b;  /‘Pointer  to  head  of  linked  list  to  be  sorted*/ 

{  /‘First  and  last  are  pointers  to  follow  two  linked  lists  whose 

heads  are  start  and  start2.  Temp  follows  the  full-length 
original  or  partly  sorted  list*/ 
sortrec  ‘first, *  last, ‘start, ‘temp, *start2; 

static  char  mask [8]  *  {  1, 2, 4, 8, 16, 32, 64, 128) ; /‘Individual  bit  masks*/ 
register  i,j; 

start  -  b;  /‘point  to  original  unsorted  list*/ 

for  (i  -  a-1;  i  >=  0;  — i)  {  /‘Loop  for  all  bytes  of  the  sort  key*/ 

for  (j  =  0;  j  <  8;  ++j)  {  /‘Loop  for  all  bits  of  each  byte*/ 
first  =  last  =  start2  =  0;  /‘Set  up  working  ptrs*/ 
/‘Loop  for  each  key  in  the  list*/ 
for  (temp  =  start;  temp;  temp  -  temp->ptr)  { 
if  (temp->sortdat [i] &mask [ j) ) 

/‘Value  of  the  bit  was  1.  If  last  list  is  empty,  initialize  it*/ 

if  (last==0)  start2  =  temp; 

/‘else  add  this  item  to  the  list*/ 
else  last->ptr  -  temp; 
last  =  temp; 

) 

/‘Value  was  0.  If  first  list  empty,  initialize  it*/ 
else  { 

if  (f irst==0)  start  =  temp; 

/‘else  add  this  item  to  the  list*/ 
else  first->ptr  *  temp; 
first  -  temp; 

) 

)  /‘End  of  list*/ 

/‘If  last  list  not  empty,  terminate  it*/ 
if  (last)  last->ptr  =  0; 

/‘if  first  list  empty,  use  last  only*/ 
if  (first  ==  0) start  =  start2; 

/‘Else  add  last  list  to  first  list*/ 
else  first->ptr  =  start2; 

)  /‘All  bits  this  byte  examined*/ 

}  /‘all  bytes  examined*/ 
return  start; 

} 


End  Listing  One 
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Listing  Two 

/*  Listing  two  */ 

/♦Shell  sort  listing*/ 

/♦Includes  for  certain  Macintosh  routines*/ 

•include  quickdraw.h 
•include  event. h 

typedef  struct  {  /*This  structure  consists  only  of  KEYSIZ  bytes*/ 
char  sortdat [KEYSIZ] ; 

)  sortrec; 
char  *lmalloc(); 

main  () 

{  int  i,j,recno; 

long  tick; 

sortrec  *array,  *base; 
unsigned  char  dat; 

MaxApplZone () ;  /*Get  heap  space,  allocate  256K  for  sort  keys*/ 

array  -  base  »  (sortrec  *)  lmalloc  (0x40000) ; 

printf("How  many  recs  to  sort\n“); 

scanf  (M%d", &recno) ; 

if  (‘array)  { 

printf ("\nNot  enough  memory  in  heap"); 
exit  () ; 

} 

/♦Fill  the  area  with  random  data.  Use  array  as  a  pointer  to  all  records*/ 
for  (i-0;  Krecno;  ++i)  { 

for  ( j“0; jcKEYSIZ;  ++ j)  { 

dat  -  (Random () &0x7fff) %256; 
array->sortdat [ j]  *  dat; 

) 

++array; 

} 

tick  -  TickCouhtO;  /*Get  the  current  time*/ 

sort (KEYSIZ, base, comp, swap, recno) ; 

printf ("\nTickcount-%ld", TickCount () -tick) ;  /*Print  elapsed  time*/ 

) 

sortrec  *sort (size, start, comp, swap, n) 

int  size,n; 

sortrec  * start; 

long  (*comp)  (),  (*swap)  () ; 

/*This  is  essentially  identical  to  that  in  the  Kernighan  and  Ritchie  text. 

The  call  includes  size  (the  number  of  records),  start  (a  pointer  to  the 
first  record),  comp  and  swap  (routines  for  comparing  and  swapping  byte 
strings,  given  pointers  to  them,  and  the  number  of  bytes  contained  therein, 
and  n  (the  number  of  bytes  in  the  sort  key) */ 

{  int  gap, i,j; 

for  (gap  -  n/2;  gap  >  0;  gap  /=  2) 
for  (i-gap;  i<n;  i++) 

for  (j-i-gap;  j>-0;  j— gap)  ( 

if  ( (*comp)  (start+ j, start+ j+gap, size)  <-  0)  break; 
(♦swap) (start+j,start+j+gap,size) ; 

) 

) 

comp (vail, val2, n) 
char  *vall,*val2; 
int  n; 

{  register  i; 

for  (i-0;  i<n;  ++i)  { 

if  (*(vall+i)  <  *(val2+i))  return  (-1); 
else  if  (*(vall+i)  >  *(val2+i))  return (1); 

} 

return  0; 

} 

swap (vail , val2, n) 
char  *vall,*val2; 
int  n; 

{  register  i,temp; 

for  (i-0;  i<n;  ++i)  { 
temp  =  *vall; 

*vall++  «  *val2; 

*val2++  -  temp; 

) 

} 


End  Listings 
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Listing  One  (Text  begins  on  page  46.) 

These  listing  are  available  for  downloading  from  co-author  Mike 
Elkins  Fido  BBS  at  (619)722-8724  which  operates  at  300  and  1200 
baud,  8-bits,  no  partity,  1  stop-bit. 

-  LISTING  1  - 

/* 

Erathosthenes  Sieve  Prime  Number  Program  in  C 

*/ 

tdefine  TRUE  1 
# define  FALSE  0 
#define  SIZE  8190 
# define  SIZEP1  8191 
char  flags [SIZEP1]; 
main() 

( 

int  i,  prime,  j,  count,  loops; 
loops  =1; 

while (loops  <=  10)  /*  Changed  to  100  for  second  benchmark  */ 

{ 

count  =0; 
i  =  0; 

while (i  <=  SIZE) 

{ 

flags [i]  =  TRUE; 
i++; 

} 

i  =  0; 

while (i  <=  SIZE) 

{ 

if (flags [i] ) 

{ 

prime  =  i  +  i  +  3; 
j  =  i  +  prime; 
while  (j  <=  SIZE) 

{ 

flags [j]  =  FALSE; 
j  =  j  +  prime; 

} 

count++; 

} 

i++; 

} 

loops++; 

} 

printf("%d  primes,  %d  loops\n",  count,  loops); 
return; 

1  End  Listing  One 

Listing  Two 


-  LISTING  2 

/* 


* 

"DHRYSTONE" 

Benchmark  Program 

* 

Compile: 

cl  dry.c  (Microsoft 

3.0) 

* 

Defines: 

Defines  are  provided  for  old  C  compiler's 

* 

which  don't  have  enums,  and  can't  assign  structures. 

* 

The  time  (2)  function 

is  library  dependant; 

One  is 

* 

provided  for  CI-C86. 

Your  compiler  may  be 

different. 

* 

This  is  not  required  for  Microsoft  3.0  which  supports 

* 

all  of  the  standard 

calls  and  will  compile 

asis. 

* 

MACHINE 

OPERATING 

COMPILER  DHRYSTONES 

* 

TYPE 

SYSTEM 

/SEC 

* 

IBM  PC 

PCDOS  3.1 

Microsoft  C  3.0 

333 

* 

IBM  PC/AT 

PCDOS  3.1 

Microsoft  C  3.0 

1041 

* 

$ 

IBM  PC/AT 

PCDOS  3.0 

CI-C86  2.1 

684 

* 

$ 

ATT  3B2/300 

UNIX  5.2 

cc 

806 

* 

$ 

IBM  PC/AT 

VENIX/86  2.1 

cc 

1000 

* 

$ 

Sun2/120 

Sun  4.2BSD 

cc 

1219 

*  The  entries  with  $  supplied  by  Rick  Richardson,  who  origanally  converted 

*  the  program  from  ADA. 

*  The  rest  are  provided  by  Mike's  "C"  Board  619-722-8724  . 
*********************************************************** *************** 

*  The  following  program  contains  statements  of  a  high-level  programming 

*  language  (C)  in  a  distribution  considered  representative: 

* 

*  assignments  53% 

*  control  statements  32% 

*  procedure,  function  calls  15% 

*  100  statements  are  dynamically  executed.  The  program  is  balanced  with 

*  respect  to  the  three  aspects: 

*  -  statement  type 

*  -  operand  type  (for  simple  data  types) 

*  -  operand  access 
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*  operand  global,  local,  parameter,  or  constant. 

* 

*  The  combination  of  these  three  aspects  is  balanced  only  approximately. 

* 

*  The  program  does  not  compute  anything  meaningful 1,  but  it  is 

*  syntactically  and  semantically  correct. 

* 

*/ 


/*  Compiler  dependent  options  */ 


#undef 

NOENUM 

/*  Define  if 

#undef 

NOSTRUCTASSIGN 

/*  Define  if 

#undef 

NOTIlffi 

/*  Define  if 

fifdef 

NOSTRUCTASSIGN 

Idefine 

#else 

structassign(d. 

s) 

memcpy  (&  (d) , 

Idefine 

lendif 

structassign (d. 

s) 

d  =  s 

compiler  has  no  enum's  */ 
compiler  can't  assign  structures 
no  time()  function  in  library  */ 


&  (s) ,  sizeof(d)) 


*/ 


#ifdef  NOENJM 
#define  Ideml 
#define  Idend 
Idefine  Idenc3 
#define  I  dent  4 
#define  I dent 5 
typedef  int 
#else 

typedef  enum 
#endif 


1 

2 

3 

4 

5 

Enumeration; 

{Identl,  Ident2,  Ident3,  Ident4,  Ident5}  Enumeration; 


OneToThirty; 
OneToFifty; 
CapitalLetter; 
String30 [31] ; 
ArraylDim[51] ; 
Array2Dim[51]  [51]  ; 


typedef  int 
typedef  int 
typedef  char 
typedef  char 
typedef  int 
typedef  int 

struct  Record 

{ 

struct  Record 
Enumeration 
Enumerat ion 
OneToFifty 
String30 

}; 

typedef  struct  Record 
typedef  RecordType  * 
typedef  int 

I define  NULL 
# define  TRUE 
I define  FALSE 

#ifndef  REG 
#define  REG 
#endif 


*PtrComp; 
Discr; 
EnumCorrp; 
Int Comp; 
StringComp; 


RecordType; 

RecordPtr; 

boolean; 

0 

1 

0 


extern  Enumeration  Fund  () ; 

extern  boolean  Func2(); 


main  () 

{ 

ProcO  () ; 

} 


/* 

*  Package  1 

*/ 

int 

Int Glob; 

boolean 

BoolGlob; 

char 

CharlGlob; 

char 

Char2Glob; 

Array 1 Dim 

ArraylGlob; 

Array2Dim 

Array2Glob; 

RecordPtr 

PtrGlob; 

RecordPtr 

PtrGlobNext 

ProcO  () 

{ 

OneToFifty 

REG  OneToFifty 

OneToFifty 

REG  char 

REG  char 

REG  Enumeration 

String30 

String30 


Int Loci; 

IntLoc2; 

IntLoc3; 

CharLoc; 

Char Index; 

EnumLoc; 

StringlLoc; 

String2Loc; 


#define  LOOPS  50000 

long  time  () ; 


(continued  on  next  page) 
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Listing  Two  (Listing  continued,  text  begins  on  page  46.) 

long  starttime; 

1 ong  bencht  ime ; 

long  nulltime; 

register  unsigned  int  i; 
starttime  =  time  (0) ; 
for  (i  =  0;  i  <  LOOPS;  ++i)  ; 
nulltime  =  time(0)  -  starttime; 

PtrGlobNext  =  (RecordPtr)  malloc  (sizeof (RecordType) ) ; 

PtrGlob  =  (RecordPtr)  malloc  (sizeof (RecordType) ) ; 

PtrGlob->PtrComp  =  PtrGlobNext; 

PtrGlob->Discr  =  Identl; 

PtrGlob->EnumComp  =  Ident3; 

PtrGlob->I ntComp  =  40; 

strcpy (PtrGlob->StringComp/  "DHRYSTONE  PROGRAM,  SOME  STRING"); 

^***************** 

—  Start  Timer  — 

*****************  j 

starttime  =  time (0) ; 

for  (i  =  0;  i  <  LOOPS;  ++i) 

{ 

Proc5  () ; 

Proc4  () ; 

Int Loci  =  2; 

IntLoc2  =3; 

strcpy (String2Loc,  "DHRYSTONE  PROGRAM,  2'ND  STRING"); 

EnumLoc  =  Ident2; 

BoolGlob  =  !  Func2 (StringlLoc,  String2Loc) ; 
while  (Int Loci  <  IntLoc2) 

{ 

IntLoc3  =  5  *  IntLocl  -  IntLoc2; 

Proc7 (Int Loci,  IntLoc2,  &IntLoc3) ; 

++ IntLocl; 

} 

Proc8  (ArraylGlob,  Array2Glob,  IntLocl,  IntLoc3) ; 

Prod  (PtrGlob)  ; 

for  (Charlndex  =  'A';  Charlndex  <=  Char2Glob;  ++Charlndex) 
if  (EnumLoc  =  Fund  (Charlndex,  'C')) 

Proc6 (Identl,  &EnumLoc) ; 

IntLoc3  =  IntLoc2  *  IntLocl; 

IntLoc2  =  IntLoc3  /  IntLocl; 

IntLoc2  =  7  *  (IntLoc3  -  IntLoc2)  -  IntLocl; 

Proc2 (slntLocl) ; 

} 

^***************** 

—  Stop  Timer  — 

*****************  j 

benchtime  =  time(0)  -  starttime  -  nulltime; 

printf ("Dhry stone  time  for  %ld  passes  =  %ld\n",  (long)  LOOPS,  benchtime); 
printf ("This  machine  benchmarks  at  %ld  dhrystones/second\n", 

((long)  LOOPS)  /  benchtime); 

} 

Prod  (PtrParln) 

REG  RecordPtr  PtrParln; 

{ 

# define  NextRecord  (*  (PtrParIn->PtrComp) ) 

structassign (NextRecord,  *PtrGlob) ; 

PtrParIn->IntComp  =  5; 

NextRecord. I ntComp  =  PtrParIn->IntConp; 

Next Record. PtrComp  =  PtrParIn->PtrComp; 

Proc3 (NextRecord.PtrConp) ; 
if  (NextRecord. Discr  ==  Identl) 

{ 

NextRecord. I ntComp  =6; 

Proc6 (PtrParIn->EnumConp,  &NextRecord. EnumComp) ; 
NextRecord. PtrConp  =  Pt  rG 1 ob-> P t r Comp ; 

Proc7 (NextRecord. Int Comp,  10,  &NextRecord.IntComp) ; 

} 

else 

structassign (*PtrParIn,  NextRecord) ; 

#undef  NextRecord 
} 

Proc2 (IntParlO) 

OneToFifty  * Int Par 10; 

{ 

REG  OneToFifty  IntLoc; 

REG  Enumeration  EnumLoc; 

IntLoc  =  *IntParI0  +  10; 
for  (;;) 

{ 

if  (CharlGlob  ==  'A') 

{ 
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— IntLoc; 

*IntParIO  =  IntLoc  -  IntGlob; 
EnumLoc  =  Identl; 

} 

if  (EnumLoc  ==  Identl) 
break; 

} 

} 


Proc3 (PtrParOut) 

RecordPtr  *PtrParOut; 

{ 

if  (PtrGlob  !=  NULL) 

♦PtrParOut  =  PtrGlob->PtrComp; 

else 

IntGlob  =  100; 

Proc7 (10,  IntGlob,  &PtrGlob->IntComp) ; 

} 

Proc4  () 

{ 

REG  boolean  BoolLoc; 

BoolLoc  =  CharlGlob  =  'A'; 

BoolLoc  |=  BoolGlob; 

Char2Glob  =  'B'; 

} 

Proc5  () 

{ 

CharlGlob  =  'A'; 

BoolGlob  =  FALSE; 

) 


extern  boolean  Func3 () ; 


Proc6 (EnumParln,  EnumParOut) 
REG  Enumeration  EnumParln; 
REG  Enumeration  * EnumParOut; 
{ 


} 


* EnumParOut  =  EnumParln; 
if  (!  Func3 (EnumParln)  ) 

♦EnumParOut  =  I dent 4; 
switch  (EnumParln) 

{ 


case  Identl: 
case  I dent 2: 


case  Ident3: 
case  I dent 4: 
case  Ident5: 


Identl;  break; 
100)  *EnumParOut 


} 


♦EnumParOut  = 
if  (IntGlob  > 
else  *EnumParOut  =  Ident4; 
break; 

♦EnumParOut  =  Ident2;  break; 
break; 

♦EnumParOut  =  Ident3; 


Identl; 


Proc7 (IntParll,  IntParI2,  IntParOut) 

OneToFifty  IntParll; 

OneToFifty  I nt Pari 2; 

OneToFifty  * IntParOut; 

{ 

REG  OneToFifty  IntLoc; 


IntLoc  =  IntParll  +  2; 
♦IntParOut  =  IntParI2  +  IntLoc; 


Proc8 (ArraylPar, 
ArraylDim 
Array2Dim 
OneToFifty 
OneToFifty 
{ 


Array2Par, 
ArraylPar; 
Array 2 Par; 
IntParll; 

I nt Pari 2; 


IntParll, 


REG  OneToFifty  IntLoc; 
REG  OneToFifty  Intlndex; 


IntParI2) 


IntLoc  =  IntParll  +  5; 

ArraylPar [IntLoc]  =  IntParI2; 

ArraylPar [IntLoc+1]  =  ArraylPar [IntLoc] ; 

ArraylPar [IntLoc+30]  =  IntLoc; 

for  (Intlndex  =  IntLoc;  Intlndex  <=  (IntLoc+1) ;  ++Intlndex) 
Array2Par[ IntLoc] [Intlndex]  =  IntLoc; 

++ Array 2Par [IntLoc] [IntLoc-1]; 

Array2Par [IntLoc+20] [IntLoc]  =  ArraylPar [IntLoc] ; 

IntGlob  =5; 


Enumeration  Fund  (CharParl, 
CapitalLetter  CharParl; 
CapitalLetter  CharPar2; 

{ 

REG  CapitalLetter 
REG  CapitalLetter 


CharPar2) 


Char Loci; 
CharLoc2; 


(continued  on  nepct  page) 
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Listing  Two  (Listing  continued,  text  begins  on  page  46.) 


} 


CharLocl  =  CharParl; 
CharLoc2  =  CharLocl; 
if  (CharLoc2  !=  CharPar2) 
return  (Identl); 

else 

return  (Ident2); 


boolean  Func2 (StrParll,  StrParI2) 

String30  StrParll; 

String30  StrParI2; 

{ 

REG  OneToThirty  IntLoc; 

REG  CapitalLetter  CharLoc; 

IntLoc  =  1; 
while  (IntLoc  <=  1) 

if  (Fund (StrParll [IntLoc] ,  StrParI2 [IntLoc+1] )  ==  Identl) 

{ 

CharLoc  =  'A'; 

++IntLoc; 

} 

if  (CharLoc  >=  'W  &&  CharLoc  <=  ' Z 1 ) 

IntLoc  =  7; 
if  (CharLoc  =  'X') 

return (TRUE) ; 

else 

{ 

if  (stranp (StrParll,  StrParI2)  >  0) 

( 

IntLoc  +=  7; 
return  (TRUE); 

} 

else 

return  (FALSE) ; 


) 

} 

boolean  Func3 (EnumParln) 

REG  Enumeration  EnunParln; 

{ 

REG  Enumeration  EnumLoc; 

Enumloc  -  EnumParln; 

if  (EnumLoc  —  Ident3)  return  (TRUE); 

return  (FALSE) ; 

) 

lifdef  NOSTRUCTASSIGN 
memcpy(d,  s,  1) 
register  char  *d; 

register  char  *s; 

int  1; 

while  (1—)  *d++  -  *sf+; 

) 

lendlf 

/* 

*  Library  function  for  compilers  with  no  time (2)  function  in  the 

*  library. 

•/ 

lifdef  NOTIME 
long  time(p) 
long  *p; 

(  /•  CI-C86  time  function  -  don't  use  around  midnight  V 

long  t ; 

struct  regval  (unsigned  int  ax,bx,cx,dx, si,di,ds, es;  )  regs; 

regs.ax  -  0x2 cOO; 
sysint21  (iregs,  &regs)  ; 

t  -  ( (regs.cx»8)  *60L  +  (regs.cx  &  0xff))*60L  +  (regs.dx»8); 
if  (p)  *p  -  t; 
return  t; 

1 

•endif 


End  Listings 
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Listing  One  (Text  begins  on  page  108.) 

Listing  1. 


1)  copy  masm.exe  masm.sav  (to  make  a  backup) 

2)  ren  masm.exe  masm.fix  (debug.com  can't  write  EXE  files) 

3)  debug  masm.fix 

3a)  D  72B8  L  22  (should  see  34  bytes  of  00) 

3b)  E  72B8 

enter  these  bytes: 

8B  IE  D6  09  C6  06  CO  01  00  E9  75  02  C4  57  06  FE 
06  CO  01  E9  74  02  80  7C  FF  1A  74  03  39  9D  02  4E 
EB  F4 

3c)  U  7535  L  1  (should  see  "MOV  BX, [09D6]"  ) 

3d)  E  7535 

enter  these  bytes:  E9  80  FD 
3e)  U  753F  L  1  (should  see  "LES  DX,  [BX+06] "  ) 

3f)  E  753F 

enter  these  bytes:  E9  82  FD 
3g)  U  756D  L  1  (should  see  "CMP  BYTE  PTR  [SI-01 ],1A"  ) 
enter  these  bytes:  E9  5E  FD 
3h)  W  (to  write  changes  to  masm.fix) 

3i)  Q  (to  exit  debug.com) 

4)  ren  masm.fix  masm.exe 

5)  Test  masm.exe  to  make  sure  changes  have  been  made  correctly. 
If  not,  copy  masm.sav  to  masm.exe  and  try  again. 


End  Listing  One 


Listing  Two 


Listing  Two 


hpkio  Basic  I/O  functions  using  handle  packing. 


Written  By  Paul  M.  Adams 
Route  4  Box  23 
Shelbyville,  KY  40065 


include  model.h 
include  prologue. h 


hcreate  (dsn,  attr) 

unsigned  char  *dsn;  /*  Data  Set  Name  */ 

int  attr;  /*  file  attribute  byte  */ 

hold  handle  -  psp  handle [19] 

psp  handle [19]  -  FF 

call  dos  to  create  file 

if  error 

retval  »  -1 

else 

retval  =  psp  handle [dos  handle] 

psp_handle[dos_handle]  -  FF 

psp_handle [19]  =  hold_handle 

return (retval)  -  real  dos  handle 

hcreate  proc 

public  hcreate 
push  es 

push  bp 

mov  bp, sp 
sub  sp,  2 

dsn  equ  [bp  +  6] 

attr  equ  [bp  +  8] 

hold_handie  equ  [bp  -  2] 

mov  ah,  62h 

int  21h 

mov  es,  bx 
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mov 

al,  byte  ptr  es:[18h  +  19] 

xor 

ah,  ah 

mov 

hold  handle,  ax 

mov 

byte  ptr  es: [18h  +  19],  Offh 

mov 

ah,  3ch 

mov 

dx,  dsn 

mov 

cx,  attr 

int 

21h 

jc 

hcreatejerror 

mov 

bx,  ax 

mov 

al,  byte  ptr  es:[bx  +  18h] 

xor 

ah,  ah 

mov 

byte  ptr  es: [bx  +  18h],  Offh 

jmp 

hcreate_done 

hcreate  error 

mov 

ax.  Off ffh 

hcreate  done: 

push 

ax 

mov 

ax,  hold  handle 

mov 

byte  ptr  es:[18h  +  19],  al 

pop 

ax 

hcreate  exit: 

mov 

sp,  bp 

pop 

bp 

pop 

es 

ret 

hcreate  endp 

;  hopen (dsn,  mode) 

;  unsigned  char  *dsn;  /*  Data  Set  Name 

*/  1 

;  int 

mode;  /*  DOS  open  mode 

*/ 

;  hold 

handle  -  psp  handle [19] 

;  psp  Handle [19)  -  FF 

;  call 

dos  to  open  file 

;  if  error 

retval  »  -1 

;  else 

retval  =  psp  handle [dos_handle] 
psp  handle [dos_handle]  -  FF 

;  psp_handle[19]  *  hold_handle 

;  return (retval)  -  real  dos  handle 

h 

open  proc 

public  ho pen 

push 

es 

push 

bp 

mov 

bp,  sp 

sub 

sp/  2 

dsn  equ  [bp  +  6] 

mode  equ  [bp  +  8) 

hold_handle  equ  [bp  -  2) 

mov 

ah,  62h 

int 

21h 

mov 

es,  bx 

mov 

al,  byte  ptr  es:[18h  +  19] 

xor 

ah,  ah 

mov 

hold  handle,  ax 

mov 

byte  ptr  es:  [18h  +  19],  Offh 

mov 

ax,  mode 

mov 

ah,  3dh 

mov 

dx,  dsn 

int 

21h 

Jc 

hopen_error 

mov 

bx,  ax 

mov 

al,  byte  ptr  es:[bx  +  18h] 

xor 

ah,  ah 

mov 

byte  ptr  es: [bx  +  18h],  Offh 

jmp 

hopen_done 

hopen  error: 

mov 

ax,  Offffh 

hopen  done: 

push 

ax 

mov 

ax,  hold  handle 

mov 

byte  ptr  es:[18h  +  19],  al 

pop 

ax 

hopen_exit: 

(continued  on  next  page) 
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Listing  Two  (Listing  continued,  text  begins  on  page  108.) 


mov  sp,  bp 

pop  bp 

pop  es 

ret 

hopen  endp 


; ;  hclose (handle) 

;;  int  handle; 

/*  File  handle  from  hopen  */  ; 

;;  hold_handle  -  psp  handle [19) 

;;  psp_handle[19)  -  Handle 

\ 

;;  call  dos  to  close  handle 

;;  if  error 

;;  retval  **  -1 

;;  else 

;;  retval  -  0 

\ 

;;  psp_handle [19)  -  hold_handle 

;;  return  (retval) 

; 

hclose  proc 

public  hclose 

push  es 

push  bp 

mov  bp,  sp 

sub  sp,  2 

handle  equ  [bp  +  6) 

hold_handle  equ  [bp  -  2] 

mov  ah,  62h 

int  21h 

mov  es,  bx 


hclose_error : 
mov 

hclose_done: 

push 

mov 

mov 

pop 


al,  byte  ptr  es:[18h  +  19) 
ah,  ah 

hold  handle,  ax 
ax,  Randle 

byte  ptr  es:[18h  +  19),  al 
bx,  19 
ah,  3eh 
21h 

hclose_error 

ax,  ax 
hclose  done 


ax,  Offffh 


ax 

ax,  hold_handle 

byte  ptr  es:[18h  +  19),  al 

ax 


hclose_exit : 

mov  sp,  bp 

pop  bp 

pop  es 

ret 

hclose  endp 


hqet (handle,  ioarea,  len) 
int  handle; 

unsigned  char  * ioarea; 
int  len; 

hold_handle  -  psp  handle [19) 
psp_Handle[19)  -  Handle 


call  dos  to  read  file 
if  error 

retval  -  -1 

else 

retval  «  number  of  bytes  read 

psp_handle[19)  -  hold_handle 
return  (retval) 


/*  File  handle  from  hopen  */ 
/*  Input  Buffer  */ 
/*  Number  of  bytes  to  read  V 
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hget  proc 

public 

hget 

push 

es 

push 

bp 

mov 

bp,sp 

sub 

sp,  2 

handle  equ 

[bp  +  6) 

get  area  equ 

[bp  +  8] 

get  len  equ 

[bp  +  10] 

hol3_handle  equ 

[bp  -  2) 

mov 

ah,  62h 

int 

21h 

mov 

es,  bx 

mov 

al,  byte  ptr  es:[18h  +  19] 

xor 

ah,  ah 

mov 

hold_handle,  ax 

mov 

ax,  handle 

mov 

byte  ptr  es:[18h  +  19],  al 

mov 

dx,  get  area 

mov 

cx,  get  len 

mov 

bx,  19 

mov 

ah,  3fh 

int 

21h 

jc 

hget  error 

Jmp 

hget_done 

hget  error: 

mov 

ax,  Offffh 

hget  done: 

push 

ax 

mov 

ax,  hold  handle 

mov 

byte  ptr  es:[18h  +  19],  al 

pop 

ax 

hget  exit: 

mov 

sp,  bp 

pop 

bp 

pop 

es 

ret 

hget  endp 

;  hput (handle,  ioarea,  len)  ;;; 

;  int 

handle;  /*  File  handle  frern  hopen  */  ;;; 

;  unsigned  char  * ioarea;  /*  Output  buffer  */  ;;; 

;  int 

len;  /*  Number  of  bytes  to  write*/  ;;; 

;  hold  handle  -  psp  handle [19]  Hi 

;  psp_Kandle[19]  -  handle  ;;; 

#  iii 

;  call  dos  to  write  file  Hi 

;  if  error  Hi 

retval  -  -1  Hi 

;  else 

Hi 

retval  -  number  of  bytes  written  Hi 

•;  psp  handle [19]  -  hold  handle  Hi 

» 

i 

;  return 

(retval)  Hi 

h 

put  proc 

liiilllilliiiiiirlltiiliwlllll 

public 

hput 

push 

es 

push 

bp 

mov 

bp,  SP 

sub 

sp,  2 

handle  equ  [bp  +  6] 

put  area  equ  [bp  +  8] 

put  len  equ  [bp  +  10] 

hole!  handle  equ  [bp  -  2] 

mov 

ah,  62h 

int 

21h 

mov 

es,  bx 

mov 

al,  byte  ptr  es:[18h  +  19] 

xor 

ah,  ah 

mov 

hold_handle,  ax 

mov 

ax,  handle 

mov 

byte  ptr  es:[18h  +  19],  al 

mov 

dx,  put  area 

mov 

cx,  put  len 

mov 

bx,  19 

mov 

ah,  40h 

int 

21h 

jc 

hput  error 

jmp 

hput_done 

(continued  on  next  page) 
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1 6-BIT 

LiStlriQ  TWO  (Listing  continued,  text  begins  on  page  108.) 

hput  error: 

mov 

ax,  Offffh 

hput  done: 

push 

ax 

mov 

ax,  hold  handle 

mov 

byte  ptr  es:(18h  +  19J,  al 

pop 

ax 

hput  exit: 

mov 

sp,  bp 

pop 

bp 

pop 

es 

ret 

hput  endp 

' 

•;  long  int  hseek (handle,  rba,  method)  ;;; 

■;  int 

handle;  /*  File  handle  from  hopen  */  ;;; 

;  long  int  rba;  /*  Relative  Byte  address  */  ;;; 

;  int 

method;  /*  Seek  method  */  ;;; 

;  hold  handle  -  psp  handle (19)  ;;; 

;  psp_Kandle[19]  -  Handle  ;;; 

;  call  dos  to  seek  to  rba  ;;; 

;  if  error 

; 

retval  -  -1  ;;; 

;  else 

... 

■; 

retval  -  seek  address  ;;; 

;  psp  handle [19]  -  hold  handle  ;;; 

;  return 

s 

(retval)  ;;; 

,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, ,,,,,,,,,,,, 

hseek  proc 

public 

hseek 

push 

es 

push 

bp 

mov 

bp.sp 

sub 

Sp,  2 

handle  equ 

[bp  +  6) 

rha  low  equ 

[bp  +  8) 

rba  high  equ 

[bp  +  10] 

seek  method  equ 

[bp  +  12] 

hold_handle  equ 

[bp  -  2] 

mov 

ah,  62h 

int 

21h 

mov 

es,  bx 

mov 

al,  byte  ptr  es:[18h  +  19] 

xor 

ah,  ah 

mov 

hold  handle,  ax 

mov 

ax,  handle 

mov 

byte  ptr  es: [18h  +  19],  al 

mov 

dx,  rba  low 

mov 

cx,  rba  high 

mov 

ax,  seeH  method 

mov 

ah,  42h 

mov 

bx,  19 

int 

21h 

jc 

hseek  error 

Jnp 

hseek_done 

hseek  error: 

mov 

ax,  Offffh 

mov 

dx,  ax 

hseek  done: 

push 

ax 

mov 

ax,  hold  handle 

mov 

byte  ptr  es:[18h  +  19],  al 

pop 

ax 

hseek  exit: 

mov 

sp,  bp 

pop 

bp 

pop 

es 

ret 

hseek  endp 

include  epilogue. h 

end 

End  Listing  Two 
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Listing  Three 


Listing  Three 
♦include  <stdio.h> 

♦define  MAXF  256 

struct  {  int  scs,  sss,  sds,  ses;  ]  sreg; 

struct  {  int  ax,  bx,  cx,  dx,  si,  di,  ds,  es;  }  dreg; 

main(argc,  argv) 
int  argc; 

unsigned  char  *argv; 

( 


int 

fid [MAXF] 

int 

i; 

int 

j; 

int 

c; 

long 

1; 

int 

lastfile; 

char 

dsn [30]; 

char 

line [80]; 

long  int  h 

segread  (&sreg) ; 
dreg. ax  =-  0x6200; 
sysint21 (fidreg,  &dreg) ; 

printf ("\nCreate  files"); 

for  (i  -  0;  i  <  MAXF  ;  i++  )  { 

sprintf(dsn,  "Wtest \\fcfc%d.dat",  i)  ; 
c  -  hcreate  (dsn,  0) ; 
fid(i)  -  c; 

printf  ("\nCreate  dsn  -  %s,  handle  -  %3d",  dsn,  c) ; 

if  (c  —  -1)  { 
break; 

) 

} 

last file  -  i; 

printf  ("\n") ; 

printf ("\nWrite  files"); 

for  (i  -  0;  i  <  lastfile;  i++  )  { 

printf ("\nWriting  file  number  %02d",  i) ; 

for (j  =■  0;  j  <  10;  j++  )  { 

sprintf (line,  "out  file  no  %03d  line  no  %02d\n\r",  i,  j) ; 
c  =  hput (f id[i) ,  line,  28); 

) 

) 

printf ("\nClose  files*); 

for  (i  -  0;  i  <  lastfile;  i++  )  ( 
c  -  hclose(fid(i] ) ; 

printf ("\nret urn  from  close  %3d  -  %3d",  i,  c  ); 


printf  ("\nOpen  files"); 

for  (i  -  0;  1  <  lastfile;  i-f-f  )  { 

sprintf  (dsn,  "WtestWfcfc%d.dat",  i)  ; 
c  -  hopen(dsn,  0); 
fid  [1)  =  c; 

printf ("\nOpen  dsn  -  %s,  handle  -  %3d",  dsn,  c); 


printf ("\nRead  files"); 

for  (i  -  0;  i  <  lastfile;  i++  )  { 

1  -  28  *  (i  %  10); 

1  -  hseek (fid [ i ] ,  1,  0); 
c  -  hget (fid[i] ,  line,  28); 
line [26]  -  0; 

printf ("\nseek  return  -  %3D,  get  return  -  %3d,  line  -  %s",  1,  c,  line); 


} 

printf ("\nClose  files"); 

for  (i  -  0;  i  <  lastfile;  i++  )  { 
c  -  hclose(fid[i] ) ; 

printf ("\nreturn  from  close  %3d  -  %3d“,  i,  c  ); 


) 


> 


End  Listings 
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RIGHT  TO  ASSEMBLE 


Listing  One  (Text  begins  on  page  1 14.) 


INFO  $Header:  worm.a-v  1.2  86/03/24  01:44:36  jans  Exp  $ 

****  ■phg  worm  Memory  Test  ****************************************** 

*  Author:  Jan  W.  Steinman,  2002  Parkside  Ct.,  West  Linn,  OR  97068. 

* 

*  The  Worn  memory  test  has  three  parts.  Init  sets  up  the  registers  for  the 

*  Worm.  The  Display  Manager  interacts  with  the  Worm  each  pass  and  periodically 

*  Displays  the  Worm's  progress.  The  Worm  itself  Worms  itself  through  memory, 

*  from  high  to  low,  checking  memory  against  a  copy  of  itself.  The  Droppings 

*  form  a  pattern  through  memory  when  the  test  is  complete. 

* 

*  This  version  runs  on  the  Tektronix  4404  under  Uniflex.  System  dependent  code 

*  is  mostly  segregated  to  the  Init,  Display,  Disable  and  Enable  routines.  Two 

*  instructions  in  the  Worm  routine  are  system  dependent,  for  enabling  and 

*  disabling  interrupts. 

* 

*  Register  usage: 

*  DO  scratch  register. 

*  D1  scratch  register. 

*  D2  scratch  register. 

*  D3  scratch  register. 

*  D4 

*  D5  address  mask  for  determining  if  time  to  show  progress. 

*  D6  base  of  memory  area  under  test. 

*  D7  length  of  Worm  in  long  words. 

*  A0  scratch  register. 

*  A1  scratch  register. 

*  A2  scratch  register. 

*  A3  pointer  to  Display  manager  for  position  independent  access. 

*  A4  pointer  to  permanent  Worm  image  for  comparison. 

*  A5  pointer  to  crawling  Worm  image. 

*  A6 

*  A7  stack  pointer. 

* 

*  These  included  files  contain  system  definitions  and  interrupt  (signal) 

*  numbers  for  the  Uni flex  operating  system.  Don't  bother  to  list  these. 

* 

OPT  lis 

DEFINE  (This  makes  all  labels  global  for  debug.) 

★ 

*  Set  D_MASK  with  the  bits  that  are  zero  at  each  progress  report. 


0000 

03FC 

D  MASK 

EQU 

$00003FC 

Report  each  boundary  passed. 

0000 

0004 

REL  SIZ 

EQU 

4 

Relocation  is  four  bytes  at  a  til 

0000 

8000 

MEM  SIZ 

EQU 

$2000*REL  SIZ 

Test  a  32K  chunk. 

0000 

0002 

DISABLE 

EQU 

2 

Trap  number  for  Disable  routine. 

0000 

0003 

ENABLE 

EQU 

3 

Trap  number  for  Enable  routine. 

0000 

000D 

CR 

EQU 

$0D 

Carriage  return. 

0000 

000A 

LF 

EQU 

$0A 

Line  feed. 

*  Uniflex  will  not  allow  intersection  math,  so  put  all  the  code  in  the  DATA 

*  section,  and  don't  use  TEXT  or  BSS  at  all! 

* 

DATA  Assemble  into  writable  data  section. 


000000  3031  3233 
000010 
000010  7407 
000012  760F 
000014  E998 
000016  2200 
000018  C283 

00001A  10FB  10E4 
00001E  51CA  FFF4 
000022  4E75 


****  hexadecimal! ze  ****************************************************** 

*  hexa decimalize  converts  a  long  word  to  eight  ASCII  hexadecimal  characters. 

*  This  routine  is  machine  and  OS  independent.  It  uses  a  simple  table  look-up 

*  to  generate  the  hexadecimal  string. 

* 

*  Entry:  dO  —  Long  word  to  be  converted  to  hex. 

*  aO  —  Pointer  to  buffer  where  hex  characters  will  go. 

*  Exit:  d2  —  -1.  (Just  in  case  someone  cares!) 

*  dO  —  unchanged. 

*  -8(a0)  —  points  to  eight  ASCII  characters. 

* 

*  Uses:  d3  —  nybble  mask:  constant  $0F. 

*  d2  —  nybble  counter. 

*  dl  —  current  nybble  to  convert  is  LSN. 

* 

CharTab  DC.B  ' 0123456789ABCDEF'  Where  we  keep  our  hex  characters. 


3435  CharTab  DC.B 
hexadecimal! ze 
move . 1 
move . 1 

HexLoop  rol .  1 


move.l  #7,d2  Bytes  to  make  -  1. 

move.l  #$0F,d3  Nybble  mask. 

HexLoop  rol.l  #4,d0  Shift  the  next  nybble  into  the  LSN,  < - 

move.l  d0,dl  make  a  copy  for  masking, 

and.l  d3,dl  mask  out  all  but  least  significant  nybble, 

*  index  into  char  table  and  store  result, 
move.b  CharTab  (pc, dl) ,  (aO)  + 

dbra  d2, HexLoop  Repeat  until  done,  and  when  done,  - 

rts  hit  the  road.  Jack.  — > 

****  Manager  ************************************************************* 

*  Manager  checks  the  Worm's  progress,  and  periodically  reports  to  the  Display. 

*  This  routine  is  also  entered  if  an  error  is  encountered. 

* 

*  Entry:  dO  —  W_LONGS  complement  of  pass  count  if  error,  else  -1. 

al  —  test  address  pass/fail  value. 
k  Exit:  via  direct  jump  to  Worm  at  (A5) . 
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Uses: 


d3,  d2,  dl,  dO,  a7,  al,  aO 
one  level,  plus  needs  of  Display. 


*  Stack: 

* 

000024  0D57  6F72  6D20  ErrMsg  DC.B  CR, 'Worm  reports  memory  error  at  ' 
000042  ErrAddrMsg 

000042  3030  3030  3030  DC.B  *00000000  on  pass  ' 

000053  ErrCountMsg 


000053 

3030 

3030 

3030 

DC.B 

'00000000.' ,CR 

0000 

0039 

E  SIZ 

EQU 

*-ErrMsg 

00005D 

0D57 

6F72 

6D20  DoneMsg 

DC.B 

CR,  'Worm  tested 

memory  from  ' 

000076 

DoneBegAddrMsg 

000076 

3030 

3030 

3030 

DC.B 

'00000000  through  ' 

000087 

DoneEndAddrMsg 

000087 

3030 

3030 

3030 

DC.B 

•00000000  successfully. '  ,CR 

0000 

0041 

D  SIZ 

EQU 

* -DoneMsg 

00009E 

3030 

3030 

3030  ProgMsg 

DC.B 

' 00000000 ',CR 

0000 

0009 

P  SIZ 

EQU 

♦-ProgMsg 

0000A8 

00 

EVEN 

(Stay  on  legal  Instruction  boundary.) 

0000A8 

4A40 

Manager 

tst  ,w 

d0  Was  loop  exited  by  error,  or  countdown? 

OOOOAA 

6A30 

bpl.s 

GetErrMsg 

Error,  go  report  it.  - 

- h 

00  00 AC 

BC8D 

cmp.  1 

a5,d6 

Countdown,  so  are  we  done  yet? 

i 

0000AE 

6708 

beq.s 

GetDoneMsg 

Yes.  Go  finish  up.  - 

-+  i 

0000B0 

200D 

move.l 

a5,d0 

No,  put  the  new  source  where  we  can 

i  i 

0000B2 

C085 

and.l 

d5,d0 

look  at  the  bottom  bits:  on  boundary?  |  | 

0000B4 

67  4A 

beq.s 

Report 

Yes,  set  up  for  progress  report.  — 

-i+i 

0000B6 

4ED5 

jmp 

<a5> 

No.  Keep  on  Crawlin'...  — > 

1 1 1 

* 

Finish  up.  Get  the  pointer  to  start  addr. 

in 

0000B8 

41Fa 

FFBC 

GetDoneMsg  lea 

DoneBegAddrMsg  (pc) ,  aO  < - 

— H  1 

0000BC 

2009 

move.l 

al,  dO 

and  the  value  to  plug  in. 

1 1 

0000BE 

6100 

FF50 

bsr 

hexadecimal ize 

which  gets  converted,  likewise,  get 

ii 

0000C2 

41FA  FFC3 

lea 

DoneEndAddrMsg (pc) , aO 

1 1 

0000C6 

203C 

0000 

8000 

move . 1 

#MEM  SIZ,d0 

the  end  address  and  its  value. 

1 1 

oooocc 

6100 

FF42 

bsr 

hexadecimal ize 

also  converted  to  hexAscii. 

1 1 

0000D0 

41FA 

FF8B 

lea 

DoneMsg  (pc) ,  aO 

Get  pointer  to  complete  done  message. 

1 1 

0000D4 

7641 

move.l 

#D  SIZ,d3 

length  of  the  done  message. 

n 

0000D6 

487A 

0050 

pea 

Exit (pc) 

push  a  return  pointer. 

1 1 

0000DA 

6034 

bra.s 

Display 

and  go  display  the  message.  - 

— i- 1 1 

* 

Make  an  error  report.  Get  message  ptr. 

1 1 1 

0000DC 

41FA 

FF75 

GetErrMsg  lea 

ErrCountMsg (pc) 

i , a0  < - 

-i  i+ 

0000E0 

0400 

0007 

sub.b 

#W  LONGS-1, dO 

convert  worm  count  to  a  pass  count. 

1 1 

0000E4 

6100 

FF2A 

bsr 

hexadecimal ize 

make  it  hex  for  Display.  < — > 

1 1 

* 

Get  addr  of  ASCII  error  addr. 

1 1 

0000E8 

41FA 

FF58 

lea 

ErrAddrMsg  (pc) , 

,a0 

1 1 
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Listing  One  (Listing  continued;  text  begins  on  page  114.) 


0000EC  70FC 
0000EE  D089 
The  Worm  Memory  Test 


#-4,d0  get  bad  long  addr  to  display, 

al,dO  less  four  to  account  for  postincrement, 

Mon  Mar  24  02:15:36  1986  page  4 


0000F0  6100  FF1E 
0000F4  41FA  FF2E 
0000F8  7639 
00 00 FA  487A  002C 
OOOOFE  6010 

000100  41FA  FF9C 
000104  200D 
000106  6100  FF08 
00010A  5188 
00010C  7609 
00010E  4855 


hexadecimal ize  make  it  hex  for  Display.  < — > 

ErrMsg (pc) , aO  Get  pointer  to  whole  err  msg, 
#E_SIZ,d3  the  size  for  the  write. 

Exit (pc)  push  a  return  pointer. 

Display  and  Display  the  message.  - 

Progress  report.  Get  message  ptr, 

ProgMsg (pc) , aO  < - 

a5,d0  load  the  checked  address, 

hexadecimal  ize  make  it  hex  for  Display.  < — > 

#8,a0  Regain  pointer  to  the  message, 

#P_SIZ,d3  get  the  size  for  the  write, 

(a 5)  push  a  return  ptr  to  the  new  Worm, 

and  drop  through  into  Display. 


****  Display  ************************************************************** 

*  Display  is  an  implement at ion-dependent  scheme  for  reporting  the  Worm's 

*  progress.  Upon  entry,  A0  contains  a  pointer  to  a  string  to  Display,  and  D3 

*  contains  the  length  of  the  string  to  Display. 

* 

*  Entry:  d3  —  number  of  bytes  to  display. 

*  aO  —  address  of  a  string  to  display. 

* 

*  Uses:  dO  —  file  descriptor  of  stdout. 

*  al  —  scratch  register  for  pointing  to  SysCall  param  block. 

* 

*  Stack:  as  needed  by  system  call. 

* 

********  BEGIN  SYSTEM-DEPENDENT  CODE  ******** 

Display  move.l  d3, - (a7)  Load  the  byte  count,  < - + 

move.l  a0,-(a7)  the  actual  string  pointer, 

move.w  #write,-(a7)  and  the  system  call  index, 

move.l  a7,a0  point  to  the  syscall  parameter  block, 

move.l  #l,d0  load  file  descriptor  for  stdout, 

SYS  indx  and  write  the  message.  < — > 

add.l  #10,  a7  Remove  the  params  from  the  stack,  and 

rts  return  somewhere.  — > 


******** 

BEG 

I  N  ! 

000110 

2F03 

Display 

move . 1 

d3,  -  (< 

000112 

2F08 

move . 1 

a0,-(c 

000114 

3F3C 

000D 

move.w 

#write, 

000118 

204F 

move.l 

a7,a0 

00011A 

7001 

move.l 

#1,  dO 

X00011C 

0000 

0001 

SYS 

indx 

000120 

DFFC 

0000 

00OA 

add.l 

#10, a7 

000126 

4E75 

rts 

*  For  lack  of  a 

better  ] 

X000128 

0000 

0005 

Exit 

SYS 

term 

******** 

END 

S  Y  i 

Terminate  this  program.  (System  dependent.) 
-DEPENDENT  CODE  ******** 


****  Disable,  Enable  ******************************************************* 

*  These  routines  provide  the  exclusion  mechanism  for  the  non-interruptible  code 

*  in  Worm  at  Crawl.  These  routines  must  execute  in  supervisor  state,  therefore 

*  they  are  executed  via  the  TRAP  exception  instruction.  Enable  requires  that 

*  D1  be  preserved  from  the  preceding  Disable. 

* 

*  Uses:  SR  —  interrupt  mask  is  raised  and  lowered. 

*  d2  —  scratch  register  for  restoring  original  interrupt  mask. 

*  dl  —  scratch  register  storage  place  for  old  interrupt  mask. 


00012C  40F9  0000  000A  Disable  move 

000132  0241  0300  and.w 

000136  027C  0300  and 

+00013A  0000  0008  0000  SYS 

000146  4E77  rtr 


000148  40C2 
0001 4A  8441 
00014C  46C2 

+00014E  0000  0008  0000 
00015A  4E77 


BEGIN  SYSTEM-DEPENDENT  CODE  ******** 
move  sr, 10  Grab  the  status  register, 

and.w  #$0300, dl  keep  only  the  interrupt  bits, 

and  #$0300, sr  and  disable  all  interrupts 

SYS  cpint,SIGTRAP2, Disable  <— > 

rtr  before  entering  critical  code  region.  — > 

move  sr,d2  Regain  the  status  register, 

or.w  dl,d2  reset  the  previous  interrupt  level, 

move  d2, sr  and  enable  the  proper  interrupts 

SYS  cpint,SIGTRAP3, Enable  <— > 

rtr  before  exiting  critical  code  region.  — > 

END  SYSTEM-DEPENDENT  CODE  ******** 


****  Worm  ************************************************************** 

*  Worm  is  a  self-modifying,  self-relocating  procedure  which  starts  at  some 

*  location  in  high  memory  and  works  its  way  down  to  its  end  address, 

*  periodically  reporting  its  progress. 

* 

*  The  loop  at  Crawl  depends  strongly  on  the  68000  prefetch  mechanism.  This 

*  loop  will  not  work  on  a  68020  machine  (which  has  a  64  entry  cache) ,  nor  on 

*  most  simulators  (which  often  do  not  bother  to  simulate  prefetch  accurately) . 

*  This  loop  will  also  not  work  with  the  TRACE  bit  set,  and  must  be  protected 

*  from  all  interrupts,  including  page  faults  in  virtual  memory  systems. 

* 

*  When  this  loop  moves  the  DBNE  long  word  at  Crawl +4,  it  overlays  the  MOVE.L 

*  and  the  CMPM.L  at  Crawl.  The  CMPM.L  is  in  the  prefetch  queue,  so  it  gets 

*  executed  even  though  its  memory  image  has  just  been  clobbered.  The  DBNE  is 

*  fetched,  and  its  execution  flushes  the  prefetch  queue  as  is  the  case  with  all 

*  branches.  Execution  continues  with  the  copy  of  the  DBNE  just  moved,  which 

*  executes  again,  branching  to  Crawl-4,  the  new  loop  location.  Note  that  the 
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00015C  3007 
00015E  204D 
000160  24 4C 
000162  43ED  FFFC 

000166  4E42 

000168  2298 
00016A  B589 
0001 6C  56C8  FFFA 

000170  4E43 

000172  598D 
000174  4E71 
000176  4ED3 


*  loop  count  gets  decremented  twice  in  this  scenario,  removing  the  need  for  the 

*  usual  predecrement  before  entering  the  loop. 


Entry:  d7  —  length  of  Worm  in  long  words. 

d6  —  base  of  memory  area  to  test. 

d5  —  address  mask  for  display  boundary. 

a5  —  first  long  word  address  of  Worm  at  present . 

a4  —  first  long  word  address  of  Worm's  original  image. 

a3  —  display  manager's  address. 

Exit:  dO  —  W_LONGS  complement  of  pass  count  if  error. 

a5  —  entry  value  less  relocation,  i.e.:  next  pass  entry  value, 
al  —  address  pass/fail  report  value. 

Uses:  dO  —  decrementing  Worm  length. 

a2  —  incrementing  COMPARE  address, 
al  —  incrementing  TO  address. 
aO  —  incrementing  FROM  address. 

Unused:  d4,  d3,  a7,  a6. 


Worm  move.w  d7,d0  Restore  the  Worm's  length, 

move.l  a5,a0  its  starting  point, 

move.l  a4,a2  and  its  original  address, 

lea  -4(a5),al  Get  the  destination  for  this  pass. 

********  begin  system-dependent  code  ******** 

trap  #DI SABLE  Don't  interrupt  this  critical  passage!  < — > 

********  END  SYSTEM-DEPENDENT  CODE  ******** 

Crawl  move.l  (a0)+,  (al)  Move  a  long  word  piece  of  Worm,  < - + 

cmp.l  (al)+,(a2)+  and  check  it  against  the  original,  I 

dbne  dO, Crawl  one  long  word  at  a  time. - + 

********  BEGIN  SYSTEM-DEPENDENT  CODE  ******** 

trap  #ENABLE  Allow  interrupts  —  critical  section  over.  < — > 

********  END  SYSTEM-DEPENDENT  CODE  ******** 

sub.l  #REL_SIZ,a5  Update  the  new  Worm  address, 
nop  keep  the  whole  thing  on  long  boundary, 

jmp  (a3)  report  to  the  Manager.  — > 


*  The  following  pattern  (which  is  notoriously  hard  on  16-bit  dynamic  RAM 

*  memories)  gets  left  in  memory  and  can  be  checked  later  if  desired. 
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RIGHT  TO  ASSEMBLE 


Listing  One  (Listing  continued;  text  begins  on  page  1 14.) 


000178 

000178  5555  AAAA 
0000  0020 
0000  0008 


Droppings 

DC.L 

W_SIZ  EQU 
W  LONGS  EQU 


$5555AAAA  Pattern  to  be  left  in  RAM. 

*-Worm  Length  of  self-relocating  code,  in  bytes 

W  SIZ/4  and  longs. 


0000  017C  Ovrly 
00017C  576F  726D  206D  LogMsg 
000190  2448  6561  6465 
0001C4  0D4D  656D  6F72 

0000  006A  L  SIZ 


****  Init  ****** ********************** ********************** ************ 

*  Init  performs  system-dependent  initialization  and  sets  up  registers  for  use 

*  of  Worm  and  Manager.  Init  then  copies  the  Worm  into  the  top  of  test  memory 

*  and  starts  the  Worm  crawling. 

* 

*  Entry:  not  applicable. 

* 

*  Exit:  a5  —  Worm's  test  image  address  at  top  of  memory  to  be  tested. 

*  a4  —  Worm's  permanent  image  address. 

*  a3  —  Manager  routine  pointer. 

*  d7  —  length  of  Worm  in  long  words. 

*  d6  —  base  of  memory  area  to  test. 

*  d5  —  address  mask  for  testing  display  boundary. 

* 

Ovrly  EQU  *  This  area  will  be  overlaid  with  the  worm. 

LogMsg  DC.B  'Worm  memory  tester,  ' 

DC.B  'SHeader:  worm.a-v  1.2  86/03/24  01:44:36  jans  Exp  $' 

DC.B  CR, 'Memory  checked  down  to  location: ', CR 
L_SIZ  EQU  * -LogMsg 

EVEN 

GLOBAL  Init 


*  First,  perform  some  system-dependent  initialization:  set  up  the  TRAPS  needed 

*  to  protect  the  Worm  from  interrupts,  protect  the  area  to  be  tested  from  page 

*  faults,  and  write  a  welcome  message. 


+0001E6  0000  0008  0000 
+0001F2  0000  0008  0000 
+0001FE  0000  0039  0000 
00020E  7001 

+000210  0000  000D  0000 


SYS 

SYS 

SYS 

move.  1 
SYS 
END 


SYSTEM-DEPENDENT 


cpint , SIGTRAP2 , Disable 
cpint, SIGTRAP3, Enable 
memman,  1 ,  MemBeg ,  MemEnd 
#1,  dO 

write,  LogMsg,  L_SIZ 


SYSTEM-DEPENDENT 


Set  up  the  exception  handlers  for  the 
interrupt  exclusion  routines. 

Protect  memory  image  from  page  faults. 
Prepare  and  write  a  stdout 
welcome  message. 


00021C 

000222 

000226 

000228 

00022C 

+000230 

000236 


00024A  4A40 
00024C  6A00  FE5A 
000250  4ED5 

0000  0252 

000252  0000  0000  0000 
0000  8000 


0  Errors  detected. 

SEGMENT  SIZES 
TEXT  SEGMENT  =  000000 
DATA  SEGMENT  =  008000 
BSS  SEGMENT  =  000000 


*  Next,  set  up  registers  that  i 

* 

move . 1 

#D_MASK,  d5 

lea 

Ovrly (pc) , aO 

move.l 

a0,d6 

lea 

Manager (pc) , ; 

lea 

Worm  (pc)  ,a4 

move . 1 

#MemEnd-W  SIZ, 

move.w 

#W_LONGS,  d7 

*  Finally,  move 

* 

the  Worm  to  th< 

move.l 

a4,  aO 

move .  .1 

a5,al 

move.w 

d7,d0 

sub.w 

#l,d0 

MoveWorm  move.l 

(aO),  (al) 

cnp.  1 

(aO)  +,  (al)  + 

dbne 

dO , MoveWorm 

tst.w 

dO 

bpl 

Manager 

jmp 

(a5) 

C_SIZ  EQU 

* -MemBeg 

DS.B 

MEM  SIZ-C  SIZ 

MemEnd  EQU 

ENDDEF 

* 

END 

Init 

Get  the  Display  address  boundary  mask. 
Load  the  lowest  address  to  test 

into  a  data  register  for  comparison, 
i3  get  the  Display  Manager's  address, 

the  Worm's  non-crawling  image  address, 
, a5  and  the  high-mem  Worm  start  address. 
Get  the  Worm's  length  in  longs. 


Get  a  copy  of  Worm's  permanent  image  pointer, 
its  test  image  pointer, 
and  its  length  in  longs. 


Move,  and  compare  < - 

a  long  word  of  the  Worm 
at  a  time.  - 


Exit  loop  by  error,  or  countdown? 
Error,  go  Report  it.  — > 
Countdown.  Start  Crawling!  — : 
(Size  of  non-relocating  code.) 


(Set  transfer  address  to  the  Init.) 


End  Listing 
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COLUMNS 


16-BIT  SOFTWARE  TOOLBOX 


MS-DOS  Books 

n  the  May  1986  16-Bit  Toolbox  col¬ 
umn,  I  briefly  reviewed  some 
books  on  MS-DOS  assembly-language 
programming.  Since  I  wrote  that  col¬ 
umn,  another  interesting  book  has 
appeared: 

Angermeyer,  John,  and  Jaeger,  Kev¬ 
in.  MS-DOS  Developer's  Guide.  India¬ 
napolis,  Ind.:  The  Waite  Group/How¬ 
ard  K.  Sams  and  Co.,  1986.  440  pages 
with  index.  $24.95. 

Compared  to  the  previous  pub¬ 
lished  efforts  on  this  topic,  this  is  a 
remarkable  book  and  is  the  first  book 
on  MS-DOS  programming  that  I  would 
actually  characterize  as  being  direct¬ 
ed  at  advanced  assembly-language 
programmers  (that  is,  typical  DDJ 
readers).  Topics  covered  that  have 
been  neglected  or  ignored  in  nearly 
every  other  book  published  to  date 
include  detailed  instructions  on  use 
of  the  advanced  features  of  MASM 
(macros  and  conditional  assembly), 
design  and  coding  of  memory-resi¬ 
dent  utilities  and  run-time  libraries, 
memory  management,  installable 
device  drivers,  local-area  networks, 
real-time  programming  under  MS- 
DOS,  disk-layout  and  file-recovery  in¬ 
formation,  and  the  functional  differ¬ 
ences  beteen  MS-DOS  versions. 

The  text  of  the  book  is  well  supple¬ 
mented  with  assembly-language  ex¬ 
amples  in  the  form  of  subroutines  or 
complete  working  programs.  The  au¬ 
thors  have  included  many  tidbits  of 
information  and  programming 
pearls  (such  as  the  method  for  remov¬ 
ing  a  memory-resident  program)  that 
are  obviously  derived  from  extensive 
personal  experience.  I  predict  that 
nearly  every  reader  of  this  column 
will  find  something  new  and  useful 


by  Ray  Duncan 


in  this  book  and  that  they  will  consid¬ 
er  it  money  well  invested. 


The  BIOS  Done  It 

The  short  description  of  my  prob¬ 
lems  with  the  PC/AT  VDISK  program 
in  the  April  1986  column  drew  a  flur¬ 
ry  of  mail  from  readers.  The  first, 
and  most  caustic,  reply  came  from 
George  Scotten  of  Springfield,  Ver¬ 
mont.  Mr.  Scotten  wrote:  "Ray  Dun¬ 
can's  column  is  a  classic  case  of  RYFM 
(read  your  fact-filled  manual)!  ...  Al¬ 
though  he  claims  that  he  and  his  co¬ 
workers  spent  a  lot  of  time  poring 
over  the  IBM  tech  ref  manual,  the 
time  might  have  been  better  spent 
reading  it.  . . .  Interrupts  Ofl-Offh  are 
listed  as  reserved  interrupts,  and 
anyone  using  a  reserved  interrupt 
deserves  what  they  get.  ...  It  only 
took  this  amateur  30  seconds  to  re¬ 
solve  his  problem. ..." 

Well,  this  letter  from  Mr.  Scotten 
rattled  me  for  a  few  minutes,  I  must 
admit.  I  leaped  out  of  my  chair  and 
consulted  my  PC/XT  and  PC/AT  tech¬ 
nical  reference  manuals  once  again. 
No,  I  wasn’t  hallucinating:  although 
the  manuals  clearly  state  that  some  in¬ 
terrupt  ranges  are  "Reserved"  (for  ex¬ 
ample,  28h  —  3fh,  40h  —  5fh,  and 
80h—85h ),  the  interrupts  Oflh  —  Offh 
are  definitely  tagged  "Not  Used”  rath¬ 
er  than  "Reserved.”  (See  PC/AT  Tech¬ 
nical  Reference  Manual,  p.  5-6,  and  PC 
Technical  Reference  2.02  Manual,  p.  2- 
8.) 

A  considerably  more  helpful  letter 
came  from  Thomas  Thurston,  of  In¬ 
tel  Corp.,  who  wrote:  ".  .  .  Actually, 
the  problem  is  not  in  VDISK  at  all  but 
in  the  PC/AT  ROM  BIOS  function  that 
VDISK  uses  to  access  extended  memo¬ 
ry  (BIOS  interrupt  15h,  function  87h, 
pp.  5-150  to  5-155  of  the  PC/AT  Techni¬ 


cal  Reference  Manual ).  This  BIOS  func¬ 
tion  creates  80286  protected  mode  de¬ 
scriptor  tables  and  then  switches  to 
protected  mode  so  that  it  can  access 
extended  memory  directly.  As  you 
noted  in  your  column,  to  get  out  of 
protected  mode,  the  BIOS  sets  a  spe¬ 
cial  value  in  the  CMOS  RAM,  outputs  a 
signal  to  cause  a  RESET,  and  then 
halts.  In  the  power-up  sequence  after 
the  RESET  signal  is  received  (pp.  5-33 
to  5-35),  the  value  from  the  CMOS  RAM 
is  checked.  If  it  indicates  that  the  RE¬ 
SET  was  caused  by  a  shutdown,  con¬ 
trol  is  returned  to  the  code  that  re¬ 
quested  the  shutdown. 

"There  are  some  side  effects  of  go¬ 
ing  through  the  RESET  sequence.  The 
registers  do  not  have  the  values  they 
had  before  the  shutdown.  In  particu¬ 
lar,  the  stack  registers  ( SS  and  SP )  are 
lost.  RESET  initializes  SS  to  0  and 
leaves  the  value  of  SP  undefined.  The 
BIOS  code  recognizes  this,  but  it  han¬ 
dles  it  in  a  way  that  causes  problems. 
After  the  power-up  code  recognizes 
that  a  shutdown  has  occurred,  before 
transfering  control  back  to  the  point 
that  requested  the  shutdown,  it  initial¬ 
izes  SS  to  0030h  and  SP  to  OlOOh  (p.  5-34 
and  p.  5-29).  This  area  of  memory  (ab¬ 
solute  addresses  300h—400h)  overlaps 
the  end  of  the  interrupt  vector  table. 
During  system  initialization,  this  isn't 
a  problem.  However,  when  the  area  is 
used  as  a  stack  during  the  RESET  se¬ 
quence  to  come  out  of  protected 
mode,  some  of  the  entries  in  the  inter¬ 
rupt  vector  table  are  trashed. 

"When  control  is  returned  to  the 
point  in  the  BIOS  code  that  requested 
the  shutdown  (p.  5-152),  one  of  the 
first  things  it  does  is  restore  the  user's 
stack  (the  values  of  SS  and  SP  were 
saved  previously).  Before  restoring 
SS  and  SP,  however,  the  code  actual¬ 
ly  does  two  procedure  calls  (which 
will  cause  two  return  addresses  to  be 
pushed  on  the  stack).  One  of  the  pro¬ 
cedures  calls  another  procedure, 
which  uses  the  stack  to  save  the  value 
of  CX.  In  all,  three  words  (6  bytes)  of 
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j  stack  space  are  used  before  the  user  | 
stack  registers  are  restored. 

"With  the  Intel  8086  architecture,  I 
i  SP  is  decremented  before  pushing 
values  onto  the  stack.  Thus  the  last  6 
|  bytes  of  the  interrupt  vector  table  are 
|  used  as  stack  space  and  destroyed  by 
this  BIOS  function.  Each  entry  in  the 
interrupt  vector  table  uses  4  bytes. 
This  means  that  the  vectors  for  inter¬ 
rupts  Ofeh  and  Offh  are  always  lost  (af¬ 
ter  a  transition  to  protected  mode 
and  back  again). 

"It  seems  to  me,  however,  that  the 
problem  is  even  more  severe  than 
this.  When  SS  and  SP  are  initialized 
by  the  RESET  sequence  (p.  5-34),  the 
interrupts  are  turned  off  before  and 
on  again  afterward.  The  reason  for 
turning  the  interrupts  off  is  to  avoid 
the  problem  of  an  interrupt  occur¬ 
ring  while  the  stack  is  in  an  unde¬ 
fined  state  (after  setting  SS  but  before 
setting  SP).  However,  it  is  not  neces¬ 
sary  to  turn  the  interrupts  off  if  SP  is 
loaded  during  the  very  next  instruc¬ 
tion  after  loading  SS  because  the  286 
always  inhibits  interrupts  until  com¬ 
pleting  the  next  instruction  after 
loading  SS. 

"In  fact,  turning  the  interrupts  off 
and  then  on  again  causes  problems 
I  because  it  leaves  the  interrupts  on  lat¬ 
er,  while  the  subsequent  code  (pp.  5- 
152  and  5-153)  assumes  that  inter¬ 
rupts  are  off.  In  the  first  place,  more 
i  than  just  the  last  entries  in  the  inter¬ 
rupt  vector  table  will  be  trashed  if 
any  interrupts  occur  before  the  us¬ 
er's  stack  is  restored.  Second,  the 
code  that  restores  the  user’s  stack 
does  not  turn  interrupts  off  when  re¬ 
storing  SS  and  SP,  and  it  executes  an 
additional  instruction  after  loading 
SS  before  loading  SP.  An  interrupt  at 
this  point  would  trash  arbitrary  loca¬ 
tions  in  the  user's  stack  segment.’1 
[These  might  overlap  and  destroy  lo- 
\  cations  in  the  user's  code  and  data  seg¬ 
ments. — Ray] 

j  Hans  Pufal,  Tom  Roberts,  and  Bob 
Sharpe,  among  others,  also  sent  de- 


and 

al.Ofh 

add 

al,90h 

daa 

add 

al,40h 

daa 

Table  1:  Pop  quiz  from  Hans  Pufal: 
What  does  this  code  do? 


tailed  explanations  of  the  VDISK  prob-  | 
lem  giving  essentially  the  same  infer- 
mation.  Hans  Pufal  threw  in  a  little  j 
conundrum  for  the  amusement  of 
DDJ  readers  (Table  1,  below),  and  Bob 
Sharpe  also  added:  "There  is  a  block 
of  interrupts  specifically  reserved  for 
user  programs  (interrupts  60h—67h). 
The  only  problem’  with  using  these 
interrupts  is  one  of  conflicting  usage 
with  other  programs  (for  example, 
the  Expanded  Memory  Manager  for 
the  Intel  Above  Board  and  other  Lo¬ 
tus/Intel/Microsoft  EMS  implementa¬ 
tions  uses  interrupt  67h).  This  need 
not  be  a  problem  for  any  application 
that  can  save  the  old  interrupt  vector, 
use  the  interrupt  during  execution, 
and  finally  restore  the  original 
interrupt. 

"It  might  be  noted  that  the  original 
PC/AT  BIOS  has  quite  a  collection  of 
errors  (for  example,  see  the  clever 
way  the  zero  flag  is  set  only  a  few 
lines  later  on  p.  5-153  and  followed  by 
/RET).  The  newer  ‘infamous’  BIOS  that 
cripples  the  system  to  a  6-MHz  clock 
rate  includes  fixes  for  nearly  all  the 
BIOS  problems  we  had  located." 

Microsoft  Macro 
Assembler 

In  my  May  1986  column,  I  noted  a 
new  problem  that  appeared  in  Ver¬ 
sion  4  of  the  Microsoft  Macro  Assem¬ 
bler  such  that  end-of-file  marks  (la/i) 
don't  seem  to  be  recognized  at  the 
end  of  include  files,  resulting  in  con¬ 
fusing  error  messages  if  the  text  file 
was  written  with  certain  editors 
(such  as  WordStar  in  nondocument 
mode).  The  technical-support  people 
at  Microsoft  have  supplied  a  patch 
that  will  correct  this  problem  (see 
Listing  One,  page  96). 

With  regard  to  another  potential 
problem,  David  Gwillim  of  Los  Ange¬ 
les  wrote:  "If  you  are  getting  strange 
errors  from  your  MASM,  or  strange  re¬ 
sults  or  even  crashes  from  your  as¬ 
sembled  and  linked  programs,  there 
is  an  insidious  bug  that  may  be 
responsible. 

"Versions  of  MASM  other  than  the 
original  IBM  MASM  1.0  all  expect  to  see 
a  CR  and  an  LF  at  the  end  of  each  line 
before  they  will  recognize  line  termi- 
!  nation.  MASM  1.0  will  work  with 
j  either. 

"The  nonacceptance  of  a  lone  CR  at 
the  end  of  a  line  where  there  is  a  com¬ 
ment  field  (which  is  most  lines  in  an 


ASM  file)  causes  the  next  line  simply  to 
become  part  of  the  comment  field  of 
the  previous  line,  effectively  remov¬ 
ing  it  from  the  assembler's  view! 

"In  the  case  where  no  LFs  are  used 
at  all,  this  will  be  immediately  obvi¬ 
ous,  but  if  there  are  just  a  few  CR- 
only  lines,  then  you  will  have  many 
strange  occurrences — symbol-not- 
defined  errors,  crashes  running  a 
program  that  looks  just  fine  in  the 
source  text,  and  so  on. 

"Because  many  text  editors  don’t 
seem  to  care  whether  there  is  an  LF 
accompanying  each  CR,  the  occasion¬ 
al  omission  of  an  LF  can  be  hard  to 
find.  One  simple  way  to  locate  these 
is  to  do  a  COPY  FILENAME.ASM  PRN,  j 
and  the  printer  will  print  the  lines 
that  don’t  have  an  LF  separating 
them  on  top  of  each  other.” 

DOS  File  Handles 

The  discussions  of  the  20-handle  limit 
in  the  December  1985  and  May  1986 
16-Bit  Toolbox  columns  generated  a 
great  deal  of  interest  and  discussion 
among  DDJ  readers.  A  particularly 
unique  work-around  was  contribut¬ 
ed  by  Paul  Adams  of  Shelbyville, 
Kentucky,  who  wrote:  "The  letter 
from  Dan  Daetwyler  quoted  in  your 
December  1985  column  was  the  first  I 
had  heard  of  MS-DOS’  limit  of  20  file 
handles  per  process.  This  came  as  an 
unpleasant  shock  to  me  because,  like 
Dan,  I  was  planning  a  database  appli¬ 
cation  that  would  certainly  require 
more  than  20  open  files.  Although, 
Dan’s  letter  left  the  impression  that 
this  restriction  is  new  with  Version  3 
of  DOS,  I  have  found  that  it  applies  to 
DOS  2.0  as  well. 

"There  is  a  way  around.  The  clue 
was  provided  in  the  January  1986  PC 
Tech  Journal.  A  Tech  Notebook  by 
Stan  Mitchell  describes  the  mecha¬ 
nism  DOS  uses  to  redirect  file  handles. 

"A  program  segment  prefix  (PSP) 
contains  a  table  of  20  bytes  starting  at 
offset  18h.  When  a  file  (or  device)  is 
opened,  the  handle  returned  by  DOS 
is  an  offset  into  this  table.  The  byte  at 
offset  18h  +handle  in  the  PSP  will  con¬ 
tain  what  I  call  the  real  handle.  The 
real  handle  represents  an  entry  in  an 
internal  DOS  table.  The  default  size  of 
this  table  allows  for  eight  real  han¬ 
dles.  This  can  be  changed  with  the 
FILES  command  in  CONFIG.SYS.  If  FILES 
=  255  is  included  in  CONFIG.SYS,  the 
real  handle  has  a  range  of  values 
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from  0  tofeh.  A  real  handle  of  ffh  al¬ 
ways  means  the  file  is  closed. 

"The  first  three  real  handles  are 
predefined  by  DOS  as: 

0 — aux  device 
!  1 — console 
i  2 — printer 

"The  result  of  this  redirection  is  to 
|  allow  child  processes  to  inherit  the 
open  files  of  the  parent  process.  The 
only  use  DOS  seems  able  to  make  of 
this  is  to  redirect  standard  input  and 
output. 

"By  the  way,  as  far  as  I  can  tell,  a 
process  is  defined  by  a  PSP.  The  cur¬ 
rently  active  PSP  can  be  determined 
by  DOS  function  62h.  The  only  way  I  j 
know  to  change  the  active  PSP  is  to 
create  a  child  process  using  DOS  func¬ 
tion  4bh.  (See  also  Ross  Nelson 's  expla¬ 
nation  of  MS-DOS  process  IDs  in  the 
May  86  column. — Ray ] 

"The  way  to  open  more  than  20 
files  from  a  single  process  is  to  trick 
DOS  into  reusing  one  of  the  table  en¬ 
tries  in  the  PSP.  I  call  this  technique 
handle  packing. 

"To  open  or  create  a  file  using  han¬ 
dle  packing: 

1.  Open  or  create  a  file  with  the  ap¬ 
propriate  DOS  handle  function. 

!  2.  The  dos— handle  is  the  handle  re¬ 
turned  by  DOS.  The  real— handle  is  the 
byte  at  offset  18h  +dos— handle  in  the 
PSP.  Save  the  real  handle  for  use 
when  performing  I/O  on  the  file. 

3.  Replace  the  byte  at  offset  18h  + 
dos— handle  with  ffh  so  the  dos— han¬ 
dle  can  be  reused. 

"For  all  other  file  functions  using  : 
handle  packing: 

1.  Save  the  real— handle  found  at  off¬ 
set  18h+19  so  it  can  be  restored  later. 

j  ( 18h+19 ,  the  last  handle  in  the  PSP  ta¬ 
ble,  was  arbitrarily  selected.) 

2.  Place  the  real— handle  of  the  de¬ 
sired  file  at  offset  18h  +19. 

3.  Move  19  to  the  bx  register  and  exe¬ 
cute  the  desired  DOS  function. 

4.  Restore  the  real— handle  that  was 
saved  in  step  1. 

"The  functions  in  HPKIO.ASM  [List¬ 
ing  Two,  page  96]  provide  the  basic 
handle-packing  I/O  system  for  use 
with  the  small-memory  model  of  Ver¬ 
sion  2.1  of  the  Computer  Innovations 


C86  compiler.  The  program  HTEST.C 
[Listing  Three,  page  101]  is  used  to 
demonstrate  the  functions.  To  try 
HTEST,  create  an  empty  \  TEST  directo¬ 
ry.  The  number  of  files  created  by 
HTEST  will  be  three  less  than  the  num¬ 
ber  of  files  specified  in  CONFIG.SYS. 

"This  solution  is  obviously  some¬ 
thing  of  a  hack  because  the  redirec¬ 
tion  scheme  is  not  documented  and 
thus  may  change  in  future  releases  of 
DOS. 

"Considering  current  develop¬ 
ments  in  mass-storage  devices,  the 
IBM  PC  family  of  machines  could  be 
used  for  some  sizable  applications. 
This  arbitrary  limit  of  20  files,  howev¬ 
er,  disqualifies  these  machines  (under 
MS-DOS,  at  least)  for  serious  database 
applications.  I  am  surprised  that  there 
have  not  been  more  complaints.  Is  I/O 
redirection  really  worth  cutting  the 
file  limit  from  255  to  20?" 

Resident  Programs 
and  File  I/O 

For  those  DDJ  readers  writing  the 
next  SideKick  or  Ready,  Gary  Cramb- 
litt  has  got  a  question  for  you:  "How 
can  a  resident  MS-DOS  program  per¬ 
form  disk  file  I/O  without  trashing 
an  existing  program  also  doing  disk  1/ 
O?  An  on-line  notepad  program,  for 
example,  allows  the  user  to  press  a 
special  key  at  any  time,  even  while 
running  some  other  program.  A  win¬ 
dow  opens  up  on  the  screen,  the  user 
enters  his  or  her  note,  and  the  note  is 
recorded  in  a  notepad  file  on  the  disk. 

"The  problem  is  that  MS-DOS  is  not 
reentrant.  When  the  user  presses  a 
special  key,  the  processor  may  be 
currently  executing  inside  an  MS-DOS 
file  I/O  routine.  If  the  on-line  note¬ 
pad  program  calls  MS-DOS  disk  I/O 
functions,  the  original  program's 
disk  I/O  will  get  trashed  or  the  com¬ 
puter  will  hang. 

‘Tve  come  up  with  several  ideas  on 
how  to  solve  this  problem,  but  so  far, 
none  of  these  solutions  is  ideal.  One 
technique  can  be  used  if  the  target 
computer  has  a  timer  hardware  in¬ 
terrupt.  The  MS-DOS  Get  Critical  Flag 
Address  function  (interrupt  Zlh, 
function  52h )  can  be  used  to  tell  when 
the  processor  is  not  executing  code 
inside  MS-DOS.  A  timer  interrupt  rou¬ 
tine  could  keep  checking  this  flag. 
When  DOS  is  no  longer  critical  (and 
therefore  is  no  longer  inside  an  MS- 
DOS  disk  I/O  routine),  then  the  note- 


!  pad  program  can  safely  request  its 
I  disk  I/O. 

"There  are  three  problems  with 
j  this  technique.  First,  it  is  hardware- 
dependent  because  you  must  have 
knowledge  of  (and  capture)  the  par-  j 
ticular  computer’s  hardware  timer  | 
!  interrupt.  Second,  the  Get  Critical 
Flag  Address  function  is  available 
only  in  MS-DOS,  Version  2,  and  later. 
(Note:  This  function  is  not  document-  | 
ed  for  PC-DOS  systems,  although  it 
seems  to  work. — Ray]  Third,  a  lot  can 
happen  between  the  time  the  user 
presses  the  special  notepad  activating 
key  and  the  time  MS-DOS  is  not  in  a 
critical  section.  For  some  applica¬ 
tions,  this  won't  be  a  big  problem. 
However,  I  have  in  mind  a  program 
to  dump  the  graphics  screen  of  my 
computer  (a  Z-100)  to  a  disk  file.  Too 
much  can  happen  on  the  screen  be¬ 
tween  the  time  the  key  to  request  the 
screen  copy  to  disk  is  pressed  and  the 
time  MS-DOS  becomes  noncritical. 

"Another  technique  for  solving  the 
reentrancy  problem  would  be  to  save 
the  notes  in  memory — like  a  special 
RAM  disk.  The  user  must  run  a  special 
program  before  shutting  off  his  or  her 
computer  to  copy  the  notes  from  the 
memory  file  to  floppy  disk.  This  solu¬ 
tion  suffers  from  two  obvious  defi¬ 
ciencies.  First,  it  requires  more  memo¬ 
ry.  Second,  if  users  forget  to  run  the 
special  program  or  if  they  lose  power, 
their  notes  are  lost  forever. 

"A  third  technique  would  be  for 
the  on-line  notepad  program  to  do  its 
own  file  handling,  reading  and  writ¬ 
ing  physical  disk  sectors  directly.  1 
think  the  problem  with  this  ap¬ 
proach  is  obvious."  DDJ  j 
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o,  this  is  not  a  method  for  quanti¬ 
fying  the  mental  retentive  pow¬ 
ers  of  certain  long,  cylindrical  inver¬ 
tebrates.  It  is  a  test  that  could  help  to 
diagnose  certain  types  of  computer 
memory  errors.  The  Worm  memory 
test  (see  Listing  One,  page  102)  uses  a 
dynamically  executing  program  as 
the  actual  test  data.  Unlike  previous 
memory  test  programs  of  this  type, 
this  worm  has  a  special  twist — it  is 
able  to  overlay  itself  while  it  is  exe¬ 
cuting,  thanks  to  the  MC68000’s  pre¬ 
fetch  register. 

Some  Fetching  Facts 

Never  heard  of  the  prefetch  register? 
To  understand  how  the  memory  test 
works,  it  might  help  to  review  the 
way  the  MC68000  fetches  and  exe¬ 
cutes  instructions.  The  MC68000  uses 
instruction  pipelining  in  order  to 
speed  execution.  There  is,  in  effect,  a 
16-bit  register  between  the  data  bus 
and  the  instruction  decoding  logic. 
When  an  instruction  is  executed,  the 
opcode  for  that  instruction  is  first 
loaded  into  the  prefetch  register  (of¬ 
ten  while  the  previously  fetched  in¬ 
struction  is  being  executed),  then  the 
instruction  is  moved  into  the  instruc¬ 
tion  decoding  register,  where  it  is  ex¬ 
ecuted.  The  net  effect  is  that  the  pro¬ 
cessor  usually  has  a  handle  on  the 
next  thing  it  is  supposed  to  do. 

Prefetch  works  fine  most  of  the 
time,  but  it  does  slow  things  down 
during  certain  operations.  If  the  in¬ 
struction  being  executed  causes  a 
nonsequential  instruction  to  be  exe¬ 
cuted,  execution  may  be  either  faster 
or  slower.  In  the  case  of  a  conditional 


by  Jan  W.  Steinman 

branch  instruction,  a  branch  taken  is 
quite  fast  because  the  prefetch  regis¬ 
ter  already  holds  the  displacement 
that  must  be  added  to  the  program 
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counter  in  order  to  fetch  the  next 
nonsequential  instruction.  A  branch 
not  taken,  however,  will  be  a  little 
faster  if  it  is  a  short  branch  because 
the  next  instruction  is  already  in  the 
prefetch  register  and  the  two  clocks 
needed  to  add  a  displacement  to  the 
program  counter  can  be  saved.  The 
worst  case  happens  when  a  branch  is 
not  taken  and  the  branch  displace¬ 
ment  is  16  bits.  In  this  case,  the  pro¬ 
cessor  has  useless  information  in  the 
prefetch  register  and  must  flush  that 
information  before  it  can  fetch  the 
next  instruction. 

Other  nonsequential  instructions 
cause  an  immediate  flush  of  the  pre¬ 
fetch  register  and  use  an  extra  four 
clocks  simply  to  restart  the  pipeline. 
One  exception  is  the  decrement-and- 
branch  instruction,  which  like  the 
taken  branches  benefits  from  having 
the  branch  displacement  handy. 
(The  MC68010,  with  its  32-bit  prefetch 
register,  actually  executes  many  16- 
bit  instructions  out  of  the  prefetch 
register  if  they  precede  a  decrement- 
and-branch  instruction.) 

How  the  Worm  Crawls 

Worm  depends  on  these  characteris¬ 
tics  of  pipelining  in  order  to  overlay 
itself  while  it  is  running,  but  it  needs 
some  management  and  control  in  or¬ 
der  to  be  useful — a  Worm  on  the 
loose  would  quickly  destroy  all  mem¬ 
ory!  Besides  Worm,  a  complete  mem¬ 
ory  test  requires  two  additional  parts: 
an  initialization  sequence  and  a  rou¬ 
tine  for  controlling  Worm  and  re¬ 
porting  its  findings. 

The  initialization  routine,  Init,  has 
some  special  characteristics  and  in¬ 
cludes  most  of  the  system  dependen¬ 
cies.  It  is  executed  only  once — at  the 
beginning — and  is  therefore  throw¬ 


away  code.  This  is  why  it  is  placed 
last — Worm  actually  crawls  right 
over  its  initialization  code  in  this  im¬ 
plementation.  The  registers  are  set 
up  to  the  specifications  of  Worm,  and 
several  important  system  functions 
are  performed.  In  particular,  it  is  im¬ 
portant  that  page  faulting  does  not 
occur  in  systems  that  support  virtual 
memory,  and  if  special  hocus-pocus 
is  needed  to  turn  off  interrupts,  it 
should  be  done  here. 

Manager  exercises  control  over 
Worm  and  is  responsible  for  commu¬ 
nicating  errors  it  discovers  and  dis¬ 
playing  progress  messages  if  desired. 
When  Manager  is  entered  upon  com¬ 
pletion  of  a  Worm  pass,  it  must  de¬ 
cide  if  it  has  been  entered  because  of 
an  error  or  simply  as  a  point  of  con¬ 
trol.  If  there  has  been  an  error,  Worm 
is  no  longer  runnable,  so  Manager 
will  have  to  report  the  error  and  ter¬ 
minate.  If  no  error  is  detected,  Man¬ 
ager  must  check  the  progress  of 
Worm  to  keep  it  from  consuming  all 
memory.  At  this  point,  Manager  can 
decide  enough  memory  has  been 
checked  to  warrant  a  progress  report 
of  some  kind. 

The  real  heart  of  the  whole  thing  is, 
after  all,  Worm.  Worm  simply  repli¬ 
cates  itself,  one  long  word  lower  in 
memory,  while  comparing  the  new 
copy  of  itself  against  the  original, 
which  never  executes.  Worm  may  be 
the  heart  of  the  memory  test,  but  the 
three  instructions  starting  at  Crawl 
are  where  the  magic  happens.  This 
loop  starts  at  the  beginning  of  Worm 
and  copies  the  first  long  word  down 
to  Worm— 4.  It  continues  with  each 
additional  long  word,  until  it  gets  to 
the  long  word  at  Crawl +4,  which  is  a 
dbne  instruction  with  its  16-bit  dis¬ 
placement.  The  preceding  move.l  and 
cmp.l  have  already  been  copied 
down. 

At  this  point,  it  becomes  a  little  dif¬ 
ficult  to  keep  track  of  what  is  data 
and  what  is  code.  When  the  move.l  is 
in  the  instruction  decode  register, 
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ready  to  be  executed,  the  following 
cmp.l  is  in  the  prefetch  register,  wait¬ 
ing  its  turn  to  be  executed.  When  the 
move.l  at  Crawl  executes,  it  moves  the 
dbne  instruction  into  the  location  it 
and  the  following  cmp.l  are  current¬ 
ly  occupying.  The  processor  has  no 
way  of  knowing  it  has  just  invalidat¬ 
ed  its  prefetch  register,  so  it  contin¬ 
ues — moving  the  cmp.l  instruction 
into  the  instruction  decode  register 
and  moving  the  following  dbne  into 
the  prefetch  register.  The  cmp.l  exe¬ 
cutes,  comparing  the  dbne  just 
|  moved  against  the  original  while 
moving  the  branch  displacement  for 
the  dbne  into  the  prefetch  register. 

Assuming  the  compare  was  suc¬ 
cessful,  the  dbne  executes,  decre¬ 
menting  do  and  branching  backward 
4  bytes  to  where  the  move.l  used  to 
be.  The  prefetch  register  is  flushed 
because  of  the  branch,  so  the  value  at 
that  location  is  loaded  into  the  pre¬ 
fetch  register  and  immediately  into 
the  instruction  decode  register.  But 
what  is  loaded?  A  copy  of  the  dbne,  j 
I  complete  with  the  same  negative  dis-  j 
placement  value.  The  condition  ; 
codes  have  not  changed,  and  the 
count  register  do  should  not  be  any¬ 
where  near  0,  so  the  copy  of  the  dbne 
gets  executed  identically  to  its  prede¬ 
cessor,  which  still  resides  in  the  next 
long  word.  The  dbne  copy  branches 
to  the  move.l  copy,  and  the  loop  con¬ 
tinues  moving  the  code  down  4  bytes. 
(See  Table  1,  above.) 

When  the  count  register  do  under¬ 
flows,  the  dbne  copy  drops  through, 
interrupts  are  enabled,  Worm’s  dy¬ 
namic  image  pointer  a5  is  adjusted  to 
point  to  the  new  Worm  copy,  and 
Worm  reports  back  to  Manager.  Note  | 
that  none  of  the  Worm  code  is  ever 
executed  before  it  has  been  com¬ 
pared  and  verified. 

It  is  vitally  important  to  disable  in-  j 
terrupts  when  the  move.l  overlays  it- 1 
self  and  the  following  cmp.l.  An  in¬ 
terrupt  at  this  point  causes  the 
prefetch  to  be  flushed  when  the  in¬ 
terrupt  is  serviced.  Upon  return  from 
the  interrupt,  the  displacement  part  j 
of  the  dbne  (hex  fffa)  will  be  fetched 
as  an  instruction.  This  will  cause  a 
"line  1111  emulator  exception”  un¬ 
less  your  system  has  a  coprocessor 
with  an  ID  code  of  7,  but  either  way 
Worm  will  be  broken  and  the  memo¬ 
ry  test  will  fail.  And  of  course,  it  is 
important  that  the  length  of  Worm 


Before 

After 

Crawl— 4 

move.l 

(a0)+,(a1) 

Crawl -2 

cmp.l 

(a1)+,(a2)+ 

Crawl  move.l 

(a0)+,(a1) 

dbne 

d0,-6  <-+ 

Crawl+2  cmp.l 

(a1)+,(a2)+ 

j 

Crawl +4  dbne 

dO,— 6- 

+ 

Table  1:  The  test  in  action 


remains  a  multiple  of  4  if  you  decide 
to  modify  it! 

Bui  What  Good  Is  It? 

I  originally  developed  the  MC68000 
Worm  test  for  an  embedded  proces¬ 
sor  application  that  was  having  dy- 
namic-RAM  refresh  problems.  It  was 
discovered  that  conventional  RAM 
tests,  which  move  smoothly  up 
through  consecutive  addresses,  were 
masking  the  problem  by  unintention¬ 
ally  providing  software  refresh.  The 
test  is  not  long  enough  to  cause  a  com¬ 
plete  cycle  of  all  a  dynamic  RAM's 
row-address-strobe  (RAS)  lines  and 
was  able  to  help  diagnose  the  prob¬ 
lem. 

In  the  form  presented,  this  imple¬ 
mentation  is  useful  primarily  as  an 
illustrative  example  of  position-inde¬ 
pendent  coding,  modular  design, 
and,  of  course,  a  unique  use  of  the 
prefetch  register.  It  could  be  put  to 
practical  use  in  several  ways. 

The  best  use  of  the  memory  test 
might  be  to  have  it  running  continu¬ 
ously,  as  a  very-low-priority  task. 
Manager  would  have  to  take  some  of 
the  responsibility  of  Init  by  allocating 
test  memory  and  restarting  Worm 
when  it  has  finished  testing  a  buffer. 
The  interrupt  disabling  code  may  be 
simpler  on  systems  without  virtual 
memory — on  the  Amiga  it  is  a  simple 
memory  store. 

Virtual-memory  systems  would 
also  need  to  add  code  to  branch 
around  the  interrupt  disabling  code 
on  the  copy  of  the  first  long  word 
only,  which  would  allow  the  memo¬ 
ry  test  to  generate  page  faults  when¬ 
ever  it  first  crosses  a  page  boundary. 
To  make  it  practical  in  such  systems, 
Manager  would  have  to  access  the 
memory-management  hardware  in 
order  to  map  faulty  virtual  locations 
to  broken  chips. 

The  Worm  routine  itself  can  hold 
much  more  code  if  desired.  I  original¬ 
ly  had  much  of  Manager 's  decision 
code  in  Worm,  which  did  speed  it  up 


but  at  the  expense  of  simplicity.  In  a 
message-based  system,  such  as  the  j 
Amiga,  Manager  could  be  totally  de-  j 
leted.  Worm  could  contain  all  the 
task  code,  merrily  crawling  through  ! 
any  available  RAM  it  could  find  and 
sending  error  reports  through  inter¬ 
task  messages — all  with  minimal  im¬ 
pact  on  the  user. 

DDJ 
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As  artificial  intelligence 
moves  more  into  the  real 
world  and  out  of  the  labo¬ 
ratory,  we  are  seeing  more 
and  more  tools  designed  to 
help  application  develop¬ 
ers  use  AI  techniques  in 
their  programs.  In  particu¬ 
lar,  PROLOG  and  expert  sys¬ 
tems  tools  seem  to  be  get¬ 
ting  hot.  Where  it  will  lead 
is  anybody's  guess — we  are 
still  far  from  true  "com¬ 
mon  sense"  AI  programs, 
and  there  are  few  products 
claiming  to  use  AI  that  are 
much  more  than  sophisti¬ 
cated  database  tools.  What 
new  developments  are  on 
the  horizon?  Will  true  AI  fi¬ 
nally  become  more  than  a 
complex  toy?  What  about 
the  poorly  understood  sis¬ 
ter  fields,  pattern  recogni¬ 
tion  and  natural-language 
interfaces? 

Intelligence  Ware  has  an¬ 
nounced  a  new  expert  sys¬ 
tems  tool,  Experteach-II,  a 
comprehensive  guide  in¬ 
cluding  complete  LISP  and 
PROLOG  interpreters  for 
the  IBM  PC.  The  product  in¬ 
cludes  on-line  and  written 
tutorials,  plus  tools  and 
source  code  for  expert  sys¬ 
tems  based  in  LISP,  PROLOG, 
dBASE  II,  or  Pascal.  It's 
priced  at  $475.  Reader  Ser¬ 
vice  No.  16. 
IntelligenceWare  Inc. 

9800  S.  Sepulveda  Blvd. 

Ste.  730 

Los  Angeles,  CA  90045 
(213)  417-8896 

PML  Systems  announces 
REAGLE  (Bionic  Evolution¬ 
ary  Algorithm  Generating 
Logical  Expressions),  a  data 


analysis  system  that  uses 
artificial  intelligence  to 
construct  rules  and  infer¬ 
ences  from  a  knowledge 
database.  BEAGLE  takes  as 
input  a  database  of  exam¬ 
ples  and  produces  both  a 
set  of  human-readable  de¬ 
cision  rules  and  a  program 
(in  FORTRAN,  Pascal,  BASIC, 
or  C)  that  expresses  the 
same  rules.  It's  $398  for  the 
IBM  PC  or  $1,198  for  the 
VAX.  Reader  Service  No.  17. 
PML  Systems 
3139  East  Almond  Ave. 
Orange,  CA  92669 
(714)  771-7744 

A  new  product  line  from 
Arity  Corp.  supports  soft¬ 
ware  development  in  PRO¬ 
LOG  on  the  IBM  PC.  The  line 
includes  five  products:  the 
PROLOG  Compiler  and  In¬ 
terpreter  for  $795,  the  In¬ 
terpreter  alone  for  $350, 
the  Expert  Systems  Devel¬ 
opment  Package  for  $295, 
the  SQL  Development  Pack¬ 
age  for  $295,  the  Arity 
Screen  Design  Toolkit  for 
$49.95,  and  the  Arity  File 
Interchange  Toolkit  for 
$49.95.  The  Combination 
Pack,  which  contains  all 
five  products,  costs  $1,225. 
Reader  Service  No.  18. 

Arity  Corp. 

358  Baker  Ave. 

Concord,  MA  01742 
(617)  371-1243 

Far  the  Macintosh 

The  WSM  Group  has  re¬ 
leased  Hyper-C  68000  for 
the  Macintosh  computer. 
Hyper-C  is  a  full  K  &,  R  C 
compiler  with  extensions 
to  allow  a  natural  interface 
with  the  Macintosh  ROM 
toolbox  routines.  Mac  tool¬ 
box  calls  are  generated  in¬ 
line,  so  there’s  no  need  for 
any  special  interfacing 
code.  Pascal  functions  can 
be  coded  in-line,  and  as¬ 
sembly  source  code  is  pro¬ 
duced  as  output.  Full  SANE 
(Standard  Apple  Numeric 


Environment)  support  is 
provided.  Hyper-C  is 
priced  at  $199.95  and  has 
no  licensing  requirements. 
Reader  Service  No.  19. 

The  WSM  Group  Inc. 

1161  N.  El  Dorado  Pi. 

Ste.  241 

Tucson,  AZ  85715 
(602)  298-7910 

Pascal  Extender  and  C  Ex¬ 
tender  from  Invention 
Software  Corp.  are  com¬ 
piled  libraries  designed  to 
simplify  the  task  of  pro¬ 
gramming  the  Macintosh 
interface  and  reduce  de¬ 
velopment  time.  They  sup¬ 
port  all  standard  toolbox 
commands  plus  add  highl¬ 
and  medium-level  routines 
for  creating  and  manipu¬ 
lating  windows,  menus, 
controls,  scrollbars,  dia¬ 
logs,  and  alert  boxes.  The 
Extender  handles  graphics 
and  text  scrolling  and  win¬ 
dow  activation.  It  fully  sup¬ 
ports  text  editing,  desk  ac¬ 
cessories,  and  graphics 
printing.  Pascal  Extender 
retails  for  $69.95;  C  Extend¬ 
er  retails  for  $129.95.  Read¬ 
er  Service  No.  20. 

Invention  Software  Corp. 
P.O.  Box  3168 
Ann  Arbor,  MI  48106 
(313)  996-8108 

For  Atari  ST 

The  Pro  Pascal  language 
compiler  from  Prospero 
Software  is  available  on 
the  Atari  ST.  It  includes 
strings,  7-  and  16-digit  pre¬ 
cision  floating  point,  sepa¬ 
rate  compilation,  and  4- 
byte  integers.  Pro  Pascal 
has  full  GEM  AES  and  VDI 
bindings.  It  costs  $149. 
Reader  Service  No.  21. 
Prospero  Software  Ltd. 

190  Castelnau 
London  SW13  9DH 
England 
011  441  741-8531 

Let's  Write  is  a  new  word 
processor  for  the  Atari  ST 


from  Mark  Williams  Co.  It 

features  advanced  text  pro¬ 
cessing,  a  spelling  checker, 
and  communications  in 
one  package.  The  editor 
gives  the  user  up  to  11  win¬ 
dows  to  view  and  change 
text  from  multiple  files. 
The  text  formatter  is  simi¬ 
lar  to  Unix’s  nroff.  Let’s 
Write  costs  $79.95.  Reader 
Service  No.  22. 

Mark  Williams  Co. 

1430  W.  Wrightwood  Ave. 
Chicago,  IL  60614 
(312)  472-6659 

Hardware  for  the  PC 

American  Computer  & 
Peripheral  has  introduced 
the  American  Abovefunc¬ 
tion  Card,  a  multifunction 
memory  board  for  Ameri¬ 
can  IBM  PC/XTs  and  compa¬ 
tibles  with  full  support  of 
Lotus,  Intel,  and  Microsoft 
expanded-memory  fea¬ 
tures.  Supporting  up  to  2 
megabytes  of  expanded 
memory,  the  Abovefunc¬ 
tion  Card  also  provides  se¬ 
rial,  parallel,  and  game 
ports  and  a  real-time 
clock/calendar.  It  includes 
a  utility  disk  that  contains 
Expanded  Memory  Man¬ 
ager,  RAM  disk,  print  buff¬ 
er,  real-time  clock/calen¬ 
dar  program,  and  example 
CONFIG.SYS  and  AUTOEXEC 
.BAT  files.  The  card  has  a 
suggested  list  price  of  $380 
with  no  RAM  or  $820  with  2 
megabytes  RAM  installed. 
Reader  Service  No.  23. 
American  Computer  & 
Peripheral  Inc. 

2720  Croddy  Way 
Santa  Ana,  CA  92704 
(714)  545-2004 

DigiBoard  has  announced 
DigiRam/3MB,  a  memory- 
expansion  board  for  the 
IBM  PC/AT  that  provides  up 
to  3  megabytes  of  error- 
checked  RAM  on  a  single 
board.  The  board  has  split 
memory  addressing,  filling 
up  to  640K  and  continuing 
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at  1  megabyte  and  up.  It  is 
user-upgradable  and  avail¬ 
able  in  any  desired  memo¬ 
ry  configuration.  Reader 
Service  No.  24. 

DigiBoard  Inc. 

6751  Oxford  St. 

St.  Louis  Park,  MN  55426 
(612)  922-8055 

Everex  Systems  has  intro¬ 
duced  an  EGA  video  card 
that  is  compatible  with  the 
IBM  Enhanced  Graphics 
Adapter,  includes  a  paral¬ 
lel  printer  port  and  256K 
display  memory  on-board, 
and  is  supplied  with  the 
company's  proprietary  EG- 
MODE  software.  The  En¬ 
hancer  board  provides 
640  X  350-resolution  graph¬ 
ics  in  16  colors  from  a  pal¬ 
ette  of  64  colors.  It  has  a 
suggested  retail  price  of 
$425.  Reader  Service  No.  25. 
Everex  Systems  Inc. 

48431  Milmont  Dr. 
Fremont,  CA  94539 
(415)498-1111 

Pacific  Data  Products  is 

offering  the  V68K  line  of  in¬ 
telligent  graphics  boards. 
These  high-resolution 


graphics  cards  are  full-size, 
IBM  PC  add-on  cards  that 
feature  palette  sizes  of  up  to 
16  million  colors,  a  Motor¬ 
ola  MC68010  video  proces¬ 
sor,  and  a  capacity  of  up  to  2 
megabytes  of  video  memo¬ 
ry.  Palettes  can  be  reloaded 
every  scan  line  with  no 
screen  performance  degra¬ 
dation.  The  boards  are  com¬ 
patible  with  the  IBM  PC,  PC/ 
XT,  PC/AT,  and  RT/PC.  The 
MC68010  video  processor 
can  perform  vector  to  ras¬ 
ter  conversion  or  other 
tasks.  Reader  Service  No.  26. 
Pacific  Data  Products 
8545  Arjons  Dr.,  Ste.  1 
San  Diego,  CA  92126 
(619)  549-0136 

Univation  has  announced 
a  new  multifunction  accel¬ 
erator  card  called  the 
Dream  Board  for  the  IBM 
PC.  It  combines  up  to  2  me¬ 
gabytes  RAM  with  a 
200—400  percent  increase 
in  speed,  serial  and/or  par¬ 
allel  ports,  a  clock/calen¬ 
dar,  an  optional  8087  math 
chip,  and  several  utilities  to 
speed  disk  I/O.  The  card  re¬ 
tails  for  $595  — $795  with 
512K  RAM,  depending  on 
options  selected.  Reader 
Service  No.  27. 


Univation 
1231  California  Cir. 
Milpitas,  CA  95025 
(408)  263-1200 

Earth  Computers’  287- 
Power-10  is  a  10-MHz  math 
coprocessor  board  for  the 
IBM  PC/AT  that  plugs  into 
the  existing  80286  socket. 
The  product  line  also  in¬ 
cludes  5-  and  8-MHz  ver¬ 
sions  of  the  board.  Prices 
range  from  $249  for  the  5- 
MHz  version  to  $695  for  the 
10-MHz  version.  Reader 
Service  No.  28. 

Earth  Computers 
P.O.  Box  8067 
Fountain  Valley,  CA  92728 
(714)  964-5784 

Networking 

ITT  has  introduced  the  Xtra 
XL,  a  high-performance  su¬ 
permicrocomputer  run¬ 
ning  both  DOS  and  Xenix. 
The  system,  based  on  the 
Intel  80286  processor,  is  de¬ 
signed  to  maximize  the 
computing  power  avail¬ 
able  to  users  operating  in 
local-area  network  and 
shared-processor  environ¬ 
ments  and  maintains  exist¬ 
ing  industry  standards. 
Xtra  XL  includes  8-MHz, 
zero-wait-state  memory; 


dynamic  disk  I/O  caching; 
an  average  hard-disk  ac¬ 
cess  time  of  28  millisec¬ 
onds;  and  an  optional 
80287  math  coprocessor.  In 
addition,  an  8-MHz  80186- 
based  communications  co¬ 
processor  offers  dramatic 
throughput  speed  in  mul¬ 
tiuser  configurations.  Mod¬ 
els  I  and  II  are  intended  for 
use  as  local-area-network 
servers  operating  under 
ITT  DOS  3.1.  Model  I,  priced 
at  $5,299,  includes  640K 
RAM,  a  1.2-megabyte  flop¬ 
py  disk,  and  a  40-megabyte 
hard  disk.  Model  II,  priced 
at  $7,299,  includes  640K 
RAM,  a  1.2-megabyte  flop¬ 
py  disk,  and  a  72-megabyte 
hard  disk.  Reader  Service 
No.  29. 

ITT  Information  Systems 
2350  Qume  Dr. 

San  Jose,  CA  95131 
(408)  945-8950 

A  local-area-network  con¬ 
figuration  for  the  AT&T 
6300  series  of  microcom¬ 
puters  has  been  an¬ 
nounced  by  The  Destek 
Group.  The  new  configu¬ 
ration  uses  industry-stan¬ 
dard  CSMA/CD  media-ac¬ 
cess  protocols  with  a 
network  bus  speed  of  2 
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megabits/second.  It  fea¬ 
tures  increased  buffer 
memory  and  circuitry. 
Prices  vary  according  to 
configuration.  Reader  Ser¬ 
vice  No.  30. 

The  Destek  Group 
830  E.  Evelyn  Ave. 
Sunnyvale,  CA  94086 
(408)  737-7211 

Network-OS  is  a  local-area- 
network  operating  system 
from  CBIS  designed  to  al¬ 
low  users  of  IBM  PCs,  PC/ 
XTs,  PC/ ATs,  and  compati¬ 
bles  to  create  microcom¬ 
puter-based  LANs.  It  is  fully 
NetBIOS/DOS  3.1  compatible 
and  can  support  all  major 
LAN  topologies  including 
token  ring.  Network-OS 
also  supports  Novell  file 
and  record  locking  and  can 
run  virtually  any  third- 
party  DOS  3.1  application. 
The  retail  list  price  of  Net¬ 
work-OS  is  $995  per  16  us¬ 
ers.  Reader  Service  No.  31. 
CBIS  Inc. 

2323  Cheshire  Bridge  Rd. 
Atlanta,  GA  30324 
(404)  634-3079 

A  simultaneous  voice/data 
multiplexer  for  use  on 
four-wire  voice  grade  lines 
is  available  from  Coherent 
Communications  Sys¬ 
tems  Corp.  The  SVD-2400 
overlays  a  full-duplex, 
2,400-bps  data  channel  to 
an  existing  leased  line,  al¬ 
lowing  it  to  support  both 
voice  and  data  traffic. 
Reader  Service  No.  32. 
Coherent  Communications 
Systems  Corp. 

60  Commerce  Dr. 
Hauppauge,  NY  11788 
(516)  231-1550 

A  high-speed,  2,400-bps, 
stand-alone  modem  de¬ 
signed  for  personal  com¬ 
puters  and  terminals  is 
available  from  Prentice 
Corp.  The  P-224  is  a  full-du¬ 
plex  modem  that  meets 


CCITT  V.22  bus  recommen¬ 
dations  and  Bell  212A  and 
103  standards  and  supports 
the  Hayes  AT  command 
set.  It  features  auto-answer 
and  auto-dial  operation 
and  can  be  used  with 
touch-tone  or  pulse-dial 
phones.  Standard  features 
also  include  automatic  bit 
rate  and  parity  selection 
and  auto-speed  recognition 
on  answer.  Reader  Service 
No.  33. 

Prentice  Corp. 

266  Caspian  Dr. 

Sunnyvale,  CA  94088-3544 
(408)  734-9810 

InterContinental  Micro 
Systems  has  released  Tur- 
boDOS/PC,  a  package  that 
runs  on  an  IBM  PC,  a  com¬ 
patible,  or  any  8086-line  mi¬ 
crocomputer  system  that 
uses  MS-DOS  or  PC-DOS,  Ver¬ 
sions  1.x,  2.x,  or  3.0.  Turbo- 
DOS/PC  allows  the  PC  to  be¬ 
come  a  TurboDOS  network 
client  and  to  access  the  disk 
drives  and  printers  belong¬ 
ing  to  the  TurboDOS  file  and 
print  servers  in  the  net¬ 
work.  The  single-copy  list 
price  for  TurboDOS/PC  is 
$100.  Reader  Service  No.  34. 
InterContinental  Micro 
Systems 

4015  Leaverton  Ct. 
Anaheim,  CA  92807 
(714)  630-0964 

Woolf  Software  Systems 
has  announced  Move-It, 
Version  4,  a  communica¬ 
tions  package  for  micro¬ 
computer  users.  The  new 
version  has  automatic  file 
compression,  keyboard 
macros,  scripting  files, 
XMODEM  protocol  support, 
infilter  and  outfitter  com¬ 
mands,  and  the  ability  to 
send  and  receive  files  auto¬ 
matically.  Move-It,  Version 
4,  retails  for  $150.  Reader 
Service  No.  35. 

Woolf  Software  Systems 
6754  Eton  Ave. 

Canoga  Park,  CA  91303 
(818)  703-8112 


A  serial  communications 
board  that  allows  users  to 
interconnect  up  to  six  IBM 
PCs,  PC/XTs,  PC/ ATs,  and 
compatibles  using  the  Easy- 
LAN  local-area  network  is 
available  from  Server 
Technology.  The  Com 
Port  Board-6  is  based  on  the 
RS-232  interface  standard 
and  works  in  conjunction 
with  the  DOS-supported 
COM1  and  COM2  ports.  By 
incorporating  a  Server  Com 
Port  Board-6  along  with  the 
DOS-supported  COM1  and 
COM2,  users  can  intercon¬ 
nect  a  total  of  eight  PCs  us¬ 
ing  EasyLAN.  If  desired,  up 
to  six  PCs  can  be  intercon¬ 
nected  to  the  Com  Port 
Board-6,  with  the  COM1  and 
COM2  reserved  for  other  se¬ 
rial  devices.  Three  boards 
can  be  accommodated  per 
PC,  allowing  up  to  18  PCs  to 
be  interconected  in  an  Ea¬ 
syLAN  network.  An  Easy¬ 
LAN  starter  kit  is  priced  at 
$179.95.  Reader  Service  No. 
36. 

Server  Technology  Inc. 

1095  E.  Duane,  Ste.  107 
Sunnyvale,  CA  94086 
(408)  738-8377 

Languages 

Clarion  from  Barrington 
Systems  is  a  structured 
programming  language 
designed  for  commercial 
applications.  Clarion  runs 
on  IBM  PCs  or  compatibles, 
requires  a  hard-disk  drive 
and  a  minimum  of  320K. 
The  utility  programs  are 
integrated;  a  single  key¬ 
stroke  can  terminate  one 
utility,  then  load  and  exe¬ 
cute  the  next.  Screen  and 
report  layouts  are  designed 
interactively.  The  entire 
package  sells  for  $295. 
Reader  Service  No.  37. 
Barrington  Systems  Inc. 

150  E.  Sample  Rd. 

Pompano  Beach,  FL  33064 
(305)  785-4555 

A  new  set  of  Forth  exam¬ 
ple  programs,  the  Forth 
Model  Library  (volumes 
1  —  3),  is  now  available 
from  the  Forth  Interest 


Group.  The  library  in¬ 
cludes  application  pro¬ 
grams  compatible  with 
Forth-83  systems  available 
from  the  most  popular 
Forth  vendors.  The  vol¬ 
umes  are  A  Forth  List  Han¬ 
dler  by  Martin  J.  Tracy,  A 
Forth  Spreadsheet  by  Craig 
A.  Lindley,  and  Automatic 
Structure  Charts  by  Kim  R. 
Harris.  Each  volume  is 
available  for  $40. 

Reader  Service  No.  38. 

Forth  Interest  Group 
P.O.  Box  8231 
San  Jose,  CA  95155 
(408)  277-0668 

Smalltalk-AT  from  Soft- 
smarts  includes  the  Xerox 
Smalltalk-80  source  code, 
the  Xerox  image,  and  Softs- 
marts'  ST-80  virtual  ma¬ 
chine.  With  Smalltalk-AT, 
users  can  run  any  applica¬ 
tion  developed  on  a  larger 
dedicated  Smalltalk  ma¬ 
chine.  It  requres  an  IBM  PC/ 
AT  with  640K  base  memo¬ 
ry,  at  least  512K  expansion 
memory,  a  Mouse  Systems’ 
three-button  mouse,  and 
i  the  IBM  Enhanced  Graph- 
1  ics  Adapter.  The  total  pack- 
I  age  price  is  $995.  Reader 
i  Service  No.  39. 

Softsmarts  Inc. 

4  Skyline  Dr. 

Woodside,  CA  94062 
(415)  327-8100 

Software  Express  has  re¬ 
leased  Version  1.6  of  Ap- 
gen,  a  fourth-generation 
language  in  the  Unix  mar- 
j  ketplace.  The  new  version 
features  a  set  of  training  tu¬ 
torials.  It  is  compatible 
|  with  all  previous  versions 
and  sells  for  $6,000.  Reader 
|  Service  No.  40. 

Software  Express 
2925  Briarpark  Dr., 

7th  Floor 
Houston,  TX  77042 
(713)  974-2298 

Star  Value  Software  has 

announced  four  software 
development  tools  for  Mo¬ 
dula-2  programmers:  Tex- 
tio,  a  display  and  printer  1/ 
O  library;  Graphix,  an  in- 
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terface  to  the  MetaWindow  system 
from  MetaGraphics;  and  Make  and 
XRef,  utilities  for  managing  large-size 
development  projects.  These  tools 
are  designed  to  work  in  conjunction 
with  the  Logitech  Modula-2/86  devel¬ 
opment  system  on  IBM  PCs  or  compa¬ 
tibles.  All  four  products  are  sold  sepa¬ 
rately  and  include  complete 
documentation.  Textio  and  Graphix 


are  $79  each;  Make  and  XRef  are  $59 
each.  Reader  Service  No.  40. 

Star  Value  Software 
12218  Scribe  Dr. 

Austin,  TX  78759 
(512)  837-5498 

Wordcraft's  C:  A  Programming 
Workshop  teaches  the  C  program¬ 
ming  language  interactively.  The 
workshop  includes  an  integrated  edi¬ 
tor  and  standard  compiler.  The  test 
module  reports  whether  a  program 


exercise  gives  correct  results.  Users 
can  also  develop  C  functions  with  no 
disk  delay.  The  Workshop  runs  on 
IBM  PCs  and  compatibles  with  19K.  It 
costs  $39.95  plus  shipping  and  han¬ 
dling.  Reader  Service  No.  41. 
Wordcraft 
3827  Penniman  Ave. 

Oakland,  CA  94619 
(415)  534-2212 

Version  1.5  of  Mystic  Pascal  from 
Mystic  Canyon  Software  features 
screen  output,  a  complete  on-line 
help  library,  and  fast  execution 
speed.  It  has  a  full-screen  editor, 
multitasking  operating  system,  ISO 
Pascal  compiler,  and  interactive  de¬ 
bugger  mode.  Users'  programs  can 
occupy  up  to  640K  of  storage  for  code 
and  data,  and  users  can  run  up  to  100 
program  sections  concurrently. 
Reader  Service  No.  42. 

Mystic  Canyon  Software 
P.O.  Box  1010 
Pecos,  NM  87552 
(505)  757-6344 

Graham  Software  Corp.  has  intro¬ 
duced  Version  1.3  of  Alice:  The  Per¬ 
sonal  Pascal.  This  version  is  compati¬ 
ble  with  industry-standard  Pascal 
compilers  and  supports  Borland  In¬ 
ternational’s  Turbo  Pascal.  Alice:  The 
Personal  Pascal  consists  of  four,  inte¬ 
grated,  computer  language  products: 
an  IBM  PC-compatible  Pascal  inter¬ 
preter,  a  language  intelligent  editor, 
on-line  help  facilities,  and  a  full-func¬ 
tion  debugging  system.  Version  1.3 
has  a  suggested  retail  price  of  $95 
(U.S.)  or  $129  (Canada).  Reader  Service 
No.  43. 

Graham  Software  Corp. 

4  Kingwood  Pi. 

Kingwood,  TX  77339 
(713)  359-1024 

Quicksilver  Software  has  released 
memory-resident  reference  guides 
for  popular  compilers.  These  refer¬ 
ence  guides  provide  clear  documenta¬ 
tion  on  the  procedural  and  syntactical 
elements  of  each  language.  The  pack¬ 
ages  require  128K  RAM,  one  disk  drive, 
and  PC-DOS  2.0  or  later.  Each  guide 
costs  $16.95.  Reader  Service  No.  44. 
Quicksilver  Software 
P.O.  Box  880887 
San  Diego,  CA  92108 
(619)  543-9896 
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SWAINE'S  FLAMES 


I've  noticed  that  all  the  best  col  unt-  ! 

nists  make  lists — lists  of  their  fa-  j 
vorite  products,  lists  of  announced  i 
but  unreleased  products,  lists  of  their 
favorite  announced  but  unreleased 
products.  I  think  I  ought  to  make 
some  lists. 

A  list  can  l>e  a  sequence,  and  a  se¬ 
quence  can  be  a  puzzle,  as  in,  What  is 
the  next  item  in  this  sequence? 


1.  00010100  00010110 
00010001  00000111 

00010110  00000001 

00001111 


MACRO 

PAR 

1FC 

f:q,*par*a 

SA6 

PAR 

ENDIF 

ENDM 

3.  while  remainder  <  >  0  do 

begin 

m  :=  n; 

n  :  =  remainder; 
remainder  ;  =  m  mod  n 

end; 

4.  PLOT  PIE 

HEADING  PAGES  OF  SOURCE  CODE' 
SHOW  SLICE  FOR  DOJ  EXPLODED 
COMBINE  SLICES  LT  5  PERCENT 
END 

Pencils  down.  Anyone  who  said  . . . 

5.  omnipotent(X) can(X,_,_). 
indestructible!  X)  :- 

not(can(_,  destroy  ,X>). 
omnipolent(god). 

?-can(god,  create,  X), 
indestructible(X). 


gets  to  stay  after  class  to  clean  erasers. 

The  sequence  was,  of  course,  first- 
through  nth-generation  language 
code.  There  is  a  clear  progression,  I 
think,  in  information  density  per 
statement  as  you  go  up  the  genera- 
!  tions.  The  progression  in  readability 
|  is  also  clear,  from  the  cryptic  bit- 
j  stream  of  first-generation  binary  to 


!  the  English-like  code  of  fourth-gener- 
|  ation  RAMIS  II. 

When  you  get  to  the  PROLOG  code, 

I  though,  the  readability  progression 
crumbles.  PROLOG  is  about  as  read-  j 
able  as  Pascal,  and  there  are  other 
reasons  to  question  PROLOG’S  position  : 
in  the  sequence. 

Given  appropriate  definitions  of  J 
create  and  destroy,  the  PROLOG  pro-  i 
gram  above  will  answer  the  ques-  j 
tion,  Can  an  omnipotent  being  create  | 
an  indestructible  object?  You  can  ac-  j 
j  tually  go  to  your  computer,  load  PRO- 
j  LOG,  key  in  this  program,  and  get  an 
answer.  Resolution  of  this  classic  an¬ 
tinomy  would  be  an  event  in  the  his¬ 
tory  of  logic,  but  I  suspect  that  my  | 
four  lines  of  code  say  more  about 
!  PROLOG’S  failures  as  a  logical  lan¬ 
guage  than  about  gods  or  logic.  Clock- 
sin  and  Mellish  also  seem  to  acknowl¬ 
edge  that  PROLOG  may  not  be  the 
j  language  of  fifth-generation  pro- 
|  gramming  by  calling  it  “a  potential 
j  basis  for  an  important  new  genera- 
|  tion  of  programming  languages. .  . .” 

I  really  don’t  think  we’re  there  yet. 

My  cousin  Corbett  has  been  telling 
me  lately  that  DDJ  needs  a  new  large 
software  project.  DDJ,  he  reminds 
me,  gave  the  first  micro  program¬ 
mers  a  language  that  would  fit  into 
their  tiny  memory  spaces  with  Tiny 
BASIC  in  1976.  Four  years  later,  the 
magazine  published  the  first  version  j 
of  Small-C,  again  shoehorning  a  lan-  ; 
guage  into  the  limited  memory  space  : 
of  micros. 

But  now  microcomputers  have  [ 
!  megabytes  of  memory  and  validated  • 


Ada  implementations.  Does  this  DDJ 
kind  of  minimization  make  sense  any 
more?  Corbett  thinks  so.  Paradoxical¬ 
ly,  he  holds  that  the  key  is  to  think  big 
about  thinking  small.  That’s  the  prin¬ 
ciple  behind  his  new  software  devel¬ 
opment  project,  for  which  he  wants 
to  solicit  programmers  through  the 
pages  of  DDJ.  There  is,  Corbett,  main¬ 
tains,  only  one  possible  next  element 
in  the  sequence  that  began  with  Tiny 
BASIC  and  Small-C:  Tiny  Star  Wars. 
Send  to  the  usual  address  for  your 
starter  disk  and  security  clearance. 

But  I  don’t  seem  to  be  getting  the 
hang  of  this  list  thing.  The  most  com¬ 
mon  kind  of  columnist  list  may  be  the 
classic  bitch  list.  The  tone  can  range 
from  Andy  Rooney-whiney  to  Ian  i 
Shoales-snarly.  Here's  my  snarl. 

I'm  tired  of  waiting  for  Alan  Kay’s  j 
Dynabook,  Ted  Nelson's  Xanadu  and 
Hypertext,  Adam  Osborne's  software 
pricing  watershed,  the  home  market, 
telecommunications  software  that 
doesn’t  push  all  the  tough  decisions 
off  on  me,  hardware  design  that 
doesn’t  penalize  me  for  being  left- 
handed.  All  the  best  programmers 
are  left-handed.  I  was  tired  of  “  near¬ 
letter  quality";  now  I’m  tired  of  I 
"near-typeset  quality."  When  will 
printers  be  good  enough  that  their  j 
manufacturers  don’t  have  to  apolo¬ 
gize  for  their  output?  I’m  tired  of 
waiting  for  Americans  to  recognize  | 
the  value  of  a  dollar  and  of  a  vote,  to  | 
stop  spending  both  on  trash,  and  to 
demand  competence  from  industry 
and  government.  Either  that  or  de¬ 
mand  printer-style  labeling:  "near- 
Sony  quality,”  ” near-Gorbachev  lu¬ 
cidity.”  And  I'm  tired  of  the  lingering 
death  of  copy  protection.  Pull  the  I 
plug  on  that  baby. 

I’m  tired.  I  gotta  go. 

'7$ •clod 

Michael  Swaine 
editor-in-chief  ! 
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EDITORIAL 


Warning:  the  fol¬ 
lowing  editori- 
|  al  contains  many  per¬ 
sonal  pronouns  used 
in  a  way  that  permits 
people  to  be  consid- 
!  ered  as  abstractions 
and  men  to  be  con- 
j  fused  with  women.  So 
far  as  1  have  been  able 
|  to  determine,  this  us- 
|  age  does  not  violate 
any  of  the  guidelines  set  forth  by  the 
;  Meese  commission  on  pornography, 
but,  just  to  be  on  the  safe  side,  anyone 
likely  to  be  offended  by  such  ideas  is 
cautioned  not  to  read  further. 

Something  has  been  puzzling  me 
about  you.  1  mean  the  plural  you,  the 
statistical  you.  After  having  hun¬ 
dreds  of  conversations  at  shows  and 
on  the  phone  and  reading  letters  and 
reader-survey  data,  I've  chewed  up 
j  all  the  scraps  of  information  I  could 
get  and  pasted  them  into  this  papier- 
niachtj  person,  this  useful  abstrac¬ 
tion,  the  Dr.  Dobb's  reader. 

!  ddj  readers  are  not  dilettantes,  not 
:  hobbyists  playing  with  the  technolo¬ 
gy.  You  are  professionals,  and  your 
knowledge  pays  your  rent.  Some¬ 
thing  about  this  has  always  puzzled 
me:  if  you're  such  serious  profession¬ 
als,  why  are  you  having  so  much  fun? 

The  answer,  I  have  decided,  has  to 
do  with  levels  of  programming 
[  knowledge.  The  first  level  is  occu¬ 
pied  by  the  programmer  with  raw 
skill.  You  know  her:  she  can  always 
shave  off  another  machine  cycle  or 
squeeze  out  another  byte.  Give  her  a 
dimension  and  she'll  optimize  along 
it.  Just  be  sure  to  tell  her  what  dimen¬ 
sion  is  important,  or  she'll  give  you 
small  when  you  need  fast  or  fast 
when  you  need  small.  Programming 
to  her  is  like  juggling  or  puzzle  solv¬ 
ing— always  a  challenge,  always  fun. 
That  spirit  was  involved  in  the  found- 
j  ing  of  this  magazine,  and  I  hope 
i  something  of  it  still  persists. 

At  a  level  above  the  enthusiast  is 
the  professional.  I  don’t  mean  that 


the  professional 
knows  more  or  is  a  bet¬ 
ter  programmer;  the 
difference  is  that  the 
professional  augments 
her  raw  skills  with  an-  j 
other  level  of  know-l¬ 
edge — judgment  about  i 
how  to  apply  those 
skills.  For  the  profes¬ 
sional,  the  task  is  not  j 
always  fun  or  chal-  I 
lenging,  however  much  it  may  chal¬ 
lenge  her  design  skills  or  her  task- 
management  abilities.  Sometimes 
what's  required  isn't  dazzle  but 
drudge  work. 

The  Dll)  readers  1  talk  with  at 
shows  are  professionals,  but  they—  : 
you — always  seem  to  be  solving  in¬ 
teresting  problems.  You  don't  seem 
bored.  You  don’t  seem  to  be  doing 
any  drudge  work.  Why  is  that? 

1  finally  figured  it  out,  and  the  an¬ 
swer  is  something  I'm  sure  you  al¬ 
ready  know:  there  is  a  level  of 
knowledge  beyond  professionalism. 

It  was  right  there  in  the  reader-sur¬ 
vey  data.  Some  of  you  run  your  own 
companies.  Others  head  design 
teams.  Many  of  you  are  simply  in  a 
position  to  call  the  shots,  to  pick  your 
own  projects. 

Just  as  the  knowledge  of  how  to  ap¬ 
ply  raw  skill  separates  the  profes¬ 
sional  from  the  enthusiast,  the  free¬ 
dom  to  decide  which  problems  to 
pursue  distinguishes  you  from  the 
professional.  Just  as  it’s  assumed  that 
the  professional  has  the  necessary 
programming  skills  for  the  job,  it’s  as¬ 
sumed  that  you  have  the  professional 
knowledge  to  decide  where  to  apply 
your  programming  skills. 

Because  you  can  choose  the  tasks, 
you  pick  tasks  you  like.  You  can  de¬ 
cide  whether  a  project  will  be  chal¬ 
lenging  or  enjoyable  enough  for  you. 

You  lucky  dog,  you. 

Michael  Svvaine 
editor-in-chief 
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RUNNING  LIGHT 


IIVES 


"Ever  since  1  firs!  saw  73  magazine  (a 

ham  radio  mag  out  of  Peterborough  NH> 
anti  noticed  that  they  used  the  radical' 
scheme  of  simply  numbering  their  issues 
sequentially  rather  than  using  a  Volume 
number  and  Issue  number,  I  have  been 
thinking  of  switching  hr  Dobbs  . .  to  rid 
ourselves  of  this  sector/byte  addressing  in 
favor  of  simple,  linear  byte  addressing." 
Jim  Warren,  DIM,  October  1976. 

"Can  you  program  a  working  tic-lac-toe 
game  in  an  hour  without  any  brafnstrain? 
Are  you  looking  for  a  way  to  make  a  living 
programming  games  and  systems  and  ex¬ 
ploring  the  strange  wonders  of  software? 
We  are  a  small  engineering  group  invent¬ 
ing  games  .  .  .  in  Crass  Valley,  California  in 
the  Sierra  foothills  an  hour  from  skiing  and 
two  hours  from  Chinese  food,"  career 
opportunity,  DDJ,  October  197H 
"Dear  Dr  Ifobb, 

1  would  like  to  express  my  opinions 
about  Ihe  two  conversion  formats  of  com¬ 
puter  address  and  data  information  cur¬ 
rently  implemented  on  nearly  all  micro1 
and  mini-computers.  1  believe  hex  lo  be 
dominant  over  octal  in  many  aspects: 

Since  all  computers  address  and  data 
word  sizes  are  in  multiples  of  four  (41  hits, 
octal  representation  often  wastes  a  digit; 
that  digit  representing  one  or  two  bits  in¬ 
stead  of  three. 

Hex  never  wastes  a  digit:  each  nibble 
(four  bils>  of  a  number  is  represented  by 
one  hex  digit. 

In  the  instance  of  the  PDP-S,  a  twelve  <  12) 
hit  mini-computer,  one  address  word  can 
be  represented  by  four  full  octal  digits 
without  waste.  But  only  three  hex  digits 
are  needed  to  stand  for  twelve  hits,  also 
without  waste. 

When  one  memorizes  an  instruction  set, 
types  in  an  object  program,  or  prints  out  an 
assembler  listing,  thousands  upon  thou¬ 
sands  11000/10001  of  wasted  characters  are 
spewed  out,  typed  in,  or  memorized  un¬ 
necessarily  when  the  octal  format  is  imple¬ 
mented  instead  of  hex  mxpeeialiy  the 
amazingly  unorthodox  "split"  octal  is  used!. 

In  conclusion,  I  would  like  to  request  that 
more  output  listings  of  assemblers  and  oc¬ 
tal  memory  dumps,  etc.  bo  hex  dumps  and 
hex  assembly  listings.  It  will  save  space  and 
time  for  all'!! 

Ilexidecimally  yours, 

Mark  J.  Nitzberg 

4D  41  52  4B  20  4A  2E  20  4E  49  54  5A  42  52  47 
1 15  101  122  113  040  1 12  056  040  116  111  124 
132  102  105  122  107 

15  South  Dr- 

East  Brunswick,  NJ  08816 
P  S.  Believe  it  or  not,  I  am  sixteen  <0fh,  026q) 
years  old  by  some  coincidence.  Also  note 
that  sixteen  more  characters  were  re¬ 
quired  to  represent  my  name  in  ASCII  octal 
than  Ilex!! 


about  some  of  these  is¬ 
sues  in  greater  detail. 


It  seems  that  we 

have  reached  the  |  -  ’Ijk, 

goal  that  the  8- and  16-  4F4* 

bit  microprocessors  of  St 

the  past  were  leading  L 
up  to:  true  32-bit  mi-  j  ^  rs 

uniprocessors,  de-  I  r**4' 
signed  with  the  pro-  S'  L  i 
grammer  in  mind.  The  t  \ 
new  generation  of  32-  \  \ 

bit  microprocessors  \\ 

have  a  lot  to  offer  pro-  L _ ...  2A _ 

gru miners  We  were  particularly  in¬ 
terested  in  what  Intel's  80386  would 
mean  to  software  developers,  and 
Ross  Nelson’s  feature  article  in  this  is¬ 
sue  represents  the  beginning  of  our 
exploration  of  programming  on  the 
80386.  In  this  and  subsequent  issues, 
we  ll  also  he  looking  at  the  oilier  32- 
bit  processors,  including  the  National 
Semiconductor  32332  and  Ihe  Motor¬ 
ola  68020. 


f;  March:  Data  compres- 

‘  sion.  Ten  years  ago, 

j.  the  challenge  was  to 

pack  significant  pro- 
,  —  jj  cessing  power  into  a 
1  *  small  amount  of  raem- 

‘  ory.  Today,  the  equiva- 

k  |  lent  challenge  may  be 

I _ I  4  to  rapidly  move 

masses  of  information  over  narrow 
channels.  Article  deadline:  Novem¬ 
ber  1,  1986. 

April:  Artificial  intelligence.  Will  ma¬ 
chine  learning  be  the  next  big  tiling 
in  practical  AI,  as  At  pioneer  Patrick 
Henry  Winston  believes?  Deadline: 
December  1,  1986. 

May:  Arts  and  sciences.  We’ll  look 
into  computers  and  music,  and  pro¬ 
gramming  for  scientific  applications. 
Deadline:  January  1,  1986. 

June:  Our  annual  telecommunica¬ 
tions  issue.  Deadline:  February  1, 


We  get  a  lot  of  letters,  telephone 
calls,  and  E-mail  messages  from  read¬ 
ers  asking  to  see  more  articles  on  a 
specific  topic.  Why  don’t  you  support 
OS-9?  When  are  you  going  to  publish 
something  on  the  Atari  ST?  How 
about  more  Unix  lor  FORTRAN  or 
80386)  coverage?  In  fact,  we  have 
plans  to  cover  all  those  topics  in  up¬ 
coming  issues,  but  you  should  under¬ 
stand  that  how  well  and  how  fre¬ 
quently  we  cover  your  favorite  topic 
depends  on  you:  almost  all  our  arti¬ 
cles  are  produced  by  our  readers. 

There  are  a  number  of  topics  that 
were  particularly  interested  in.  Do 
any  of  these  areas  match  your  exper¬ 
tise  and  interest?  Scientific  comput¬ 
ing.  Fourth-generation  languages. 
Programming  and  the  80386.  The 
68000  machines:  Macintosh,  Atari  ST, 
Commodore  Amiga;  and  the  68020 
machines,  like  the  Mustang  020.  OS-9. 
Versa  DOS.  The  Hvpercube.  Graphics 
techniques.  Pattern  recognition.  Ma¬ 
chine  learning.  Do  you  have  an  idea? 
Give  me  a  call. 

Here's  what’s  coming  up  early  in 
1987.  in  future  months,  I  ll  lie  talking 


We  also  want  to  broaden  our  lin¬ 
guistic  horizons  in  1987,  so  don’t  be 
shy  about  sending  in  Pascal  code,  or 
FORTRAN,  or  LISP,  or  whatever.  If  you 
have  an  article  idea,  call  me  at  (415) 
366-3600  and  we  ll  discuss  it. 


Nick  Turner 
editor 
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Carew’s  Flames 

Dear  DDJ, 

David  Carew,  author  of  the 
June  Viewpoint,  "What's 
Wrong  with  C,”  may  be  in¬ 
terested  to  note  that  my  C 
compiler  (Manx  Aztec)  for 
the  IBM  PC  produces  identi¬ 
cal  code  for  the  two  frag¬ 
ments  he  supplies: 

b  =  ++i 

or 

i  =  i  +  l 
b  =  i 

One  of  Mr.  Carew’s  main 
points  in  attacking  C  is  that 
the  former  produces  "radi¬ 
cally  better  code.”  Obvi¬ 
ously  it  does  not. 

Mr.  Carew  is  right  in  his 
contention  that  C  code  can 
be  difficult  to  understand 
and  to  maintain  (although 
this  is  hardly  news).  C  code 
can  also  be  elegant  and 
quite  portable.  I  have  con¬ 
verted  several  programs 
written  by  others  for  use 
with  my  particular  compil¬ 
er  (some  from  Unix  and  CP/ 
M)  and  have  had  very  little 
difficulty  understanding  or 
maintaining  the  code 
involved. 

Perhaps  the  most  confus¬ 
ing  aspect  of  Mr.  Carew's 
article  is  his  comparison  of 
the  output  of  C  compilers 
to  that  of  "an  average  pro¬ 
duction-quality  optimizing 
compiler.”  Is  there  a  word 
missing  from  this  phrase? 
Presumably  these  compil¬ 
ers  are  compiling  some¬ 
thing.  Tradition  suggests 


that  it  would  be  source 
code  in  some  language.  Ap¬ 
parently  Mr.  Carew  thinks 
that  some  other  high-level 
language  produces  tighter 
and  faster  code  than  C  does 
but  is  hesitant  to  name  it. 
We  can  only  guess  his  rea¬ 
son  for  this. 

Given  that  you  have  an 
application  to  write,  the 
application  will  perform 
the  same  tasks  no  matter 
what  language  it's  written 
in.  The  speed  and  compact¬ 
ness  of  the  code  are  there¬ 
fore  a  function  of  the  quali¬ 
ty  of  the  compiler,  not  of 
the  language.  In  my  own 
very-high-level  language 
(BOB),  you  can  issue  simple 
statements  such  as  compile 
standard  mailing  list  or 
compile  standard  Word¬ 
Star  clone  and  the  compiler 
does  the  rest.  The  code  pro¬ 


duced  rivals  that  of  the 
very  best  assembly-lan¬ 
guage  programmers  or  op¬ 
timizing  compilers.  Unfor¬ 
tunately  the  compiler  (also 
called  Bob)  is  often  struck 
by  periods  of  existential 
ennui  during  which  he  is 
unable  to  compile  any¬ 
thing  but  is  still  able  to  code 
in  C  and  leave  things  up  to 
another  somewhat  less  in¬ 
telligent  but  much  faster 
compiler. 

Dr.  Bob 

444  Maple  Ln. 

St.  Paul,  MN  55126 

Dear  DDJ, 

As  a  professional  program¬ 
mer — one  of  Bill  Gates’ 
crew,  in  fact — I  feel  called 
upon  to  respond  to  David 
Carew's  article,  "What’s 
Wrong  with  C,"  in  the  June 
1986  issue.  Having  used  C 


extensively  in  the  past  five 
years,  I  will  readily  admit 
that  the  language  is  not 
without  its  deficiencies. 
Mr.  Carew,  however,  has 
not  mentioned  any.  He 
confuses  bad  C  compilers 
and  bad  programmers 
with  flaws  in  C. 

"C  simply  doesn’t  allow 
the  use  of  standard  compil¬ 
er  optimization  tech¬ 
niques."  This  statement 
certainly  comes  as  a  sur¬ 
prise  to  the  programmers 
who  wrote  the  optimizer 
for  the  Microsoft  C  compil¬ 
er.  They  were  under  the 
impression  that  detection 
of  common  subexpres¬ 
sions,  constant  folding,  and 
peephole  optimizations 
such  as  redundant  jump 
elimination  were  standard 
optimization  techniques. 
These  are  just  some  of  the 
optimizations  that  the  Mi¬ 
crosoft  C  compiler  does, 
and  it  is  not  the  only  opti¬ 
mizing  C  compiler  avail¬ 
able,  either.  It  is  true  that 
certain  constructs  in  C  can¬ 
not  be  optimized  safely, 
but  these  are  the  very  con¬ 
structs  that  produce  effi¬ 
cient  code  when  used 
properly.  Further,  there  is 
nothing  to  prevent  a  pro¬ 
grammer  from  writing  C 
code  using  the  "vanilla" 
constructs  that  are  also 
found  in  Pascal,  and  there 
is  nothing  to  prevent  a 
good  C  compiler  from  per¬ 
forming  sophisticated  opti¬ 
mizations  on  such  code. 

C  is  "inefficient  com¬ 
pared  with  the  output  of 
an  average  production- 
quality  optimizing  compil¬ 
er.”  Mr.  Carew  makes  this 
bold  statement,  but  he  of¬ 
fers  no  facts  to  back  it  up.  I 
might  as  well  say  that  I 
think  people  from  Colora¬ 
do  tend  to  make  more  un¬ 
founded  statements  than 
do  people  from  Washing¬ 
ton.  I  present  Mr.  Carew  as 
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evidence.  One  example  is 
hardly  conclusive,  but  it  is 
far  better  than  nothing. 

"C’s  operator  set  is  too 
rich."  You  might  as  well 
say,  "The  English  language 
is  too  rich."  As  with  any 
language,  natural  or  other¬ 
wise,  sensible  people  will 
use  only  those  constructs 
with  which  they  are  famil¬ 
iar.  Shakespeare  and  Chur¬ 
chill  used  English  far  better 
than  I  do.  What  a  loss  if 
they  had  been  forced  to 
write  at  my  level! 

"I  am  often  struck  by  the 
impression  that  a  given  C 
program  is  an  elegant  ex¬ 
ample  of  C  and  its  opera¬ 
tors  but  misses  the  point  as 
a  solution."  Perhaps  Mr. 
Carew  has  never  read  any 
C  written  by  competent 
programmers.  A  poor 
choice  of  algorithms  makes 
for  an  inelegant  solution 
no  matter  what  language  is 
being  used.  A  programmer 
who  becomes  "distracted 
from  the  task  of  contriving 
an  optimal  solution  to  the 
problem  at  hand”  is  an  un¬ 
professional  program¬ 
mer — a  hacker. 

"When  one  construct 
generates  radically  better 
code,  it  is  natural  for  the 
programmer  to  expend  ef¬ 
fort  optimizing  his  or  her 
use  of  the  programming 
notation.”  If  true,  this  is  a 
valid  point.  It  is  simply  not 
true,  however.  I  present 
Mr.  Carew’s  examples  and 
the  corresponding  code 
generated  by  the  Microsoft 
C  compiler  (Version  3.00): 

b  =  +  +i; 

inc  WORD  PTR  [bp— 2]  ;i 
mov  ax, [bp— 2]  ;i 

mov  [bp— 4], ax  ;b 

i  —  i  +  1; 

inc  WORD  PTR  [bp  -  2]  ;i 
b  =i 

mov  ax, [bp— 2]  ;i 

mov  [bp— 4], ax  ;b 


As  you  can  see,  the  code  is 
identical. 

"Better  algorithms  and 
data  structures  are  far 
more  important  than  is  ide¬ 
al  use  of  a  complex  pro¬ 
gramming  notation."  Of 
course.  What  is  Mr.  Carew’s 
point?  Will  reading  Ker- 
nighan  and  Ritchie  some¬ 
how  destroy  a  program¬ 
mer's  judgment?  The 
example  Mr.  Carew  gives  is 
meaningless.  Any  pro¬ 
grammer  who  would 
choose  a  selection  sort  over 
quicksort  when  sorting 
more  than  a  few  dozen  ele¬ 
ments  is  not  a  good  pro¬ 
grammer.  Does  it  matter 
what  language  is  being 
used?  Would  Mr.  Carew 
care  to  wager  that  a  careful¬ 
ly  coded  quicksort  in  com¬ 
piled  BASIC  will  beat  a  care¬ 
fully  coded  quicksort  in  C? 

"The  investment  in 
learning  C  is  so  high.” 
Again  a  statement  made 
with  no  support.  I  can 
speak  only  from  personal 
experience.  C  was  the  first 
structured  language  I 
learned.  It  took  me  a  day  or 
two  to  begin  writing  cor¬ 
rect  code.  My  major  obsta¬ 
cle  was  poor  diagnostic 
messages  from  the  compil¬ 
er.  This  is  a  compiler  im¬ 
plementation  issue,  not  a 
language  issue.  I  do  not 
think  my  experience  was 
either  unreasonable  or 
atypical.  Of  course,  learn¬ 
ing  to  use  any  language 
well  takes  more  than  a  cou¬ 
ple  of  days. 

Mr.  Carew's  complaints 
are  misdirected.  They  ap¬ 
ply  to  poor  C  compilers 
and  poor  programmers  but 
not  to  the  C  language.  Mr. 
Carew  invites  controversy 
by  making  statements 
without  attempting  to  pro¬ 
vide  any  substantiation. 
The  gentleman  is  certainly 
entitled  to  his  opinions,  but 
by  failing  to  support  them, 
he  sounds  like  a  crank  up 
on  a  soapbox. 

The  opinions  expressed 


herein  are  my  own  and  do 
not  necessarily  reflect 
those  of  my  employer. 

Pete  Stewart 
Microsoft  Corp. 

16011  N.E.  36th  Way 
P.O.  Box  97017 
Redmond,  WA 
98073-9717 

Dear  DDJ, 

I  am  concerned  about  your 
Viewpoint  forum.  As  an 
educated  DDJ  reader,  I  ex¬ 
pect  copious  facts  or  obser¬ 
vations  to  support  a  posi¬ 
tion  presented.  D.  Carew 
presents  unsupported  as¬ 
sertions.  The  "brutal  fact” 
is  that  no  DDJ  quality  exam¬ 
ples  of  optimizing  compil¬ 
ers  vs.  C  were  given.  Sec¬ 
ond,  he  suggests  that 
mediocrity  is  better  than 
elegance  or  efficiency.  Can 
he  be  serious?  Would  you 
adopt  his  view?  I  wouldn't. 
Dr.  Barr  E.  Bauer 
9  Stone  Ave. 

Elmwood  Park,  NJ  07407 

David  Carew  replies: 

Dr.  Bauer  believes  that  I 
suggested  mediocrity  is 
better  than  elegance  and 
efficiency.  I  did  not  mean 
to  do  so.  I  did  mean  to  sug¬ 
gest  that  productivity  is 
better  than  elegance  and 
efficiency,  with  the  provi¬ 
so  that  in  general  efficien¬ 
cy  is  not  sacrificed  when  C 
is  given  up  and  that  ele¬ 
gance  is  much  in  the  eye  of 
the  beholder. 

It  is  perhaps  lame  to 
point  the  finger  elsewhere 
in  defending  one's  own 
viewpoint.  In  my  original 
submission,  however,  I 
had  at  least  one  example 
cited  and  made  mention  of 
Modula-2,  Edison,  Occam, 
and  (I  believe)  Ada  as  alter¬ 
natives  available  for  micro¬ 
computers  that  may  be 
more  productive  than  C,  or 
more  efficient  than  C,  or 
both.  The  copy  I  refer  to 
was  cut  out  of  the  final 
piece.  Perhaps  this  was 
done  because  examples  are 


so  obvious  and  plentiful. 
Almost  everywhere  you 
look,  you  can  find  exam¬ 
ples  of  optimizing  compil¬ 
ers  with  higher  level  syn¬ 
tax  that  equal  or  beat  C  in 
standard  benchmarks. 

In  addition  to  those  men¬ 
tioned  above,  the  VMS  ba¬ 
sic  compiler  beats  portable 
C  on  the  VAX.  On  virtually 
every  operating  system 
that  has  them  to  compare 
(except  Unix!),  hoary  old 
FORTRAN  and  even  COBOL 
can  be  found  outbench- 
marking  C. 

In  fact,  what  you  get 
when  choosing  C  is  porta¬ 
bility  and  a  certain  low-lev- 
el,  "no-limits-on-what-I- 
can-do”  feeling.  (Perhaps 
this  is  what  people  mean 
when  they  rhapsodize 
about  C's  "power”  and  “el¬ 
egance.”)  From  1975  to  per¬ 
haps  1984  or  1985,  this  was 
indeed  a  rare  combination. 
It  is  now  not  so  rare.  All 
choices  are  trade-offs. 
What  you  give  up  in  choos¬ 
ing  C's  portability  and 
"power/elegance”  is: 

1.  Efficiency  of  the  compil¬ 
er's  output  object  code. 

2.  Productivity  considering 
the  entire  life  cycle  of  the 
software  (80  percent  main¬ 
tenance,  remember!). 

It  is  curious  to  me  that  ev¬ 
eryone  seems  willing  to 
concede  point  2,  which  is 
much  more  important  in 
terms  of  total  dollars  cost, 
while  stongly  denying  that 
point  1  has  any  validity. 

As  for  the  embarrassing 
fact  that  my  example  C 
fragments  produce  identi¬ 
cal  code,  I  can  only  say  that 
it  proves  the  obvious:  I  am 
no  C  wizard.  The  basic 
point  is  that  C  is  a  notation 
that  favors  powerful  com¬ 
plexity  over  optimizable 
simplicity.  Those  more  fa¬ 
miliar  with  C  can  surely  fill 
in  a  good  example  for  my 
bogus  one.  The  expert's 
terse  and  idiomatic  C  does 
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produce  better  results  than 
the  beginner’s  C,  coded  as 
though  it  were  Pascal.  Ex¬ 
pert  and  beginner  alike 
may  well  have  a  tendency 
to  spend  time  exploring 
and  exploiting  the  complex 
notation  and  the  preproces¬ 
sor  at  the  expense  of  mas¬ 
tering  the  application 
problem. 

Who  is  DDJ  for? 

Dear  DDJ, 

I’m  not  a  serials  cataloger, 
but  I  do  sympathize  with 
Dave  Sullivan’s  comments 
in  the  July  issue's  Letters 
column.  Presumably,  fre¬ 
quent  variations  in  the  title 
of  a  journal  are  a  valuable 
marketing  tool,  but  they 
are  also  a  librarian's  night¬ 
mare.  It  is  all  the  more  ag¬ 
gravating  because,  as  far  as 


I  can  tell,  the  editorial  con¬ 
tent  of  the  journal  has  not 
changed  as  much  as  the  ti¬ 
tle  has. 

Putting  all  that  aside,  I 
wouldn't  miss  a  single  is¬ 
sue.  Even  though  I  am  not  a 
professional  programmer, 
more  of  what  I  am  interest¬ 
ed  in,  and  need,  is  in  DDJ 
than  in  any  other  source. 
Whatever  it  is  you’re  doing, 
please  keep  it  up.  Just  cool  it 
on  the  title  changes,  OK? 
Bruce  B.  Cox 
Automation  Committee 
Linda  Hall  Library 
5109  Cherry  St. 

Kansas  City,  MO  64110 

OS-9  Bugs 

Dear  DDJ, 

I  must  respond  to  the  letter 
written  by  Tim  Harris  of 
Microware  Systems  Corp. 
that  appeared  in  May's 
DDJ.  I  took  a  chance  on  a 
medium-size  project  that 


involved  porting  a  DBMS  to 
a  multiuser  environment 
under  OS-9.  Although  I 
agree  that  the  design  inten¬ 
tion  of  OS-9  is  decent,  the 
implementation  is  poor, 
laden  with  bugs,  and 
backed  with  poor  custom¬ 
er  service.  I  have  com¬ 
plaints  about  both  OS-9’s 
operating  system  and  its 
implementation  of  C. 

The  OS-9  disk  formatter 
utility,  for  example,  has  a 
bug  that  prevents  it  from 
being  used  with  more  than 
one  sector  per  allocation 
cluster.  This  is  not  docu¬ 
mented,  Microware  has  no 
intention  of  repairing  this 
bug  before  the  next  re¬ 
lease,  and  it  cost  me  several 
days  of  my  time.  OS-9  has  a 
flawed  file  system,  and  the 
disk-access  method  used 
by  OS-9  is  also  extremely 
slow.  I  benchmark  it  at 
from  1  to  100  times  slower 
than  equivalent  Unix  ma¬ 
chines.  The  idea  of  build¬ 
ing  a  disk-intensive  appli¬ 
cation  for  a  client  on  OS-9 
makes  me  shudder. 

Now  for  the  real  prob¬ 
lems.  The  C  compiler  and 
its  associated  library  are 
full  of  bugs.  Last  Friday  I 
lost  half  a  day  because  the 
library  function  t sleep (  ), 
which  supposedly  pro¬ 
vides  timed  delays,  is  high¬ 
ly  nonlinear  in  its  function 
and,  at  some  point  deter¬ 
mined  by  the  system  clock 
speed,  suffers  from  a  dis¬ 
continuity  that  severely 
shortens  the  response 
time.  I  was  using  this  func¬ 
tion  to  determine  whether 
a  multicharacter  key  had 
been  pressed  on  the  key¬ 
board  and  was  attempting 
to  wait  a  hundredth  of  a 
second — instead  the  wait 
was  approximately  1/3,000 
of  a  second.  This  behavior 
is  not  documented. 

Earlier  last  week  I  ran 
into  a  problem  with  the  *  = 
operator  used  with  a  vari¬ 
able  of  type  long  that  com¬ 
pletely  hung  the  system.  I 
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lost  half  a  day  tracking  that 
down.  The  week  before 
that,  I  ran  into  a  bug  in 
which  floating-point  cast 
to  integers  fail  to  trigger  an 
ifl )  expression  correctly. 
Some  problem  crops  up 
once  or  twice  a  week  with 
this  compiler  or  its  library. 

The  current  compiler  re¬ 
lease  came  out  in  Febru¬ 
ary.  The  previous  compiler 
was  worse.  If  you  used  pa¬ 
rentheses  in  a  certain  way, 
it  would  get  lost  and  not 
even  perform  integer  divi¬ 
sion  correctly. 

My  biggest  complaint  is 
that  Microware  will  not 
remedy  what  is  broken.  Ifl 
get  stuck,  it  will  not  fix  the 
broken  compiler  and  ship 
me  an  update.  It  claims  it  is 
too  big  to  be  bothered  with 
sending  out  updates  be¬ 
tween  major  releases.  My 
claim  is  that  its  software  is 
too  broken  not  to. 

Beware  of  OS-9  if  you 
value  your  business  and 
your  sanity. 

Heitzso 

MetaMedia  Inc. 

P.O.  Box  292 

Atlanta,  GA  30301 

Correction 

Listing  Seven  of  the  August 
1986  C  Chest  contained  a 
bug  that  could  cause  the  in¬ 
sert  function  to  fail  on  an 
attempt  to  insert  a  conflict¬ 
ing  node.  To  fix  the  prob¬ 
lem,  add  the  line  h  =  0;  im¬ 
mediately  below  line  68 
(page  92). 

DDJ 
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We've  opened  a  new  section 
on  the  SlG  called  TEACHING / 
LEARNING.  The  message 
board  of  this  section  is  a 
place  where  expert  pro¬ 
grammers  can  give  advice 
to  absolute  beginners. 
(Where  would  you  begin ? 
Which  language ?  What 
books?)  It's  also  for  experi¬ 
enced  programmers  who 
wish  to  learn  a  new 
language. 

The  Data  Library  will  pri¬ 
marily  contain  threads 
from  the  board  and  refer¬ 
ence  lists. 

— Levi  Thomas  (* SYSOP) 

C  Chest 

The  following  discussion 
took  place  on  our  C  Chest 
message  board  on  the  DDJ 
Forum: 

*■.  3092  Sl/C  Chest 
Fm:  Bill 
To:  all 

I'm  at  that  stage  of  experi¬ 
ence  with  C  where  I  learn 
about  the  language  mostly 
by  analyzing  my  mistakes. 
Here's  one  I  need  some 
help  with.  Yesterday  I  en¬ 
countered  what  I  thought 
was  a  compiler  bug  in  Az¬ 
tec  C86. 1  was  getting  "sym¬ 
bol  re-definition  errors" 
for  the  second  declaration 
of  errorvar  in  a  piece  of 
code  typified  by  the  fol¬ 
lowing  fragment: 

int  fnl  ( ) 

{ 

int  errorvar  ; 
int  dummy  var  ; 
fn2  (dummyvar) ; 

} 

void  fn2  (errorvar) 
int  errorvar  ; 

{ 

} 

Manx's  explanation: 
"That's  not  a  bug;  it’s  a  fea¬ 
ture"  (of  the  language).  The 
(legitimate)  error  message 


was  actually  produced  by 
my  redefinition  of  fnZ;  that 
Aztec  C86  didn't  detect  and 
flag  it  until  the  following 
line  was  "interesting.”  I’d 
be  inclined  to  agree  with 
that;  in  fact,  after  several 
hours  of  tearing  my  hair 
and  several  more  trying  to 
reach  Manx  by  phone,  I 
might  have  used  a  slightly 
stronger  adjective.  To  con¬ 
tinue  with  the  explanation: 
"Because  fnZ  wasn't  for¬ 
mally  declared  before  be¬ 
ing  invoked,  it  defaults  to 
int.  The  later  declaration  as 
void  triggers  the  're-defini¬ 
tion  error’  diagnostic.”  I 
should  (Manx  said)  either 
move  fnZ  above  fn  1  in  the 
source  or  else  declare  fnZ 
as  void  within  fnl  before 
invoking  it. 

Frankly,  this  strikes  me 
as  nonsense.  If  I  craved  a 
language  that  would  kick 
me  around  in  this  way,  I'd 
use  Pascal.  Bottom  line: 
Will/should  this  code  be 
flagged  as  incorrect  by  any 
standard  compiler?  If  so, 
and  if  there’s  a  good  reason 
for  including  this  "feature” 
in  the  standard,  would 
somebody  explain  it  ? 

Fm:  Chris  [IBMNET] 

To:  Bill 

Sorry  to  say,  Manx  is  right. 
This  is  one  of  the  very  few 
cases  where  C  compilers 
do  any  type  checking  at  all. 
Any  reference  to  the  result 
of  an  as-yet-undefined 
function  is  assumed  to  be 
an  int,  and  you’ll  get  some 
kind  of  diagnostic  if  that 
later  turns  out  to  be  wrong. 
The  company's  two  sug¬ 
gested  resolutions  are  also 
correct.  Not  sure  why  the 
compiler  waits  until  the 
errorvar  declaration. .  .  . 

Fm:  Bill 
To:  Chris 

Maybe  I  expressed  my 
point  badly;  I  realize  there 


are  times  the  compiler 
must  make  assumptions,  if 
only  to  clear  the  procedure 
stack.  Where  externals  are 
concerned,  I  have  no  prob¬ 
lem  with  default  typing. 
But  in  my  example,  the 
compiler  does/ could  know 
the  function  type  because 
it's  explicitly  declared  void 
a  few  lines  later  on.  Doesn't 
it  strike  you  as  odd  to  talk 
about  assigning  a  "default” 
type  to  a  symbol  that's  ex¬ 
plicitly  typed  in  the  same 
source  module?  As  my  er¬ 
ror  shows,  a  language  that 
works  in  this  way  will  fre¬ 
quently  be  unable  to  han¬ 
dle  forward  references  in 
an  intelligent  way  (that  is, 
without  requiring  contor¬ 
tions  on  the  part  of  the  pro¬ 
grammer).  I  have  appar¬ 
ently  escaped  being  bitten 
by  this  up  to  now  through 
sheer  luck;  it  gives  me  a 
spooky  feeling  to  think 
that  I  could  go  back  and 
edit  working  code,  chang¬ 
ing  nothing  but  the  order 
in  which  functions  appear 
in  the  source  module,  and 
produce  numerous  com- 
pile-time  errors. 

Fm:  Larry 
To:  Bill 

A  couple  of  things — the 
reason  why  standard  C 
doesn't  catch  this  is  that  it 
doesn’t  do  forward  refer¬ 
ences.  That  is,  all  symbols, 
whether  functions  or  vari¬ 
ables,  must  be  predefined 
to  non-z'nt  if  they  are  to  be 
used  as  such.  The  reason  I 
say  standard  C  is  that  it  is 
not  infeasible  that  you 
might  write  a  multipass  C 
compiler;  but  the  Ker- 
nighan/Ritchie,  Harbison/ 
Steele,  and  ANSI  C  stan¬ 
dards/references  all  de¬ 
scribe  C  in  this  manner. 

Second,  the  way  that  I 
try  to  code  is  that  all  vari¬ 
ables,  whether  functions 
or  not,  get  declared  explic¬ 


itly — I  am  not  one  for  de¬ 
pending  on  a  compiler  to 
do  things  such  as  declara¬ 
tions  itself.  Even  things 
such  as  strcpyl )  generally 
get  placed  in  a  preamble  to 
my  code.  If  I  have  macros 
that  call  subroutines  (de¬ 
clared  within  a  header), 
that  is  where  the  function 
is  declared.  I  am  beginning 
to  write: 

#ifdef  lint 


*  end  if 

clauses  as  well,  putting 
info  in  so  that  lint  knows 
what  is  going  on  for  per¬ 
sonal  functions. 

Note  that  in  Pascal  you 
have  only  the  choice  of  de¬ 
claring  a  function  before 
using  it  (in  general) — there 
is  no  mechanism  I  am 
aware  of  to  allow  simple 
declarations  of  a  later  oc¬ 
curring  function.  At  least 
in  C,  you  can  briefly  tell  the 
compiler  how  to  handle 
the  calls  to  the  subroutine 
and  then  later  actually  go 
ahead  and  specify  the 
subroutine. 

Fm:  Chris 
To:  Larry 

Oops!  You  can  make  any 
Pascal  function/procedure 
declaration  FORWARD, 
which  allows  you  to  use  as- 
yet-undefined  blocks.  The 
compiler  just  needs  the  pa¬ 
rameter  list  and  result  type 
if  it’s  a  function.  .  . . 

Fm:  Larry 
To:  Chris 

OK — I  had  never  heard  of 
it.  Of  course,  I  have  only 
taken  a  few  intro  courses 
on  Pascal  and  used  it  only 
on  an  Apple  II  (Apple's  Pas¬ 
cal).  ...  I  shouldn't  have 
spoken  of  that  which  I  did 
not  know  for  sure — sorry 
all! 
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Fm:  Bill 
To:  Larry 

Actually,  K  &  R  is  consider¬ 
ably  stricter  than  that.  (Af¬ 
ter  finding  nothing  under 
definition,  declaration, 
type,  scope,  and  so  on,  I’d 
about  decided  this  wasn't 
addressed  explicitly.  (I  fi¬ 
nally  stumbled  across  it  un¬ 
der  functions  returning  a 
non-int.  Unless  declared  ex¬ 
ternally  to  all  functions,  a 
noninteger  function  has  to 
be  declared  within  each 
and  every  other  function 
that  references  it.)  Al¬ 
though  your  practice  has 
obvious  advantages  for  de¬ 
bug  and  documentation,  it 
still  seems  strange  to  me  to 
be  forced  to  declare  a  func¬ 
tion  more  than  once.  Do  I 
understand  correctly  from 
your  comments  that  C 


compilers  are  always  or  al¬ 
most  always  single-pass 
jobs?  Being  even  more  ig¬ 
norant  about  implementa¬ 
tions  than  about  the  lan¬ 
guage  itself,  I’d  assumed 
the  opposite — one  reason 
why  this  behavior  seemed 
so  bewildering. 

Fm:  Larry 
To:  Bill 

From  my  experience,  in 
Unix  at  least,  the  C,  compil¬ 
er  does  the  following:  in¬ 
vokes  a  preprocessor 
(which  makes  a  single  pass 
through  the  file),  invokes  a 
program  that  converts  the 
C  languages  into  a  token- 
ized  form,  invokes  a  token 
—  >assembler  program, 
assembles  the  program, 
optimizes  the  program 
(this  step  may  actually  take 
place  before  the  assem¬ 
bly — I  forget  at  this  mo¬ 
ment),  then  links  the  pro¬ 


gram.  Each  step,  except 
perhaps  the  final  two, 
seems  to  be  a  single  pass 
through  the  current  file. 
Note  that  in  many  ways, 
the  link  step  itself  is  a  single 
pass — that  is,  the  ordering 
of  object  modules/libraries 
within  Unix  is  usually  very 
critical.  It  may  make  for  a 
somewhat  faster  link,  but  I 
would  prefer  a  multipass 
approach  here  as  well  as  in 
some  other  places  in  the 
process. 

Fm:  Shira 
To:  Bill 

Bill — It’s  worse  than  that. 
You  can  get  run-time  er¬ 
rors  if,  for  example,  the 
function  returns  a  long  and 
you  don’t  predeclare  it. 
And  (forgive  me  if  I’m  be¬ 
ing  pedagogic  here),  assign¬ 
ing  the  result  to  a  long  (as  in 
longvar  =  Ifun  ( );)  makes  it 
look  OK  but  doesn’t  im¬ 


prove  the  result.  As  I  un¬ 
derstand  it,  the  new  ANSI 
standard  is  moving  toward 
stronger  type  checking,  so 
this  feature  is  probably 
permanent. 

It’s  not  so  bad,  really  .  .  . 
encourages  good  program¬ 
ming  practices  for  one 
thing  (what  if  you  decide 
later  to  move  fn2  to  a 
library?). 

Does  anybody  know, 
btw,  how  C++  handles 
this?  And  is  there  a  PC  im¬ 
plementation  of  C  +  +  yet? 

Fm:  Lenox 
To:  Shira 

In  ANSI  C  (which,  of  course, 
is  currently  only  a  "pro¬ 
posed”  standard),  a  pro¬ 
gram  must  declare  any 
function  before  it  is  actual¬ 
ly  defined  to  be  considered 
a  "strictly  conforming” 
program.  Here  is  an 
example: 
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extern  char  ’foo(void); 

/*  This  is  the  declaration  */ 
static  char  nonsense; 

char  *foo( ) 

/*  This  is  the  definition  */ 

{ 

return  (&,nonsense); 

} 

In  practice,  I  believe  that 
the  intention  of  this  rule  is 
to  get  you  to  declare  every¬ 
thing  in  a  header  file  for 
every  module  that  uses 
foof  7  to  #. include .  Then  the 
compiler  can  tell  if  there 
are  any  type  mismatches 
in  either  the  use  or  defini¬ 
tion  of  a  given  procedure. 

I  believe  that  C++  re¬ 
quires  everything  to  be  de¬ 
clared  before  it  is  actually 
defined.  And  I  haven't 
heard  of  any  PC  implemen¬ 
tations  of  C++:  The  com¬ 
piler  is  just  too  much  of  a 
memory  hog  right  now. 

Fm:  Jeff 
To:  Bill 

As  the  others  have  pointed 
out,  C  requires  variables 
and  functions  to  be  de¬ 
clared  before  they  are 
used.  Pascal  usually  does 
too — and  for  the  same  rea¬ 
son — so  you  can  do  the 
compilation  with  a  single¬ 
pass  parser.  Assuming  int 
for  nondeclared  variables 
makes  it  possible  to  pass  off 
forward  references  to  the 
assembler  and/or  linker. 

C  compilers  are  not  real¬ 
ly  single-pass  programs; 
they  usually  involve  three 
to  five  passes  not  including 
the  linker.  Pass  1  is  the  pre¬ 
processor  and  pass  2  the 
parser.  Pass  3  and  beyond 
are  where  compilers  start 
to  vary:  Some  optimize  the 
output  from  the  parser  be¬ 
fore  feeding  it  to  the  code 
generator;  some  optimize 
after  the  code  is  generated. 
Others  do  both,  and  many 


just  ignore  optimization 
completely. 

Next  comes  the  assem¬ 
bler  pass  and  then  the  link¬ 
er.  Note  that  none  of  the 
above  has  to  be  a  separate 
program;  some  compilers 
have  all  the  passes  built 
into  a  single  program  and 
just  call  each  pass  in  turn 
on  the  current  code  line. 

The  important  thing  to 
remember  is  that  the  com¬ 
piler  knows  nothing  about 
what  happens  after  the 
current  line  being  com¬ 
piled.  It  only  knows  what  it 
is  doing  now  and  what  is  in 
the  symbol  table.  If  a  func¬ 
tion  has  not  been  declared 
explicitly,  it  is  not  in  the 
symbol  table  yet.  Because 
the  compiler  must  know 
what  it  returns  to  continue, 
it  defaults  to  int  and  makes 
a  symbol  table  entry  that 
says  so. 

When  it  got  to  your  dec¬ 
laration  of  fn2(  V,  all  it  had 
was  that  symbol  table  en¬ 
try  to  work  with,  and  so  it 
blew  up. 

Fm:  Sam 
To:  Bill 

After  spending  15  minutes 
reading  this  thread,  I’m  in¬ 
clined  to  comment.  I  like  C, 
but  I  have  to  agree  that  ex¬ 
plicit  type  declaration  for 
functions  is  inconvenient. 
Not  only  that,  it  is  a  poten¬ 
tial  horror  show  for  porta¬ 
bility.  Two  cases  in  point 
(which  happened  to  yours 
truly  in  his  C  programming 
infancy):  Wrote  a  program 
using  atolf J  on  a  Z8000- 
based  machine.  Worked 
like  a  charm.  Ported  it  to  a 
VAX.  No  go.  Problem?  I  nev¬ 
er  declared  long  atolf  J;  at 
the  top  of  the  program — 
making  atolf )  assumed  as 
int.  On  the  zsooo,  the  byte 
order  let  me  get  away  with 
it.  Neither  compiler  com¬ 
plained  a  bit.  Second  case  is 
the  new  type  void.  I  have 
written  many  programs 
compatible  with  Unix,  Ver¬ 
sion  7.  Now,  under  System 


V,  1  have  a  problem.  I  never 
had  to  declare  exit/ )  be¬ 
fore!  System  V  says  void 
ejcitf );,  and  Version  7  says 
int  epcitf  J;.  Why  do  I  care? 
Because  after  my  first  expe¬ 
rience,  I  made  a  law  for 
writing  portable  code:  run 
lint  and  fix  every  error ! 
Now,  of  course,  dear  lint 
complains  about  every  exit 
call  under  System  V.  And 
speaking  of  lint,  does  the 
ANSI  spec  solve  the  mallocf  ) 
problem?  Mallocf  )  is  de¬ 
fined  to  return  a  pointer  for 
any  valid  data  type,  but  lint 
insists  that  you  can’t  right¬ 
fully  typecast  a  (char  Vto  a 
( struct  * ).  I  think  C  needs  a 
type  to  complement  void- 
valid.  Valid  *ptr;  would 
mean  "ptr  can  point  to  any 
data  element.”  Whew.  Said 
more  than  I  thought  I 
would.  Good  thread. 

Fm:  Larry 
To:  Sam 

The  ANSI  standard  pro¬ 
posed  the  type  void  *  with 
the  meaning  that  it  is  a 
pointer  of  generic  type, 
sized  and  aligned  to  match 
any  other  type.  Don’t  ask 
me  how  it  plans  to  pull  that 
one  off  for  machines  with 
different-size  pointers. . .  . 

Fm:  Allen 
To:  Bill 

I  realize  I’m  replying  a  lit¬ 
tle  late  in  the  thread,  but 
there  are  several  things 
that  no  one’s  mentioned 
yet.  First,  if  the  compiler 
processed  forward  refer¬ 
ences  in  the  way  you  sug¬ 
gest,  it  would  either  have 
to  go  through  the  input 
twice  (like  an  assembler 
does  it)  or  keep  elaborate 
tables  around  for  resolving 
these  references.  Either 
way  the  compiler  would 
be  slower.  C  compilers  are 
indeed  single  pass,  and  the 
language  is  designed  in  the 
way  it  is  to  make  this 
possible. 

As  for  the  duplicate  dec¬ 
larations,  don’t  confuse  a 


declaration  with  a  defini¬ 
tion.  A  declaration  is  an  an¬ 
nouncement.  All  it  does  is 
announce  the  existence  of 
an  object  to  the  compiler. 
It’s  something  like  a 
pseudo-op.  That  is,  a  decla¬ 
ration  gives  the  compiler 
information  that  it  will  use 
to  update  its  symbol  table. 
A  definition  on  the  other 
hand  actually  allocates 
space  for  an  object  and 
generates  a  label  associated 
with  that  object.  The 
choice  of  words  is  rather 
unfortunate  here.  I’d  pre¬ 
fer  something  such  as  defi¬ 
nition  and  allocation.  The 
usage  stems  from  K  &  R, 
and  no  one’s  seen  fit  to 
challenge  them. 

You’ll  notice  that  Pascal 
doesn't  allow  any  forward 
references  at  all.  Subrou¬ 
tines  have  to  be  declared 
before  you  can  use  them.  C 
isn’t  really  a  high-level  lan¬ 
guage;  it's  a  very  fancy  as¬ 
sembly  language  and 
should  be  treated  as  such. 

Fm:  Shira 
To:  Allen 

Allen — Thanks  for  the 
very  clear  distinction  be¬ 
tween  declarations  and 
definitions.  Those  of  us 
who  deal  with  multiple 
languages  always  seem  to 
have  trouble  with  these 
terms,  but  I've  printed 
your  message  out  and  I 
won’t  mix  up  these  terms 
again!  Btw,  by  these  terms  I 
mean  technical  terms  used 
differently  by  the  develop¬ 
ers  of  different  languages. 
In,  say,  PL/I,  a  declaration 
normally  allocates  storage. 
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More,  a  File-Browsing  Utility 


Microsoft,  for  some  reason  un¬ 
known  to  myself,  used  the 
name  of  the  Unix  utility  more  for  the 
MS-DOS  file-paging  command.  The 
Microsoft  more  is  actually  a  subset  of 
a  Unix  utility  called  p  (for  page);  it's  a 
subset  because  p  accepts  a  list  of  files 
on  the  command  line  but  Microsoft's 
more  does  not.  The  real  more  is  a 
much  more  powerful  file-browsing 
utility.  It’s  useful  anytime  you  want 
to  look  at  a  file  but  don’t  want  to  both¬ 
er  with  an  editor. 

The  program  presented  here  is  not 
an  exact  look-alike  for  the  Unix  utility. 
It  does,  however,  support  all  the  fea¬ 
tures  of  the  real  more  that  I  use  regu¬ 
larly.  It  also  includes  several  com¬ 
mands  not  supported  by  the  Unix 
version.  Most  important,  it  can  go 
backward  in  the  input  file  (even  if  the 
input  file  is  stdin,  provided  that  stdin 
is  a  redirected  file  or  the  end  of  a 
pipe).  It  can  also  move  around  in  huge 
files.  In  fact,  I  wrote  the  program  for 
this  reason.  I  wanted  to  review  the 
"nroffed"  output  of  an  entire  book,  a 
file  that  was  a  little  more  than  a  mega¬ 
byte  in  size.  The  original  for  the  book 
was  split  into  about  20  smaller  files, 
but  the  word-processed  output  was  in 
a  single  file  that  my  poor  editor  just 
couldn't  handle.  In  addition  to  the 
ability  to  go  backward,  I  needed  sev¬ 
eral  capabilities  of  the  Unix  more.  In 
particular,  I  wanted  to  be  able  to  exe¬ 
cute  my  editor  from  within  more  and 
be  back  where  I  had  left  off  when  I 


by  Allen  Holub 


had  finished  editing.  I’ve  also  added 
(at  the  suggestion  of  reader  Fred 
Smith)  the  ability  to  search  for  a  regu¬ 
lar  expression. 

The  command-line  syntax  is: 
more  [+  <num>]  [file.  .  .] 

The  optional  +<num>  will  cause 


more  to  seek  to  character  <num> 
before  it  starts  printing.  It's  useful  if 
you  want  to  quit  looking  at  a  long  file 
but  then  go  back  to  it  later.  Note  that 
this  is  different  from  the  Unix  ver¬ 
sion,  which  goes  to  line  <num> 
rather  than  character  <num>.  Seek¬ 
ing  to  a  character  is  much  faster  (be¬ 
cause  you  can  do  it  with  an  fseek ( ) 
and  don’t  have  to  process  the  skipped 
lines).  The  remainder  of  the  com¬ 
mand  line  consists  of  a  list  of  files  to 
process.  If  no  files  are  present,  stdin  is 
used  so  you  can  use  more  at  the  end 
of  a  pipe  (as  in  Is  I  more  or  nroff—ms 
file  I  more). 

When  the  program  starts  up,  it 
prints  a  page  from  the  current  input 
file  and  then  waits  for  one  of  several 
commands.  All  these  commands  can 
be  preceded  by  a  count  that  will 
cause  the  command  to  be  executed 
the  specified  number  of  times.  A 
count  doesn’t  always  make  sense 
(you  wouldn't  want  to  print  the  help 
screen  N  times),  but  it's  supported  for 
all  commands  anyway.  The  com¬ 
mands  supported  by  my  more  are 
summarized  in  Table  1,  page  24. 
They  are: 

b — Go  backward  one  page  in  the  in¬ 
put  ( Nb  will  go  back  N  pages). 
More  prints  a  line  on  the  screen 
and  then  prints  the  previous 
page.  This  way  the  program  can 
be  used  on  terminals  that  don't 
support  backward  scrolling, 
e — Go  to  the  end  of  the  current  file, 
n — Go  to  the  next  file  that  was  listed 
on  the  command  line, 
o — Print  the  offset,  in  characters, 
from  the  beginning  of  the  file. 
The  offsets  of  both  the  top  and 
bottom  lines  of  the  current  screen 


are  printed.  This  command  is  use¬ 
ful  in  conjunction  with  the  + 
command-line  option. 

q — Quit  (return  to  DOS). 

s — Skip  one  line.  The  skipped  line  is 
not  printed.  This  command  is  usu¬ 
ally  used  with  a  preceding 
count — for  example,  100s  skips 
over  the  next  100  lines  without 
printing  them.  You  can  still  back 
up  with  the  b  command  if  you  de¬ 
cide  you  really  wanted  to  see  the 
skipped  lines  after  all.  The  cur¬ 
rent  position  in  the  file  (represent¬ 
ed  as  a  percentage)  is  printed  as  a 
"mileage”  indicator  as  lines  are 
skipped. 

r — For  rewind.  Goes  back  to  begin¬ 
ning  of  the  current  file  and  prints 
the  first  page. 

! — Waits  for  you  to  type  a  normal  DOS 
command  and  then  executes  that 
command.  Unix  creates  a  shell  to 
execute  the  command.  I  decided 
not  to  create  a  shell  because  of  the 
additional  memory  required,  so 
you  can't  execute  a  batch  file  or  an 
internal  command  directly.  You 
can  do  it  indirectly  by  creating  a 
shell  explicitly,  however.  Use 
command  /c  batchfile  . . .  for  COM- 
MAND.COM  and  sh  —c  batchfile  . . . 
for  the  shell.  If  you  enter  a  car¬ 
riage  return  instead  of  a  com¬ 
mand,  the  command  used  in  the 
previous  /  is  used  this  time.  When 
the  program  terminates,  more  re¬ 
prints  the  current  page  and  then 
carries  on  as  usual. 

/ — Prompts  for  a  grep-like  regular 
expression  and  then  searches  for 
a  string  matching  that  expression. 
The  search  starts  at  the  first  char¬ 
acter  after  the  end  of  the  current 
screenful.  The  search  terminates 
either  when  the  string  is  found  or 
when  any  key  is  pressed.  As  with 
the  /  command,  the  previous  ex¬ 
pression  is  used  if  a  carriage  re¬ 
turn  is  entered  at  the  prompt. 

ESC — Input  starts  scrolling,  without 
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pausing,  until  any  key  is 
pressed. 

CR — (or  Enter)  Print  next  line.  Like 
any  other  command,  the  CR 
command  may  be  preceded  by 
a  count. 

space — Print  next  screen. 

Implementation 

The  code  for  more  itself  is  in  Listing 
One  (page  64).  Most  of  the  external 
routines  listed  on  lines  17-28  should 
be  provided,  in  one  form  or  another, 
with  your  compiler  (these  are  for  the 
Microsoft  compiler).  Exceptions  are 
6_gefc( ),  look ( ),  and  filelengthl ).  The 
first  two  are  in  Listings  Two  and 
Three,  page  78;  I'll  discuss  them  later. 
Filelengthl )  is  a  Microsoft  routine  that 
returns  the  size  of  a  file  in  bytes.  If 
you  don’t  have  this  routine,  you  can 
find  the  file  length  by  seeking  to  the 
end  of  file  and  noting  the  file  position 
returned  by  fseekl  >.  An  example  is 


shown  in  Table  2,  below.  The  same 
techniques  can  be  used  with  open ( ) 
and  Iseekl ).  Because  the  file  length  is 
determined  only  once  (on  line  633), 
the  penalty  of  using  a  seek  isn’t  too 
great. 

More  keeps  track  of  the  starting  po¬ 
sition  of  each  line  on  a  stack.  (A  line’s 
position  is  the  offset,  in  characters, 
from  the  beginning  of  the  file  to  the 
first  character  on  the  line.)  Every  time 
a  line  is  input,  the  position  of  the  first 
character  is  stacked.  When  you  go 
backward  a  page,  two  pages’  worth  of 
these  positions  are  popped  off  the 
stack,  then  a  page  is  printed,  starting 
at  the  last-popped  line.  Printing  the 
page  causes  a  page's  worth  of  lines  to 
be  input  with  those  line's  positions 
getting  restacked  as  part  of  the  input 
process.  The  stack  itself  (Stack)  and 
the  stack  pointer  ( Sp )  are  declared  on 
lines  59-60.  The  macros  on  the  follow¬ 
ing  lines  do  various  stack-mainte¬ 
nance  tasks.  STACKFULL  evaluates  to 
true  if  the  stack  is  full,  STACKEMPTY  is 
true  if  the  stack's  empty,  and  CLEAR 


STACK  deletes  all  items  currently  in 
the  stack  and  resets  the  stack  pointer. 
TOS  evaluates  to  the  entry  at  the  cur¬ 
rent  top  of  stack.  The  entry  isn't 
popped,  however.  BACKSCRN  evalu¬ 
ates  to  either  the  stack  entry  that's  at 
one  page’s  offset  from  the  top  of  stack 
(that  is,  to  the  position  of  the  top  line 
on  the  screen)  or  to  zero  if  there  aren't 
that  many  lines  on  the  screen  (as  will 
happen  with  a  small  file).  It's  used  by 
the  o  command. 

Various  stack-maintenance  sub¬ 
routines  are  needed,  too.  Push( )  and 
popt )  on  lines  125-144  do  what  you’d 
think  they  would.  Comp— stack! ) 
(lines  147-164)  is  called  from  push( ) 
when  the  stack  is  full.  It  compresses 
the  stack  by  removing  every  other 
entry.  This  way  you  won’t  loose  all 
the  information  on  the  stack  in  the 
event  of  an  overflow;  you'll  just  loose 
a  little  resolution  when  you  go  back¬ 
ward  in  the  file  with  a  b  command. 
Note  that  the  default  stack  size  is  6K, 
so  it’s  pretty  unlikely  that  you’ll  run 
out  of  stack. 

A  help  screen  is  printed  by  help ( ion 
lines  72-107.  It  uses  the  IBM  box-draw¬ 
ing  characters  to  put  a  box  around  the 
help  message.  You’ll  want  to  use 
dashes  and  vertical  bars  if  you're  not 
running  the  program  on  a  PC. 

The  file  position,  represented  as  a 
percentage,  is  printed  at  every  com¬ 
mand  prompt  using  the  percent ( ) 
routine  on  lines  258-264.  Note  that 
the  cast  is  necessary  here  because,  as 
TOS  and  Flen  are  both  integral  types, 
TOS/Flen  evaluates  to  zero  if  the  cast 
isn't  present.  The  problem  here  is 
that  expressions  are  evaluated  two 
terms  at  a  time,  and  the  type  of  the 
temporary  variable  used  to  store  in¬ 
termediate  results  will  be  the  same  as 
the  two  operands.  Because  TOS  and 
Flen  are  both  longs,  an  integer  divi¬ 
sion  is  done  and  the  result  will  be 
truncated  to  zero  and  stored  in  a  long. 
The  compiler  then  evaluates  the  * 
100.00  part  of  the  expression.  Because 
the  value  of  the  temporary  variable 
that's  used  to  hold  TOS/Flen  is  a  long 
and  100.00  is  a  double,  the  long  is  pro¬ 
moted  to  double  before  the  multipli¬ 
cation  is  performed.  This  promotion 
won’t  restore  the  fraction  that  was 
discarded  in  the  initial  division, 
though,  so  if  the  cast  wasn't  present, 
the  expression  would  evaluate  to 
zero. 

Regular  expression  searching  is 


Usage:  more[  +  <num>]  [file.  . .] 

Print  all  files  in  list  on  the  screen,  pausing  every  23  lines. 

If  +  is  specified,  more  will  start  printing  at  character  <num>. 

Stdin  is  used  if  no  file  is  specified  so  more  can  be  used  at 

the  end  of  a  pipe.  One  of  the  following  commands  may  be  executed 

every  time  the  program  pauses: 


b . go  (B)ack  a  page 

e  . go  to  end  of  file 

n  . go  to  (N)ext  file 

o  . print  (O)ffset  from  start  of  file  in  bytes 

q  . (Q)uit  (return  to  DOS) 

s  . (S)kip  one  line  (w/o  printing) 

r . (R)ewind  file  (go  back  to  beginning) 

! . execute  a  program  (type  blank  line  at  prompt  to 

execute  previous  /  cmd) 

/ . search  for  regular  expression  (type  blank  line  at  prompt 

for  last) 

ESC . scroll  until  any  key  is  pressed 

CR . print  next  line 

SP  . print  next  screen 


anything  else  . . .  .print  list  of  legal  commands 
All  commands  may  be  preceded  by  a  count. 


Table  1:  More’s  commands  and  command-line  syntax 


FILE  *fp; 

int  length; 

fp  =  fopen(  "file",  "="r"  ); 

length  =  fseek(  fp,  0,  2  );  /*  Offset  0  from  EOF  7 

fclose(  fp ); 


Table  2:  Finding  a  file  length  with  fseek(  ) 
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done  by  search ( )  on  lines  338-379. 
The  subroutines  makepati )  and 
matchsi )  aren't  in  the  listing.  They 
are  the  same  routines  as  are  used  by 
grep.  (See  the  Availability  section.) 

The  /  command  is  processed  by  ex¬ 
ecute!  Ion  lines  383-444.  Note  that  I’m 
using  a  spawnlp ( )  call  rather  than  a 
system ( )  call  to  create  the  child  pro¬ 
cess.  This  means  that  you  can’t  exe¬ 
cute  a  batch  file  directly  from  within 
more,  though  you  can  do  it  indirect¬ 
ly,  as  I  explained  earlier.  If  you’re  go¬ 
ing  to  execute  a  lot  of  batch  files,  you 
may  want  to  change  line  432  into  a 
system ( Icall. 

Note  that  a  bug  in  Microsoft  C,  Ver¬ 
sion  3.0,  forces  you  to  close  the  cur¬ 
rent  input  file  (on  line  591)  before 
calling  eyecutei )  and  then  reopen  it 
on  returning  (lines  595-605).  This  will 
cause  problems  if  you’re  getting  in¬ 
put  from  standard  input  because  you 
won’t  be  able  to  reopen  the  file,  not 
having  a  file  name  to  give  fopenf ). 
Consequently,  if  you’re  likely  to  use 
the  !  command,  you’ll  have  to  create 
a  temporary  file  rather  than  use  a 
pipe. 

The  remainder  of  the  program  is 
pretty  much  self-explanatory.  The 
one  other  pipe-related  problem  is 
solved  with  the  b—getci )  and  look( ) 
functions  in  Listings  Two  and  Three. 
You  have  to  get  commands  using  ROM 
BIOS  input  routines  because  you  might 
be  using  standard  input  for  the  file  be¬ 
ing  printed.  B—getc( )  gets  a  character 
from  the  BIOS,  using  the  keyboard  in¬ 
terrupt  (0yl6).  Look ( 1  is  a  keyboard 
look-ahead  function.  It  returns  0  if  no 
key  has  been  typed.  Otherwise  it  re¬ 
turns  the  key  in  the  scan-code/char¬ 
acter-code  format  used  by  the  BIOS. 
You  can  find  more  information  in  the 
DOS  Technical  Reference  (buried  in 
the  BIOS  listing  as  a  comment)  and  in 
The  Peter  Norton  Programmer's 
Guide  to  the  IBM  PC.  Although  look ( ) 
was  written  in  assembler  for  speed 
reasons,  it’s  pretty  easy  to  move  it  to  C. 
Most  of  the  file  is  just  overhead  fcr  the 
Microsoft  compiler.  The  actual  work 
is  done  on  lines  37-41,  and  the  return 
value  is  in  ay. 

Availability 

The  pattern-matching  routines  were 
originally  published  as  part  of  grep  in 
DDJ,  October  1984.  Back  issues  are 
available  for  $5  from  DDJ.  Grep  is  also 
available  electronically  as  part  of  the 


/util  program  package  listed  in  the 
DDJ  catalog  ad  (page  105)  and  is  includ¬ 
ed  in  both  Dr.  Dobbs  Tool  book  of  C 
and  in  Dr.  Dobb 's  Bound  Volume  9. 

All  the  code  printed  in  this  month’s 
issue  is  available  on  CompuServe  in 
DL  1  (type  ddjforum).  The  entire  pro¬ 
gram,  along  with  the  pattern-match¬ 
ing  routines  and  an  executable  ver¬ 
sion,  is  also  available  on  an  IBM  PC- 
compatible  disk  for  $25  from 
Software  Engineering  Consultants, 
P.O.  Box  5679,  Berkeley,  CA  94705. 


Erratum 

Ron  Albury  found  a  bug  in  Listing 
Seven  of  my  AVL  tree  routines  (Au¬ 
gust  1986)  that  could  cause  the  insert 
function  to  fail  on  an  attempt  to  in¬ 
sert  a  conflicting  node.  To  fix  the 
problem,  add  the  line  h  =  0;  immedi¬ 
ately  below  line  68  (page  92).  ddj 

(Listings  begin  on  page  64.) 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  No.  2. 
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ARTICLES 


Programming  on  the 

80386 


by  Ross  Nelson 


Intel  recently  intro¬ 
duced  the  80386,  its 
entry  into  the  32-bit 
microprocessor  derby. 

The  80386  can  run  all 
programs  developed  for 
the  80286,  which  in  turn 
runs  programs  designed 
for  the  8086  and  8088. 

Because  of  this  compatibility  with  its  widely  used  prede¬ 
cessors,  the  80386  is  likely  to  be  very  popular.  The  80386 
(or  386  for  short)  is  not  merely  bigger  and  faster,  however; 
Intel  has  made  some  significant  architectural  changes  as 
well.  The  enhancements  that  I’ll  examine  in  this  article 
include  the  elimination  of  the  64K  segment  restriction; 
enhanced  instruction  set  and  operand  addressing;  the 
ability  to  run  32-bit  and  16-bit  software  simultaneously; 
and  virtual  memory  support,  including  paging. 

Operating  Modes 

Like  its  predecessor  the  286,  the  386  operates  in  either  real 
address  mode  or  protected  virtual  address  mode,  usually 
just  called  real  mode  and  protected  mode,  respectively.  In 
real  mode,  the  386  is  practically  indistinguishable  from  an 
8088  or  an  8086.  Real  mode  carries  with  it  all  the  restric¬ 
tions  of  the  8086 — most  important,  only  1  megabyte  of 
memory  is  directly  addressable.  As  in  the  8086,  physical 
addresses  are  created  by  multiplying  the  segment  regis¬ 
ter  value  by  16  and  adding  an  offset. 

Object-code  compatible  with  the  286,  the  386  also  oper¬ 
ates  in  protected  mode.  Unlike  the  286,  however,  it  also 
performs  32-bit  operations.  All  the  architectural  enhance¬ 
ments  of  the  386  are  available  when  running  32-bit  in¬ 
structions  in  protected  mode.  This  is  the  way  the  proces¬ 
sor  was  designed  to  run  and  is  therefore  called  its  native 
mode.  The  other  modes  (real  mode,  16-bit  protected 
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mode,  and  virtual  8086 
mode)  are  called  emula¬ 
tion  modes.  The  basic 
protection  mechanism 
of  the  386  is  identical  to 
that  of  the  286.  It  is  out¬ 
side  the  scope  of  this  ar¬ 
ticle  to  describe  the  full 
protection  model  of  the 
286  and  386;  therefore,  I  will  essentially  ignore  gate  de¬ 
scriptors,  tasking,  and  privilege  levels.  A  short  review  is 
provided  in  the  inset  entitled  "The  286/386  Protection 
Model”  on  page  39.  The  extensions  to  the  386  are  primari¬ 
ly  in  memory  addressing,  so  it's  appropriate  to  review 
protected  mode  addressing  in  the  286. 

In  protected  mode,  there  is  a  dramatic  change  in  the 
way  the  processor  behaves.  In  real  mode,  the  program 
currently  executing  interprets  memory  values,  and  the 
processor  is  merely  the  vehicle  for  manipulation  of  the 
data  provided  by  the  program.  In  protected  mode,  how¬ 
ever,  the  processor  assigns  semantic  meaning  to  certain 
blocks  of  memory  independently  of  whatever  program 
may  be  running.  Each  block  of  memory  the  processor 
recognizes  I  call  a  system  object.  The  most  common  sys¬ 
tem  object  is  the  descriptor.  Other  objects  include  descrip¬ 
tor  tables,  which  contain  descriptors;  segments,  which 
are  blocks  of  memory;  and  gates,  which  restrict  access  to 
segments  and  help  enforce  the  protection  rules.  Each  seg¬ 
ment,  gate,  and  table  has  an  8-byte  descriptor  that  defines 
it.  Descriptors  contain  information  about  the  object,  such 
as  its  size,  type,  location  in  memory,  and  protection  attri¬ 
butes.  Figure  1,  page  34,  shows  a  typical  segment  descrip¬ 
tor  for  the  286. 

In  protected  mode,  memory  is  accessed  via  a  descrip¬ 
tor.  The  contents  of  segment  registers  do  not  point  to  spe¬ 
cific  memory  paragraphs  but  are  treated  as  indices  into 
descriptor  tables.  The  processor  requires  the  existence  of 
a  global  descriptor  table  (GDT)  and  an  interrupt  descriptor 


The  80386  is  likely  to  be  very  popu¬ 
lar  because  of  its  compatibility 
with  the  8086 ,  8088,  and  80286. 
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table  (IDT).  It  also  allows  optional  local  descriptor  tables 
(LDTs)  to  be  present.  The  GDTR  and  1DTR  registers  point  to 
the  GDT  and  IDT,  respectively.  All  other  system  objects, 
including  segments,  LDTs,  and  gates,  are  pointed  to  by 
descriptors.  Figure  2,  page  34,  outlines  the  hierarchy  of 
pointers  to  system  objects. 

When  a  memory  reference  instruction,  such  as  MOV 
AX,  12001,  is  executed,  the  base  address  from  the  descriptor 
selected  by  the  DS  register  is  added  to  the  offset  from  the 
instruction  (in  this  case  0200H)  to  generate  the  linear  ad¬ 
dress.  In  the  286,  the  linear  address  becomes  the  physical 
address  that  goes  out  over  the  processor  bus.  In  the  386, 
however,  the  linear  address  passes  through  the  paging 
mechanism,  which  generates  the  final  physical  address.  I 
will  examine  paging  a  little  later.  First,  I’ll  look  at  how 
descriptors  have  been  changed  in  the  386. 

In  the  286,  the  last  2  bytes  of  the  descriptor  must  be  0.  In 
the  386,  though,  these  bytes  can  take  on  other  values. 
Figure  3,  page  34,  shows  the  fields  in  the  last  16  bits  of  a 
descriptor  on  the  386.  Eight  of  the  bits  have  been  used  to 
extend  the  linear  address  space  to  32  bits,  another  4  bits  go 
toward  extending  the  limit  field,  2  bits  are  used  as  flags, 
and  another  2  bits  are  reserved  for  some  future  processor. 
At  first  glance,  these  extensions  grant  you  a  physical  ad¬ 
dress  space  of  232,  as  expected,  with  a  maximum  segment 
size  of  220,  or  1  megabyte. 

Have  you  been  saddled  with  a  new  segment  limitation? 
Fortunately,  no.  The  G  bit  stands  for  segment  granularity. 
When  reset  to  0,  as  in  286  code,  the  size  of  a  segment  (as 
indicated  by  the  limit  field)  is  measured  in  bytes.  But 
when  the  G  bit  is  set  to  1,  the  segment  size  is  measured  in 
pages.  Each  page  is  212  bytes  (4K)  long.  Therefore,  the  max¬ 
imum  segment  size  is  220  pages  times  212  bytes  per  page,  or 
232  bytes.  The  D  bit,  which  Intel  calls  the  default  bit,  is 
active  only  in  executable  segment  descriptors.  When  set 
to  1,  it  means  that  the  native  mode,  32-bit  instruction  set  is 
to  be  used.  When  reset,  the  processor  interprets  opcodes 
as  if  it  were  a  286. 


Native  Architecture  and  Instruction  Set 

The  386  microprocessor  holds  34  different  registers, 
grouped  into  four  classes.  These  registers  are  illustrated 
in  Figure  4,  page  34.  The  first  group,  general-purpose  reg¬ 
isters,  are  the  ones  most  commonly  dealt  with.  They  act 
as  accumulators  and  index  registers,  and  their  names  are 
derived  from  the  corresponding  registers  of  the  previous 
generations  of  processors. 

The  next  register  class,  segmentation  and  protection,  is 
also  familiar  from  the  286,  although  there  are  two  new 
entries.  In  addition  to  the  SS,  CS,  DS,  and  ES  segment  regis¬ 
ters,  there  are  the  FS  and  GS.  These  segment  registers  are 
used  only  when  the  special  segment  override  prefixes  FS: 
and  GS:  are  found  in  the  instruction  stream.  Associated 
with  most  of  the  registers  in  this  class  is  a  special  on-chip 
cache  that  holds  the  descriptor  information  associated 
with  each  segment.  This  precludes  the  necessity  of  read¬ 
ing  the  descriptor  table  every  time  an  access  to  a  given 
segment  occurs. 

The  registers  in  the  control  class  are  partially  familiar. 
ElP  is  the  32-bit  extension  of  the  instruction  pointer,  and 
EFLAGS  contains  two  additional  flag  bits.  The  control  regis¬ 
ters  ( CR0—CR7 )  are  new  to  the  386,  but  CRO  contains  what 
was  called  the  machine  status  word  (MSW)  on  the  286. 
These  control  registers  contain  information  necessary  for 
controlling  processor  extensions  (80387)  and  paging. 

The  final  class  of  registers,  test  and  debug,  are  com¬ 
pletely  new.  The  debug  registers  ( DR0—DR7 )  allow  a  soft¬ 
ware  debugger  to  set  the  kind  of  breakpoints  that  used  to 
require  an  expensive  emulator  to  generate.  I'll  describe 
use  of  these  registers  in  more  detail  later.  The  test  regis¬ 
ters,  TR6  and  TR7,  are  used  to  verify  that  the  paging  cache 
is  working  correctly. 

In  addition  to  expanding  the  address  space  and  register 
set  of  the  processor,  Intel  has  also  expanded  the  address¬ 
ing  modes  of  the  instruction  set.  The  instruction  format  of 
the  previous  generations  of  processors  was  an  opcode 
byte,  followed  by  the  modr/m  byte,  followed  by  any 
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operands  required.  Because  only  a  limited  number  of  ad¬ 
dressing  modes  could  be  encoded  in  the  modr/m  byte, 
certain  registers  took  on  dedicated  functions.  Only  BX,  SI, 
DI,  and  BP  could  be  used  for  indexing  or  indirection  and 
only  in  certain  combinations.  These  restrictions  have 
been  greatly  relaxed  in  the  386  with  the  addition  of  an¬ 
other  address  mode  byte  following  the  modr/m. 

This  new  byte,  called  s-i-b,  for  scale-index-base,  extends 
the  addressing  capabilities  of  the  386  in  two  significant 
ways.  First,  it  allows  any  of  the  eight  general-purpose 
registers  to  be  used  as  base  or  index  registers,  in  any  com¬ 
bination.  This  makes  the  job  of  compiler  writers  much 
easier  because  they  no  longer  have  to  worry  about  having 
the  results  of  address  computations  in  the  proper  register. 
Any  of  the  registers  is  proper. 

In  addition,  the  scale  portion  of  the  s-i-b  byte  can  be  used 
to  eliminate  array  index  computation  altogether  in  some 
cases.  As  an  example,  assume  that  array  FOO  contains  sev¬ 
eral  32-bit  floating-point  numbers.  The  instruction  se¬ 
quence  generated  by  the  high-level  language  statement 
SQflT  (FOO [I  +31)  is  shown  for  the  8086,  the  286,  and  the  386 
in  Table  1,  below.  Automatic  scaling  is  allowed  only  for 
arrays  whose  elements  are  2,  4,  or  8  bytes  long. 

In  the  8086  and  286  instruction  sets,  the  most  common 
operations  affected  either  byte  or  word  operands.  The 
same  is  true  of  the  386  except  that  the  D  bit  of  the  executing 
code  segment  is  checked  to  see  if  the  machine  word  is  32 
bits  long  ( D=1 )  or  16  bits  long  ( D=0 ).  The  MOVSW  instruc¬ 
tion,  for  example,  will  copy  a  16-bit  quantity  when  D  is  0 
and  a  32-bit  quantity  when  D  is  1.  To  allow  a  program 
running  in  the  native  (32-bit)  mode  to  access  a  16-bit  quanti¬ 
ty,  an  override  instruction  ( 066H )  is  provided,  which  tog- 


8086 

286 

386 

MOV 

AX,  1 

MOV 

AX,  1 

MOV 

EAX,  1 

ADD 

AX,  3 

ADD 

AX,  3 

ADD 

EAX,  3 

MOV 

BX,  AX 

MOV 

BX,  AX 

FLD 

FOO[EAX  *  4] 

MOV 

CL,  2 

SHR 

BX,  2 

FSQRT 

SHR 

BX,  CL 

FLD 

[BX] 

FLD 

[BX] 

FSQRT 

FSQRT 

Tuble  1:  Implementation  of  SQRT  (FOO[I  +  3])  on  8086/ 
286/386 


MOVSX 

move  byte  to  word,  sign  extended 

MOVZX 

move  byte  to  word,  zero  extended 

LFS,  LGS 

load  pointer,  new  segment  register 

SHLD,  SHRD 

double  word  shift 

BT 

bit  test 

BTC 

bit  test  and  complement 

BTS 

bit  test  and  set 

BTR 

bit  test  and  reset 

BSF 

bit  scan  forward 

BSR 

bit  scan  reverse 

SETcc 

set  byte  if  condition  code 

(cc  same  as  Jcc  in  conditional  jumps) 

Table  2:  Instruction  set  additions  for  the  386 


gles  the  default  operand  size  for  the  next  instruction. 
While  running  in  16-bit  mode,  this  opcode  has  the  inverse 
effect — it  allows  access  to  32-bit  registers  and  memory 
operands. 

The  instruction  repertoire  of  the  386  has  been  en¬ 
hanced  as  well.  Opcodes  have  been  added  to  allow  access 
to  the  new  control,  breakpoint,  and  debug  registers,  and 
new  conditional  and  bit  operators  have  been  added. 
There  are  now  double-precision  shift  operators  and 
move  byte  with  sign  extension  or  zero  extension.  Table  2, 
below,  lists  the  new  mnemonics. 

Paging 

Paging  has  long  been  the  most  popular  method  of  imple¬ 
menting  virtual  memory.  Although  virtual  memory  can 
be  achieved  with  segmentation  alone  (as  in  the  286),  pag¬ 
ing  methods  are  usually  faster  and  simpler  because  the 
fixed  page  size  maps  easily  onto  the  fixed  sector  sizes  of 
disks,  the  most  common  secondary  storage  medium.  The 
page  size  of  the  memory  management  unit  (MMU)  of  the 
386  is  212  bytes,  or  4K.  It  is  no  coincidence  that  the  granu¬ 
larity  hit  of  the  segment  descriptors  deals  with  pages  of 
the  same  size. 

The  low-order  12  bits  are  reserved  to  address  within  a 
page,  leaving  20  of  the  32  physical  address  bits  to  select 
the  page.  The  additional  20  bits  could  be  used  as  an  index 
into  an  array  of  linear  (virtual)  to  physical  addresses,  but 
this  would  require  a  table  of  more  than  1  million  entries 
(220)  to  be  in  memory  constantly  for  each  task.  Instead,  the 
upper  20  bits  are  divided  into  two  10-bit  numbers.  The 
highest  order  value  is  used  to  select  one  of  1,024  (210)  page 
table  directories.  Each  directory  entry  points  to  a  page 
table  containing  1,024  physical  page  addresses.  The  ad¬ 
vantage  of  using  this  method  is  that  only  the  directory 
entries  must  be  guaranteed  to  be  in  memory  at  all  times, 
whereas  the  page  tables  themselves  may  be  swapped  out 
to  save  working  storage  space.  Note  that,  with  1,024  en¬ 
tries  of  32  bits  each,  a  page  table  is  4K  long. 

One  of  the  control  registers  (CB3)  points  to  the  starting 
location  of  the  page  table  directories.  A  copy  of  CR3  is 


80386  Development  Tools 

In  addition  to  the  standard  Intel  development  tools 
that  have  been  available  for  some  time,  new  products 
(both  software  and  hardware)  that  can  significantly 
speed  386  development  tasks  are  starting  to  appear. 

One  such  product  is  called  the  386  Translator.  It’s  a 
plug-in  piggyback  card  that  replaces  the  80286  in  a  stan¬ 
dard  IBM  PC/AT  with  an  80386  and  some  support  circuit¬ 
ry.  The  new  board  allows  developers  to  create  software 
that  takes  advantage  of  the  386 's  ability  to  run  simulta¬ 
neously  in  several  different  modes.  The  only  penalty 
seems  to  be  that  an  AT  with  the  386  Translator  board 
runs  about  10  percent  slower  than  an  unmodified  ma¬ 
chine  because  of  the  wait  states  that  must  be  inserted 
for  386  memory  accesses. 

The  386  Translator  is  available  from  American  Com¬ 
puter  &  Peripheral  Inc.,  2720  Croddy  Way,  Santa  Ana, 
CA  92704;  (714)  545-2004. 
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stored  for  each  task  in  386  native  mode.  Figure  5,  page  38, 
illustrates  translation  from  linear  to  physical  address.  Be¬ 
cause  the  directory  pointers  and  the  page  table  pointer 
both  reference  a  4K  page,  only  20  bits  of  the  32-bit  word 
are  used  as  a  page  address  by  the  MMU.  This  frees  up  the 
12  low-order  bits  for  other  uses.  The  lowest-order  bit 
(called  the  P  bit)  is  used  to  mark  whether  the  page  is  actu¬ 
ally  present  in  physical  memory.  If  a  memory  reference 


occurs  and  either  the  page  table  or  the  physical  page  is 
marked  "not  present,”  a  page  fault  (inf  14)  occurs,  and  the 
operating  system  is  responsible  for  reading  the  page  into 
physical  memory.  The  other  11  bits  have  various  uses; 
some  are  used  by  the  hardware  to  mark  whether  pages 
have  been  used  and  to  provide  a  simple  user/supervisor 
protection  scheme,  and  three  of  the  bits  can  be  used  by 
the  operating  system.  Note  that  whenever  the  P  bit  is  0  or 
"not  present,”  the  pointer  does  not  contain  a  physical 
memory  address  and  the  operating  system  can  use  the 
other  31  bits  as  it  chooses — typically  to  hold  the  disk  sec- 


Offset  15 


Limit  (segment  size  —  1) 


Base  address  bits  15  .  .  0 


Base  23  .  .  16 


Access  rights 


386  Reserved  (0) 


Offset  1 5  0 


+0 

Limit  bits  15  .  .  0 

+2 

Base  address  bits  15  .  .  0 

+4 

Base  23  .  .  16 

Access  rights 

+6 

1 

Limit  19  .  .  16 

Base  31  .  .  24 

Figure  1:  286  segment  descriptor 


Figure  3:  386  segment  descriptor 


Figure  2:  Descriptor  hierarchy 
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tor  that  contains  the  primary  storage  memory  image. 

From  this  discussion,  it  would  seem  that  every  memo¬ 
ry-reference  instruction  executed  while  paging  was  en¬ 
abled  would  actually  require  three  memory  fetches  to 
complete:  the  first  to  fetch  the  page  directory,  the  next  to 
fetch  the  page  table,  and  the  third  to  finally  read  the  oper¬ 
and  itself.  To  prevent  this  slowdown,  the  386  contains  a 
cache,  called  the  translation  lookaside  buffer  (TLB),  which 
holds  the  32  most  commonly  referenced  page  table  en¬ 
tries.  If  a  cache  "hit”  occurs,  no  lookup  penalty  will  be 
exacted.  Intel  estimates  that  only  2  percent  of  address 
lookups  will  require  the  three-stage  memory  references. 


32-bit 
name  31 

EAX 
EBX 
ECX 
EDX 
ESI 
EDI 
EBP 
ESP 


General  Purpose 
16  15  87 


AH 

AL 

BH 

BL 

CH 

CL 

DH 

DL 

16-bit 

name 

AX 

BX 

CX 

DX 

SI 

Dl 

BP 

SP 


31 


Control 
16  15 


As  a  further  performance  optimization,  the  MMU  is  on- 
chip.  Microprocessor  systems  with  an  external  MMU  of¬ 
ten  require  delays  equivalent  to  one  wait  state  while  the 
MMU  determines  whether  a  page  fault  has  occurred. 

Performance 

Instruction  durations  for  the  386  are  measured  by  the 
number  of  clock  cycles  required  for  an  instruction  to 
complete.  When  coupled  with  the  processor  clock  rate, 
an  instruction  time  (in  nanoseconds  or  microseconds)  can 
be  generated. 

For  the  most  part,  the  number  of  clocks  required  for  a 
given  instruction  on  the  386  is  the  same  as  it  was  on  the 
286.  When  the  286  was  first  available,  however,  it  ran  at 
clock  rates  of  6  and  8  MHz.  The  386  can  run  at  speeds  of 
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Segmentation  and  Protection 
0  |  Base  Limit  AR 


SS 


CS 


DS 


ES 


FS 


GS 


TR 


LDTR 


Descriptor  portion  (hidden) 


Base 


Limit 


GDTR 

IDTR 


Debug  and  Test 


31 


EIP 

EFLAGS 

CRO 

CR1 

CR2 

CR3 


MSW 

reserved  for  future  use 

page  fault  address  reg 

page  directory  base  reg 

IP 

Flags 


DRO 

DR1 

DR2 

DR3 

DR4 

DR5 

DR6 

DR7 

TR6 

TR7 


Breakpoint  address  0 


Breakpoint  address  1 


Breakpoint  address  2 


Breakpoint  address  3 


Intel  reserved 


Intel  reserved 


Breakpoint  status 


Breakpoint  control 


Test  control 


Test  status 


Figure  4:  386  CPU  registers 
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12.5  and  16  MHz,  approximately  twice  as  fast.  It  must  be 
emphasized  that  clock  rate  alone  is  an  inadequate  mea¬ 
sure  of  performance.  For  one  thing,  the  bandwidth  of  the 
386  is  also  twice  that  of  the  286;  that  is,  each  386  instruc¬ 
tion  is  capable  of  processing  32  bits  of  data,  whereas  the 
286  processes  only  16  bits.  Programs  written  in  high-level 
languages  that  are  recompiled  for  native  mode  can  also 
see  performance  gains  based  on  the  use  of  new  instruc¬ 
tions  and  addressing  modes. 

As  a  general  rule,  you  can  assume  that  programs  run¬ 
ning  in  emulation  mode  will  see  a  performance  gain 
equivalent  to  the  change  in  clock  rate  between  the  two 
computers  being  compared.  Assuming  you  are  compar¬ 
ing  a  6-MHz  286  with  a  12-MHz  386,  this  means  a  speedup 
of  two  times,  all  other  things  being  equal.  Comparing  a 
286  program  against  a  386  native  mode  program,  two 
times  should  be  the  minimum  performance  improve¬ 
ment.  Depending  on  the  application,  gains  of  four  to  five 
times  are  easily  attainable. 


Additional  Features 

One  unique  feature  of  the  386  architecture  is  its  support 
for  the  programmer.  In  addition  to  the  single-step  inter¬ 
rupt  (inf  1)  and  software  breakpoint  interrupt  (inf  3),  also 
found  on  the  8086  and  286,  the  386  provides  four  break¬ 
point  registers  that  can  be  set  to  match  on  instruction 
execution,  data  accessed,  or  data  written  for  a  given  ad¬ 
dress.  This  feature  allows  debuggers  written  for  the  386  to 
implement  commands  such  as  GO  til  variable  ZOT 
modified. 

Another  selling  point  for  the  processor  is  the  virtual 
8086  mode.  With  this  option,  an  operating  system  that 
runs  in  the  native  mode  (Unix,  for  example)  would  be 
able  to  run  MS-DOS  and  DOS  applications  as  subtasks.  Be¬ 
cause  programs  running  in  this  mode  actually  generate 
the  same  linear  addresses  as  an  8086  (0-1  megabytes),  this 
option  is  useful  only  in  an  operating  system  running  with 
paging  enabled  so  that  the  addresses  of  multiple  DOS  tasks 
can  be  mapped  to  their  different  physical  memory 
locations. 

Also,  for  those  who  cannot  abide  segmentation  of  any 
sort,  the  386  can  masquerade  as  a  linear-address-space 


Linear  Address 


Figure  S:  Linear-to-physical-address  translation 
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The  286/386  Pi 

Intel’s  protected  mode  processors,  the  80286  and  80386, 
use  a  variety  of  methods  to  safeguard  the  security  of 
data  belonging  to  one  process  from  corruption  by  an¬ 
other  process.  By  making  all  memory  references  indi¬ 
rect  (through  a  descriptor),  the  CPU  can  verify  that  the 
operations  specified  are  valid. 

The  access  rights  (AR)  byte  of  a  descriptor  contains 
the  key  to  the  operations  that  are  legal  for  the  object. 
Bits  in  the  AR  byte  specify  whether  the  object  is  cur¬ 
rently  present  in  memory,  the  privilege  level  of  the 
object,  and  the  type  of  object. 

When  a  program  is  running,  the  privilege  level  of 
the  code  segment  is  set  to  the  process's  current  privi¬ 
lege  level  (CPL).  There  are  four  privilege  levels,  ranging 
from  level  0  (most  privileged)  to  level  3  (least  privi¬ 
leged).  No  process  is  allowed  to  access  an  object  more 
privileged  than  itself.  Typically,  the  operating  system 
will  consist  of  segments  of  higher  privilege  than  appli¬ 
cations,  and  it  will  therefore  be  protected  from  acci¬ 
dental  or  malicious  attempts  at  modification. 

In  the  interests  of  efficiency,  certain  routines  are  of¬ 
ten  shared  between  processes.  I/O  libraries,  for  exam¬ 
ple,  are  often  part  of  the  operating  system  but  are  us¬ 
able  by  all  applications.  The  protection  model 
provides  an  object  called  a  gate  to  deal  with  this  situa¬ 
tion.  A  gate  is  a  descriptor  that  points  to  a  code  segment 
and  offset  of  a  valid  operating  system  entry  point.  Be- 

‘otection  Model 

cause  the  gate  is  a  descriptor,  it  has  a  privilege  level  of 
its  own,  separate  from  that  of  the  code  segment.  A 
program  requests  access  to  a  gate  by  issuing  a  FAR  call 
or  jump  to  the  gate.  If  no  privilege  violation  occurs,  the 

CPL  of  the  executing  process  is  set  to  the  privilege  of  the 
new  code  segment,  and  execution  continues  at  the 
privilege  level  of  the  operating  system.  Any  parame¬ 
ters  on  the  stack  are  copied  to  a  new  stack  with  the 
same  privilege  level  as  the  operating  system  so  that 
they  cannot  be  modified  by  the  caller.  When  the  called 
routine  executes  a  FAR  return,  the  CPL  is  reset  to  that  of 
the  caller. 

To  prevent  applications  at  the  same  privilege  level 
from  corrupting  one  another,  the  architecture  pro¬ 
vides  task  state  segments  (TSSs)  and  local  descriptor  ta¬ 
bles  (LDTs).  TSSs  provide  direct  hardware  support  for 
multitasking.  When  a  call  or  interrupt  is  executed 
through  a  task  gate,  all  the  registers  for  the  current 
process  are  saved  in  its  TSS,  and  all  the  registers  are 
reloaded  with  new  values  from  the  TSS  pointed  to  by 
the  task  gate.  One  of  the  registers  is  the  LDTR,  which 
points  to  an  LDT  for  the  task.  If  the  code  and  data  seg¬ 
ment  descriptors  for  each  task  are  stored  in  its  own 

LDT,  then  there  is  no  way  that  one  task  can  get  access  to 
memory  belonging  to  another  task  because  it  has  no 
way  to  reference  the  other  task's  descriptors. 

machine.  By  initializing  the  CS,  DS,  and  SS  registers  with 
a  descriptor  that  points  to  one  gigantic  4-gigabyte  seg¬ 
ment,  users  will  never  have  to  load  another  segment  reg¬ 
ister.  A  slight  variation  on  this  can  permit  a  simple  user/ 
supervisor  protection  model  that  fits  in  well  with  the  pag¬ 
ing  mechanism. 

Even  with  all  the  features  and  enhancements  found  in 
the  386,  though,  there  is  still  some  room  for  improvement. 

It  still  has  no  "store  pointer”  instruction  counterpart  to  the 
LDS  reg,  [memory  1  instruction  for  loading  pointers.  A  set  of 
conditional  "skip”  instructions  would  be  much  more  effi¬ 
cient  in  compiled  code  than  are  the  conditional  jumps  that 
are  currently  available.  Compilers  often  have  to  generate 
the  following  sequence  of  code  when  processing  if 
statements: 

jnz  LABI 

jmp  ELSE_CLAUSE 

LABI:  ;  then  clause 

The  jump-not-zero  forces  the  instruction  queue  to  be 
flushed,  which  degrades  performance.  Replacing  the  jnz 
with  a  skipnz  would  be  more  efficient. 

Finally,  for  use  in  tightly  coupled  multiprocessor  appli¬ 
cations,  Intel  should  have  provided  a  hardware  signal 
that  would  force  the  TLB  to  be  flushed.  With  the  current 
implementation,  if  one  processor  modifies  a  page  table 
entry  in  RAM,  another  processor  may  be  using  the  entry 
stored  in  its  on-chip  TLB,  which  could  contain  some  inva¬ 
lid  information. 

Summary 

Despite  the  quibbles  noted  above,  the  80386  has  been  well 
designed.  Elimination  of  the  64K  segment  size  restriction 
makes  it  a  pleasure  to  program  rather  than  a  pain.  The 
enhanced  architecture  makes  it  easier  for  compilers  to 
generate  efficient  code,  and  the  machine  itself  is  fast.  The 
ability  to  run  8086  code,  286  code,  and  native  code  simul¬ 
taneously  means  that  a  large  software  base  will  be  avail¬ 
able.  Programmers  also  will  appreciate  the  availability  of 
new  development  tools.  (See  inset  "80386  Development 
Tools,”  on  page  32.) 

Because  of  the  complexity  of  the  processor,  I  have  been 
able  only  to  highlight  some  of  its  most  important  new 
features.  I  hope  I  have  spurred  your  interest.  This  chip  is 
sure  to  have  an  important  effect  on  microcomputing  in 
the  near  future. 
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T\Z:  An  8-bit  to  16-bit 

Translator 


A  serious  deterrent  to  wide¬ 
spread  use  of  a  new  micro¬ 
processor  unit  (MPU)  is  the 
lack  of  software  available  for  it.  This 
observation  means  that  chip  design¬ 
ers  and  their  employers  are  biased  to¬ 
ward  upgrading  an  existing  MPU 
rather  than  designing  a  substantially 
improved  one.  The  availability  of 
software  also  influences  microcom¬ 
puter  manufacturers  in  their  choice 
of  an  MPU,  which  tends  to  inhibit  ma¬ 
jor  improvements  in  chip  design. 

A  major  advantage  of  16-bit  chips 
when  compared  to  8-bit  chips  is  sim¬ 
pler  high-level-language  compilation 
or  fewer  and  more  understandable 
lines  in  an  assembly-language  pro¬ 
gram.  This  leads  to  faster  and  less  ex¬ 
pensive  programming  because  the 
cost  of  program  development  and 
maintenance  is  more  closely  related 
to  the  number  of  lines  in  a  program 
than  it  is  to  the  size  of  the  object  code 
or  the  speed  of  operation.  In  my 
experience,  assembly-language 
NS320xx  programs  have  fewer  lines 
and  instructions  than  their  Z80  equiv¬ 
alents,  but  the  object  code  is  about  the 
same  size. 

Although  it  is  possible  to  write  en¬ 
tirely  new  programs  for  these  MPUs, 
it  is  often  expedient  to  convert  prov¬ 
en  programs  that  have  already  been 
written.  This  article  discusses  the 
conversion  of  programs  from  an  8-bit 
MPU  to  a  16-bit  MPU — specifically 
from  the  Z80  to  the  NS320xx — and  in¬ 
cludes  a  conversion  program  and 
some  examples  of  converted 
programs. 

High-Level  Language 

One  solution  to  the  problem  of  mov¬ 
ing  programs  written  for  one  MPU  to 
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is  philosophically 
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another  is  to  write  them  originally  in 
a  high-level  language.  Then,  only  a 
compiler,  and  perhaps  an  assembler, 
is  necessary  for  the  destination  MPU. 
This  has  been  done  to  a  limited  degree 
with  C  being  used  as  the  high-level 
language.  The  problem  with  this  ap¬ 
proach  is  that  a  program  written  in  C, 
when  compiled  for  an  8-bit  MPU,  may 
be  unacceptably  larger  and  slower 
than  the  same  program  written  in  as¬ 
sembly  language.  Based  on  their  expe¬ 
rience  with  8-bit  MPUs,  many  pro¬ 
grammers  do  not  believe  that  a 
compiled  high-level  language  pro¬ 
gram  can  approach  the  size  and  speed 
of  an  assembly-language  program. 

In  my  experience  with  the 
NS320xx  MPU,  however,  compiled  C 
programs  are  within  50  percent  of 
the  size  and  speed  of  equivalent  as¬ 
sembly-language  programs.  On  a  6- 
MHz  NS16032,  for  example,  the  com¬ 
piled  sieve  of  Eratosthenes  is  149 
bytes  long  and  runs  ten  times  in  4.2 
seconds;  written  in  assembly  lan¬ 
guage,  it  is  141  bytes  long  and  runs 
ten  times  in  3  seconds.  This  40  per¬ 
cent  penalty  in  speed  for  a  high-level 
language  is  tolerable  in  many  cases. 
In  general,  C-compiled  programs  on 
the  NS320xx  end  up  about  65  percent 
of  the  size  of  their  Z80  equivalents. 

Aside  from  the  size  and  speed  is¬ 
sue,  the  high-level-language  ap¬ 
proach  is  of  no  use  for  those  many 


useful  existing  programs  that  are 
available  only  in  assembly-language 
form;  for  these  some  sort  of  conver¬ 
sion  is  necessary. 

Conversion 

If  the  new  or  destination  MPU  is 
merely  an  upgrade  of,  but  philosoph¬ 
ically  similar  to,  an  older  one,  a  rela¬ 
tively  simple  conversion  is  possible. 
For  example,  converting  an  assem¬ 
bly-language  program  from  an  8080 
to  a  Z80  is  a  simple  matter,  and  pro¬ 
grams  are  available  for  doing  it. 

If  the  destination  MPU  is  philosoph¬ 
ically  different  from  the  original, 
however,  the  conversion  becomes 
more  difficult.  For  example,  conver¬ 
sion  from  the  Z80  to  the  MC6809  is 
harder  because,  even  though  the 
chips  have  similar  power,  their  in¬ 
struction  sets  are  philosophically  dif¬ 
ferent.  Converting  from  the  8080  or 
Z80  to  the  NS320xx  is  also  quite  diffi¬ 
cult  because  the  NS320xx  is  not  only 
substantially  more  powerful  than 
the  Z80  but  it  is  also  philosophically 
quite  different.  The  NS320xx  instruc¬ 
tion  set  is  more  similar  to  that  of  a 
VAX  than  to  any  8-bit  MPU,  and  assem¬ 
bly-language  source  code  for  the  VAX 
is  far  less  available  than  source  code 
for  8-bit  MPUs. 

In  order  to  execute  a  program  writ¬ 
ten  in  Z80  assembly  language  on  an 
NS320xx,  you  can  take  two  conversion 
approaches — write  a  simulator  pro¬ 
gram  that  enables  the  NS320xx  to  sim¬ 
ulate  the  instructions  of  the  Z80  or 
write  a  program  that  translates  the 
Z80  program  into  an  NS320xx 
program. 

The  problem  with  the  simulator 
approach  is  that  the  simulation  pro¬ 
cess  will  add  a  substantial  amount  to 
the  code  size  and  will  reduce  the 
speed  of  operation  to  a  fraction  of  the 
original  speed;  the  new  MPU  is  figura- 
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tively  running  with  both  hands  tied 
behind  its  back.  Thus,  if  you  are  in¬ 
terested  in  having  a  program  that  can 
be  executed  with  the  additional 
speed  and  power  of  the  NS320xx,  the 
translation  approach  makes  more 
sense.  Indeed,  why  should  you  both¬ 
er  to  convert  a  program  if  it  will  not 
execute  any  better  than  it  did  on  the 
original  MPU? 

An  additional  factor  to  consider  is 
whether  or  not  the  program  you 
want  to  convert  is  arithmetic,  partic¬ 


ularly  floating-point  arithmetic,  in¬ 
tensive.  If  it  is,  then  the  translation 
approach  will  lead  to  a  markedly  bet¬ 
ter  (smaller,  faster,  and  more  power¬ 
ful)  program  than  the  simulation  ap¬ 
proach.  This  is  because  the  larger 
operands  and  the  floating-point  co¬ 
processor  permit  floating-point- 
number  input,  arithmetic,  and  out¬ 
put  to  be  done  with  far  fewer 
instructions  than  are  necessary  with 
an  8-bit  chip.  For  example,  the  code 
for  a  BASIC  interpreter  with  floating¬ 
point  arithmetic  translated  to  the 
NS320xx  is  roughly  one-half  the  size 
of  the  original  Z80  version. 


You  must  also  decide  how  much 
"automatic”  translation  should  be 
done  and  how  much  if  any  "hand” 
translation  will  be  required.  I  devel¬ 
oped  the  translation  program  de¬ 
scribed  here  to  translate  three  differ¬ 
ent  Z80  programs,  and  initially  I 
envisioned  a  completely  automatic 
translation.  One  of  the  programs — 
the  BASIC  interpreter  mentioned  ear¬ 
lier — had  a  substantial  amount  of 
floating-point  arithmetic.  As  the 
translation  program  developed, 
however,  it  became  apparent  that  a 
totally  automatic  translation  ap¬ 
proach  was  forcing  the  NS320xx  to 
simulate  the  Z80;  the  translated  code 
was  three  times  the  size  of  the  origi¬ 
nal  and  would  have  executed  more 
slowly  than  the  original.  Thus,  it  be¬ 
came  evident  that  a  significant 
amount  of  hand  editing  was  neces¬ 
sary  in  order  to  end  up  with  a  really 
useful  NS320xx  program.  Some  of  the 
reasons  for  this  will  become  appar¬ 
ent  when  you  consider  the  two  chips 
and  the  translation  program  in  more 
detail. 

This  means  that  this  translation 
program,  TNZ,  is  not  automatic.  It  can 
do  most  of  the  conversion  process  but 
is  not  intended  to  and  generally  will 
not  yield  a  fully  executable  program. 
Some  editing  is  necessary  to  get  a  pro¬ 
gram  that  will  run;  insightful  editing 
will  yield  a  very  efficient  program. 

The  MS3ZOXX 

Briefly,  the  NS320xx  has  eight  general- 
purpose  registers  that  are  32  bits 
wide.  It  can  carry  out  8-,  16-,  or  32-bit 
arithmetic  and  logical  operations 
with  operands  in  the  registers  that  are 
addressed  through  registers  or  in 
memory.  An  operand  can  be  either 
data  or  an  address.  The  direction  of 
movement  in  an  instruction  is  from 
left  to  right,  opposite  to  that  of  a  Z80 
instruction.  The  size  of  the  operand  is 
specified  in  the  instruction — for  ex¬ 
ample,  .B  =  byte, .  W  =  word  (2  bytes), 
and  .D  =  double-word  (4  bytes). 

The  floating-point  coprocessor 
(FPU)  can  carry  out  either  32-bit  F  sin¬ 
gle-precision  or  64-bit  L  double-preci¬ 
sion  operations  on  operands  either  in 
the  FPU's  registers  or  in  memory,  as 
well  as  integer  to  floating-point  to  in¬ 
teger  conversions.  It  does  not  do  well 
with  operands  in  an  MPU  register. 

All  arithmetic  and  logical  instruc¬ 
tions  can  be  performed  on  operands 


SETVAL: 

CALL 

TSTV 

IS  A  VARIABLE  NAME? 

JR 

Z.QWHAT 

"WHAT?”  NO  VARIABLE 

PUSH 

HL 

SAVE  ADDRESS  OF  VAR. 

LD 

A,'  =  ’ 

CALL 

TSTC 

IS  "=”  SIGN 

JP 

NZ.QWHAT 

NO  =?? 

CALL 

EXPR 

EVALUATE  EXPR. 

LD 

B,H 

VALUE  IN  BC  NOW 

LD 

C,L 

POP 

HL 

GET ADDRESS 

LD 

(HL),C 

SAVE  VALUE 

INC 

HL 

LD 

(HL),B 

RET 

;ADDRESS  +  1  OF  VAR  IN  R3 

Table  1:  Original  Z80  LET  statement  interpreter 


SETVAL: 

CALL 

TSTV 

IS  A  VARIABLE  NAME? 

BEQ 

QWHAT 

“WHAT?”  NO  VARIABLE 

MOV.D 

R3.TOS 

SAVE  ADDRESS  OF  VAR. 

MOV.B 

’=’,R0 

BSR 

TSTC 

IS  “  =  ”  SIGN 

BNE 

QWHAT 

NO  =?? 

BSR 

EXPR 

EVALUATE  EXPR. 

MOV.B 

RH,RB 

VALUE  IN  BC  NOW 

MOV.B 

R3,R1 

MOV.D 

TOS.R3 

GET  ADDRESS 

MOV.B 

R1,(R3) 

SAVE  VALUE 

ADDQ.W 

+  1.R3 

MOV.B 

RB,(R3) 

RET 

;ADDRESS  +  1  OF  VAR  IN  R3 

Table  2:  Original  TNZ  output  for  LET  interpreter 


SETVAL: 

CALL 

TSTV 

IS  A  VARIABLE  NAME? 

BEQ 

QWHAT 

“WHAT?”  NO  VARIABLE 

MOV.D 

R3.TOS 

SAVE  ADDRESS  OF  VAR. 

MOV.B 

’=’,R0 

BSR 

TSTC 

IS  “  =  ”  SIGN 

BNE 

QWHAT 

NO  =?? 

BSR 

EXPR 

EVALUATE  EXPR,  VALUE  IN  R3 

MOV.D 

TOS.R1 

GET  ADDRESS  BACK 

MOV.D 

R3,0(R1) 

SAVE  VALUE  IN  R3 

RET 

ADDRESS  OF  VAR  IN  R1 

Table  3:  Improved  LET  interpreter 
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in  memory  addressed  in  several  dif¬ 
ferent  modes  (including  the  stack 
pointer)  so  a  program  may  use  no 
registers  at  all!  Indeed,  unless  an  op¬ 
erand  is  accessed  repeatedly,  it  is  just 
as  well  left  in  memory. 

The  Translation  Program 

The  program  itself  is  based  on  a  ge¬ 
neric  assembler  program  that  I  have 
used  for  various  MPUs,  including  the 
8080,  MC68000,  and  NS320xx.  The 
source  is  about  1,200  lines  long,  and 
the  8080  code  is  18,000  bytes  (NS320xx 
code  is  11,500  bytes),  about  the  same 
size  as  the  8080  assembler  but  much 
shorter  than  the  other  assemblers. 
Remnants  of  the  other  programs  re¬ 
main,  for  which  I  apologize. 


TNZ  operates  like  an  assembler 
does  in  that  its  input  is  an  assembly- 
language  file.  It  differs  in  that  it  uses 
only  a  single  pass  and  its  output  is  an¬ 
other  assembly-language  file — in  AS¬ 
CII — instead  of  the  bit  patterns  pro¬ 
duced  by  an  assembler.  By  use  of 
#ifdefs  it  can  be  compiled  by  two  C 
compilers  that  differ  with  regard  to 
their  disk  input/output  library 
functions. 

It  consists  of  four  files:  TNZH.C, 
TNZ.C,  TNZ2.C,  and  TNZO.C.  The  first  is 
the  header  file,  which  contains  con¬ 
stants  and  global  variables.  The  sec¬ 
ond  is  the  main  body  of  the  transla¬ 
tion  process.  The  third  consists  of 
fairly  routine  functions  for  initializa¬ 
tion,  opcode-table  loading  and  look¬ 
up,  integer  conversion,  file  input/ 
output,  and  so  on.  The  fourth  consists 
of  the  opcode  table,  which  is  read 


from  the  disk  during  the  initializa¬ 
tion  process.  The  opcode  entry  for 
each  operation  and  register  has  the 
source  (Z80)  opcode  in  ASCII;  the  desti¬ 
nation  (NS320xx)  opcode  in  ASCII;  and 
two  16-bit  words  of  operation  class, 
size,  and  modifier. 

In  TNZ,  the  main(  )  function  sizes 
memory,  calls  the  initialization  func¬ 
tion  (which  reads  in  the  opcode  table, 
checks  for  user  options,  and  opens 
the  output  file),  and  then  calls  dos- 
canl ).  The  program  is  capable  of 
translating  multiple  files,  so  doscanf ) 
opens  the  input  file(s)  and  starts  read¬ 
ing,  converting,  and  outputting  each 
line  of  the  input. 

The  heart  of  doscanf  j  is  a  loop 
through  rdlinef  ),  dolinef  ),  and  out- 
code(  ).  Each  noncomment  line  is 
parsed  in  rdline(  ):  symbols  are  sim¬ 
ply  copied  to  the  output  in  rdsym- 
boK  J;  operations  and  modifiers  are 
converted  in  rdopcodef  J;  and  oper¬ 
ands  are  converted  in  rdoperandsf ). 
At  this  point,  the  converted  operation 
and  operands  are  in  temporary 
buffers. 

Next,  in  dolinef ),  one  of  three  ac¬ 
tions  can  occur,  depending  on  the 
particular  operation  being  translat¬ 
ed.  One,  in  the  case  of  a  simple  trans¬ 
lation,  the  temporary  buffers  are 
copied,  with  operation  size  added 
and  operands  reversed,  to  the  output 
buffer  in  doarmovf ).  Two,  special 
conversion  steps  are  carried  out  in 
dospcsf  ) — for  example,  Z80  opera¬ 
tions  that  have  an  implied  accumula¬ 
tor  destination  need  to  have  the  desti¬ 
nation  added  explicitly.  Three, 
program  flow  operations  are  han¬ 
dled  in  doprflf  ) — for  example,  Z80 
conditional  calls  and  returns  need 
special  handling. 

In  any  event,  after  dolinef  )  the 
converted  line  is  ready  to  be  passed  to 
the  output  file  by  outcodef  ).  Then, 
the  next  line  is  read  in  rdlinef  )  and 
the  above  loop  is  repeated  until  the 
end  of  the  file,  at  which  point  dos¬ 
canf  )  closes  the  input  file  and  either 
moves  to  the  next  input  file  or  closes 
the  output  file  and  stops. 

This  is  a  general  summary  of  the 
program.  Most  of  it  is  straightforward 
programming;  the  tricky  stuff  is  in 
dospcsf  )  and  doprflf  )  when  a  simple 
translation  is  not  possible.  Because  I 
use  it  with  two  different  C  compilers, 
I  have  tried  to  avoid  compiler-specific 
programming. 


TEST  IF  TEXT  IS  A  NUMBER, IF  NOT  RET  0  IN  B  &  HL 

TSTNUM:  LD 

HL,0 

LD 

B,H 

CALL 

IGNBLK  ;NEXT  NON-BLANK  CHAR 

TSTNML:  CP 

'O' 

RET 

C 

;IF  NUMB,  MAKE  BINARY  IN  HL  &  A=NO.  OF  DIG. 

CP 

RET 

NC 

LD 

A,0F0 

AND 

H 

JP 

NZ.QHOW 

INC 

B 

PUSH 

BC 

LD 

B,H  ;HL=10;HL+(NEW  DIGIT) 

LD 

C,L 

ADD 

HL,HL 

ADD 

HL,HL 

ADD 

HL,BC 

ADD 

HL.HL 

LD 

A,(DE) 

INC 

DE 

AND 

0FH 

ADD 

L 

LD 

L,A 

LD 

A,0 

ADC 

H 

LD 

H,A 

POP 

BC 

LD 

A,(DE) 

JP 

P, TSTNML 

Table  4:  Z80  string-to- number  conversion 
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Translation  Problem  Areas 
Half  Registers 

Direct  translation  of  many  Z80  regis¬ 
ter  operations  involving  16-bit  and 
many  8-bit  operands  presents  no 
problem.  However,  you  can  access  di¬ 
rectly  only  the  lower  8  or  16  bits  in  the 
NS320xx  registers.  This  means  that  the 
practice  of  directly  accessing  the  up¬ 
per  8-bit  halves  of  the  Z80 — BC  B  DE 
'D',  HL  'H'  (and  IX  and  1Y  registers,  if 
you’re  cute)  is  not  possible  on  the 
NS320xx. 

You  can  solve  this  problem  by  sim¬ 
ulating  Z80  registers  in  memory  and 
accessing  their  two  bytes  separately, 
but  this  is  not  a  very  efficient  solu¬ 
tion.  What  I  did  was  to  treat  the 
NS320xx  registers  arbitrarily  as  fol¬ 
lows — BO  =  AF,  R1  =  C  or  BC,  B2  = 
DE  or  E,  and  R3  =  HL  or  L  and  to  use 
simulated  registers  in  memory  for 
the  high  halves  B,  D,  and  H. 

If  the  high  and  low  half  registers 
are  being  used  as  separate  operands, 
this  works  well.  If  they  are  actually 
the  two  bytes  of  one  16-bit  operand, 
though,  then  some  hand  changes  are 
necessary. 

Say  you  wanted  to  load  DE  with  the 
data  at  (HL): 

LD  E,(HL) 

INC  HL 

LD  D,(HL) 

TNZ  will  translate  this  to: 

MOV.B  (R3),R2 

ADDQ.W  +1,R3 

MOV.B  (R3),RD 

Although  this  translation  will  not 
work  properly,  you  can  change  it  to 
the  one  instruction  MOV.W  (R3),B2 — 
the  ADDQ.W  +1,B3  is  probably  un¬ 
necessary.  This  change  is  quite  easy 
to  spot  by  eye,  but  for  TNZ  to  figure 
this  out  would  take  a  more  insightful 
translator  program  than  I  am  willing 
to  write. 

Flags 

A  great  difference  exists  between  the 
two  MPUs'  flags  and  their  use.  Again, 
you  could  simulate  the  Z80  flag  ac¬ 
tions,  but  this  would  result  in  a  great 
deal  of  often  unnecessary  code  and 
we  are  interested  in  an  efficient  trans¬ 
lated  program.  The  Z80  has  three  con¬ 
stantly  used  flags — zero,  carry,  and 
positive.  The  same  flags  are  affected 


by  arithmetic,  logical,  and  compari¬ 
son  operations.  The  NS320xx  has  a  si¬ 
milar  set  of  flags,  but  they  operate 
differently.  Arithmetic  operations  af¬ 
fect  the  carry  flag  only.  Logical  opera¬ 


tions — AND,  OR,  and  so  on — do  not  af¬ 
fect  the  flags.  Comparisons  affect  the 
equal  (zero),  less-than,  greater-than 
(signed),  lower-than,  and  more-than 
(unsigned)  flags.  Thus,  an  explicit 


;Z80  -  NS320XX  Translator;  RAC  03/26/86 

TEST  IF  TEXT  IS  A  NUMBER, IF  NOT  RET  0  IN  B  &  HL 

TSTNUM: 

MOV.W 

0,R3 

MOV.B 

RH,RB 

BSR 

IGNBLK 

;NEXT  NON-BLANK  CHAR 

TSTNML: 

CMP.B 

’0’,R0 

BLS 

XYZ1 

RET 

XYZ1: 

;IF  NUMB,  MAKE  BINARY  IN  HL  &  A=NO.  OF  DIG. 

CMP.B 

’:’,R0 

BHI 

XYZ2 

RET 

;??? 

XYZ2: 

MOV.B 

0F0,R0 

AND.B 

RH,R0 

CMPQ.B 

0,R0 

BNE 

QHOW 

ADDQ.B 

+  1  ,RB 

MOV.D 

R1.TOS 

MOV.B 

RH,RB 

;HL=10;HL+(NEW  DIGIT) 

MOV.B 

R3,R1 

ADD.W 

R3,R3 

ADD.W 

R3.R3 

ADD.W 

R1,R3 

ADD.W 

R3,R3 

MOV.B 

(R2),R0 

ADDQ.W 

+  1  ,R2 

AND.B 

0FH,R0 

ADD.B 

R3.R0 

MOV.B 

R0,R3 

MOV.B 

0,R0 

ADDC.B 

RH.RO 

MOV.B 

R0,RH 

MOV.D 

TOS.R1 

MOV.B 

(R2),R0 

CMPQ.B 

0,R0 

BLE 

TSTNML 

;??? 

Table  5:  TNZ  output  for  string-to-number  convertor 


;TEST  IF  TEXT  IS  A  NUMBER;  RETURN  NO.  IN  R3,  DIGITS  IN  R2 

;R5  CONTAINS  TEXT  POINTER. 

; IGNBLK  RETURNS  NEXT  NON-BLANK  CHARACTER  IN  R0 

TSTNUM: 

MOVQ.D 

0,R3 

ZERO  NUMBER 

MOVQ.B 

0,R2 

ZERO  DIGITS 

BSR 

IGNBLK 

NEXT  NON-BLANK  CHAR 

TSTNML: 

AND.D 

7FH.R0 

STRIP  HIGH  BITS 

SUB.B 

’O’.RO 

BCS 

TSTNMZ 

IS  NG,  RETURN 

CMP.B 

10, R0 

<  10? 

BHI 

TSTNM2 

OK,  TAKE  CHAR 

TSTNMZ: 

RET 

TSTNM2: 

ADDQ.B 

1  ,R2 

COUNT  THE  DIGIT 

MUL.D 

10,  R3 

MULTIPLY  NO.  BY  10 

ADD.D 

R0,R3 

ADD  IN  NEW  DIGIT 

ADDQ.D 

1  ,R5 

MOVE  TO  NEXT  CHAR 

MOV.B 

0(R5),R0 

GET  NEXT  CHAR 

; 

BR 

TSTNML 

GO  FOR  NEXT 

Table  G:  Improved  string-to-number  convertor 
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comparison  is  required  to  set  the 
equal  flag,  for  example. 

TNZ  keeps  track  of  previous  in¬ 
structions,  and  if  a  conditional  jump, 
call,  or  return  is  encountered  that  has 
not  been  preceded  by  an  explicit 
comparison,  then  the  code  for  a  com¬ 
parison  with  zero  is  produced  to  set 
the  flags.  This  is  less  than  perfect, 
particularly  when  a  subroutine  has 
been  called  that  is  to  return  informa¬ 


tion  in  the  flags.  There  is  no  way  for 
the  translator  to  know  what  has  been 
done  in  the  subroutine,  so  a  compari¬ 
son  with  zero  may  not  be  appropri¬ 
ate  and  is  not  carried  out. 

Examples 

The  following  is  an  example  of  some 
original  translated  and  edited  code 
that  is  not  particularly  arithmetic  in 
nature.  This  is  the  (LET)  X  =  ??  part  of 
an  integer  BASIC  interpreter.  The 
code  ends  up  about  the  same  size  as 
the  original,  but  double-precision  val¬ 


ues  are  being  handled.  To  handle 
floating-point  values  would  involve 
trivial  changes  on  the  NS320xx  but 
would  involve  substantial  modifica¬ 
tion  to  the  Z80  program. 

Table  1,  page  42,  shows  the  Z80 
code,  and  Table  2,  page  42,  shows  this 
code  after  TNZ  has  translated  it.  No¬ 
tice  the  half-register  problems  in¬ 
volving  RB.  These  two  instructions 
and  the  ADDQ.W  +1,R3  need  to  be 
eliminated,  and  the  size  of  the  R3,R1 
and  R1,(R3)  moves  are  changed  to 
double  words — .D — a  relatively  sim¬ 
ple  editing  task.  When  double-preci¬ 
sion  integer  arithmetic  is  executed, 
the  translated  code  becomes  that 
shown  in  Table  3,  page  42. 

Another  example  of  translated 
code  involves  the  conversion  of  a  text 
string  into  a  binary  number.  This 
somewhat  arithmetic  example 
points  out  the  advantages  of  the 
translation  rather  than  simulation 
approach  because  a  great  many  of 
the  instructions  needed  for  the  Z80 
can  be  eliminated.  Note  that  this  rou¬ 
tine  as  finally  translated  can  be  used 
lor  floating-point  number  conver¬ 
sion  with  only  a  few  changes. 

Table  4,  page  44,  shows  the  Z80  rou¬ 
tine,  and  Table  5,  page  45,  shows  the 
translated  version.  Notice  that  RET  C 
has  been  changed  into  the  sequence 
BLS  XYZ1,  RET,  XYZl: . . .  because  the 
preceding  operation  was  a  compari¬ 
son  and  because  the  NS320xx  has  no 
conditional-return  instructions.  This 
routine,  as  directly  translated,  is  load¬ 
ed  with  half-register  problems  and 
would  not  work.  Some  editing,  how¬ 
ever,  will  result  in  the  routine  shown 
in  Table  6,  page  45,  which  is  much 
shorter  and  more  powerful  because 
it  handles  32-bit  integers  of  nine  or 
more  digits.  Note  in  the  test  following 
the  SUB.B  '0',R0  instruction  in  Table  6 
that  the  carry  flag  is  tested,  and  fol¬ 
lowing  the  CMP.B  JO, RO,  the  higher- 
than  flag  is  tested. 

DDJ 


The  listing  for  this  article  is  present¬ 
ed  in  a  machine-readable  form — a 
Softstrip  produced  by  Cauzin  Sys¬ 
tems.  The  strips  begin  on  page  84.  The 
teyt  of  the  listing  is  available  for  down¬ 
loading  in  the  DDJ  Electronic  Edition 
on  CompuServe. 


46 


Dr.  Dobb's  Journal,  October  1986 

693 


REVIEWS 


Modula-2  Compilers 
for  the  IBM  PC 


This  comparative  review  looks 
at  four  Modula-2  compilers 
for  the  IBM  PC.  The  compilers 
come  from  Logitech,  Interface  Tech¬ 
nology  Corp.  (ITC),  Modula  Corp.,  and 
PColliers  Systems. 

Logitech  offers  its  Modula-2/86 
overlayed  four-pass  compiler  and 
linker  in  three  configurations:  a  base 
system,  a  base  system  with  8087  sup¬ 
port,  and  Modula-2/86  Plus.  For  this 
review  I  evaluated  Modula-2/86  Plus, 
which  I’ll  refer  to  as  simply  Modula- 
2/86  for  the  rest  of  the  review.  This  is 
a  full  system  that  runs  on  machines 
with  S12K  RAM,  taking  advantage  of 
the  large  memory  to  increase  the 
speed  of  compilation.  Support  for  the 
8086,  8087,  80186,  80286,  and  80287 
chips  is  included,  and  it  comes  with  a 
fully  linked  compiler  and  linker.  Logi¬ 
tech  also  includes  the  MOD  text  editor, 
which  can  become  the  heart  of  an  in¬ 
tegrated  software-development  sys¬ 
tem. 

ITC  sells  the  Modula-2  System  Devel¬ 
opment  System  (M2SDS),  a  window- 
based  integrated  system  containing  a 
compiler,  linker,  librarian,  and  built- 
in  syntax-oriented  editor.  The  compa¬ 
ny  also  sells  an  advanced  software-de¬ 
velopment  version,  SDS-XP,  which 
includes  an  extended  library,  the 
M2MAKE  utility,  and  the  Foreign  Ob¬ 
ject  Module  Importer  (FOMI).  The 
FOMI  utility  enables  software  develop¬ 
ers  to  import  object  modules  created 
by  an  8088/8086  assembler  into  the 
SDS  library.  I  received  the  M2SDS  ver¬ 
sion  for  this  review. 

Modula  Corp.  has  launched  its  new 
PC  Modula-2,  a  one-pass  native  com¬ 
piler,  to  replace  a  previous  version 


Namir  Clement  Shammas,  4814  Mill 
Park  Ct.,  Glen  Allen,  VA  23060 


by  Namir  Clement 
Shammas 


Four  compilers  from 
the  latest  generation 
are  compared. 


that  generated  much  slower  code.  PC 
Modula-2  has  neither  a  built-in  editor 
nor  an  integrated  environment. 

PColliers  Systems,  a  newcomer  to 
the  arena  of  Modula-2  vendors,  offers 
Modula-2PC,  a  one-pass  native  com¬ 
piler.  The  company  will  come  out 
with  8087  support,  an  editor,  and  a 
debugger  in  late  1986. 

Compilers  and  Linkers 
Modula-2/86 

You  can  compile  one  or  more  source 
code  files  with  the  four-pass  Modula- 
2/86  compiler  in  one  of  two  ways. 
The  source  file  names  can  follow  M2 
COMP,  which  you  type  at  the  DOS 
command  level.  This  is  interpreted 
by  the  Modula-2  shell  as  a  request  to 
compile  the  listed  files  and  then  exit 
back  to  DOS.  In  the  second  method, 
you  simply  type  M2  COMP  from  DOS 
to  invoke  the  compiler,  which  in 
turn  prompts  you  for  a  source  file 
name.  At  the  end  of  compilation,  an¬ 
other  similar  prompt  appears.  This 
allows  you  to  compile  another  file  or 
exit  to  DOS  by  pressing  the  Escape 
key.  Logitech  also  provides  a  fully 
linked  compiler  (M2C.EXE),  which 
runs  faster  than  the  standard  over¬ 
layed  version.  The  Modula-2/86  com¬ 
piler  produces  LOD  files  that  run  un¬ 
der  the  Modula-2  shell.  The  LOD2EXE 
program  is  used  to  convert  the  LOD 
files  into  stand-alone  .EXE  files  that 


run  directly  from  DOS. 

The  compiler  has  several  direc¬ 
tives  or  switches,  whose  default 
states  are  shown  in  the  manual.  The 
query  and  auto-query  switches  alter 
the  file-search  mechanism  and  strat¬ 
egy.  The  default  search  uses  the  mod¬ 
ule  name  to  construct  the  file  name. 
There  is  a  switch  for  the  systematic 
generation  of  a  listing  and  another 
switch  that  invokes  the  latter  only 
when  the  compiler  detects  an  error. 
The  listings  can  include  a  header,  a 
footer,  and  a  date — each  included  by 
turning  on  a  switch.  There’s  an  emu¬ 
lator/coprocessor  switch  to  control 
the  generation  of  in-line  8087  code  as 
well  as  a  switch  to  create  code  for  the 
80186/80286.  The  default  is,  of 
course,  8086/8088  code.  Other 
switches  are  used  to  perform  stack 
test,  range,  and  overflow  checking 
and  index  and  nil  pointer  tests.  The 
alignment  option  positions  all  multi¬ 
byte  variables  on  even  address 
boundaries.  The  collection  of  switch¬ 
es  can  be  included  inside  comments 
in  the  source  files. 

You  invoke  the  Modula-2/86  linker 
in  a  fashion  similar  to  the  way  you 
invoke  the  compiler.  Again,  linked 
file  names  can  be  included  on  the  DOS 
command  line.  Moreover,  there  is  a 
fully  linked  version  (M2L.EXE).  The  in¬ 
clusion  of  file  names  on  the  DOS  com¬ 
mand  line  makes  possible  the  use  of 
batch  files  to  invoke  the  compiler 
and  linker.  Using  the  fully  linked  ver¬ 
sions  of  the  compiler  and  linker,  the 
whole  process  becomes  even  faster. 

The  linker  has  several  .options,  in¬ 
cluding  a  base-layer  option  for  use  in 
compiling  overlays.  The  query  and 
auto-query  options  operate  similarly 
to  those  of  the  compiler.  The  large 
option  enables  the  number  of  linked 
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modules  to  jump  from  200  to  400.  You 
generate  map  files  by  turning  on  the 
corresponding  switch. 

M2SDS 

ITC’s  M2SDS  uses  pull-down  menu 
windows  and  pop-up  windows  ex¬ 
tensively.  When  users  first  enter 
M2SDS,  it  displays  the  Library-Tray 
and  the  Menu-Pick  windows.  The  Li¬ 
brary-Tray  is  used  to  recall  packed  li¬ 
braries  of  modules.  The  Menu-Pick 
window  offers  five  options:  Desk,  File, 
Tools,  Edit,  and  Controls.  The  Desk 
contains  a  calculator,  ASCII  table,  time 
display,  and  help.  The  File  option  is 
used  to  save  an  edited  file,  quit  the  edi¬ 
tor  without  saving  it,  and  exit  back  to 
DOS.  The  Tools  option  provides  op¬ 
tions  to  edit,  compile,  link,  display  a 
file's  contents,  read/write  source 
code  in  ASCII  form,  and  escape  to  DOS 


Vendors 

Modula-2  PC 

PCollier  Systems 

7925-A  North  Oracle  Rd.,  Ste.  390 

Tucson,  AZ  85704 

(800)  522-2060 
$59.95 

Reader  Service  Number  37 

M2SDS 

Interface  Technologies  Inc. 

3336  Richmond,  Ste.  200 
Houston,  TX  77098 
(713)  523-8422 
$80.88 

Reader  Service  Number  38 

Modula-2/86 
Logitech  Inc. 

805  Veterans  Blvd.,  Ste.  201 
Redwood  City,  CA  94063 
(415)  365-9852 
$89,  base  system 
$129,  8087  support  system 
$189,  512K  memory  usage 
Reader  Service  Number  39 

PC  Modula-2 
Modula  Corp. 

950  North  University  Ave. 

Provo,  UT  84604 

(801)  375-7400 
$150 

Reader  Service  Number  40 


(you  return  to  M2SDS  by  typing  EXIT  in 
DOS).  The  Edit  option  allows  you  to 
mark,  cut,  copy,  delete,  and  paste  edit¬ 
ed  text.  The  Controls  option  enables 
you  to  resize  and  move  a  currently 
displayed  window,  as  well  as  toggle 
the  PC  beeper. 

The  ITC  compiler  is  integrated  with 
the  syntax-oriented  editor,  and  you 
invoke  it  by  pressing  the  Ctrl-\  key 
combination.  A  window  appears  dis¬ 
playing  the  compiler  switches  and 
their  current  status.  The  switches  in¬ 
clude  those  for  use  of  8087,  stack, 
range,  and  arithmetic  checking.  If 
the  compiler  finds  an  error,  it  will 
display  a  diagnostic  message  and 
place  the  cursor  at  the  first  error  lo¬ 
cation. 

The  compiler  can  remember  20  er¬ 
rors,  which  you  can  examine  in  se¬ 
quence  by  pressing  Ctrl-E. 

The  M2SDS  linker  can  be  invoked 
from  the  Edit/Compile/Link  option 
box.  The  linker,  which  has  no 
switches,  produces  .EXE  files  and  can 
also  link  overlays. 


PC  Modula-2 

The  PC  Modula-2  compiler  is  invoked 
from  DOS  by  typing  modula  followed 
by  an  optional  source  file  name.  If 
the  file  name  is  omitted,  the  compiler 
will  prompt  for  one.  The  compiler 
options  are  typed  after  the  file  name 
at  either  the  DOS-level  or  the  compil¬ 
er  prompt.  At  the  end  of  program 
compilation,  you  are  asked  to  type  in 
another  file  name  or  exit.  When  the 
compiler  detects  errors,  it  displays  di¬ 
agnostic  messages  on  the  screen  and 
in  the  listing  file  if  generated. 

The  PC  Modula-2  compiler  has  six 
switches.  They  control  range,  stack, 
and  arithmetic  overflow  checking.  In 
addition,  they  affect  generating  a  list¬ 
ing  file,  query  for  symbol  file  names, 
and  display  information  about  the 
compiler  version. 

PC  Modula-2  offers  three  formats 
for  compiled  programs:  unlinked, 
linked,  and  executable.  Unlinked  ob¬ 
ject  files  contain  code  for  the  program 
itself  and  none  for  any  module  it  uses. 
They  are  executed  by  invoking  the 
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Modula-2/86 

M2SDS 

PC  Modula-2 

Modula-2PC 

Version 

2.0 

2.00 

1.0 

1.0 

Compiler 

yes 

yes 

yes 

yes 

Number  of  passes 

4 

incremental 

i 

i 

Linker 

yes 

yes 

yes 

no 

Editor 

yes(opt) 

yes 

no 

no 

Syntax -oriented 

no 

yes 

n/a 

n/a 

Produce  M-code 

no 

no 

no 

no 

Produce  native  code 
Optional  post-mortem 

yes 

yes 

yes 

yes 

debugger 

Optional  run-time 

yes 

no 

no 

no 

debugger 

yes 

yes 

yes 

no 

Table  1:  General  comparisons 


Modula-2/86 

M2SDS 

PC  Modula-2 

Modula-2PC 

87  support 

yes 

yes1 

yes 

no 

Absolute  variables 

yes 

yes 

yes 

yes 

Address 

yes 

yes 

yes 

yes 

Array 

yes 

yes 

yes 

yes 

Bit  set 

yes 

yes 

yes 

yes 

Boolean 

yes 

yes 

yes 

yes 

Byte 

yes 

yes 

no 

no 

Cardinal 

yes 

yes 

yes 

yes 

Character 

yes 

yes 

yes 

yes 

Enumerated 

yes 

yes 

yes 

yes 

Integer 

yes 

yes 

yes 

yes 

Long  integer 

LongSet  library 

no 

yes 

yes 

yes 

support 

no2 

yes 

yes 

no 

Bytes  in  REAL 

8 

8 

4 

8 

Export  opaque  data 

yes 

yes 

yes 

yes 

Pointer 

yes 

yes 

yes 

yes 

Proc.  type 

yes 

yes 

yes 

yes 

Procedural  parameter 

yes 

yes 

yes 

yes 

Process 

yes 

yes 

yes 

yes 

Real 

yes 

yes 

yes 

yes 

Record 

yes 

yes 

yes 

yes 

Set 

yes 

yes 

yes 

yes 

Subrange 

yes 

yes 

yes 

yes 

WORD 

yes 

yes 

yes 

yes 

1  Tests  showed  support  severely  malfunctioning. 

2  Available  with  the  Logitech  Translator  for  Turbo  Pascal  programs 


Table  2:  Data  types 


Modula-2/86 

M2SOS 

PC  Modula-2 

Modula-2PC 

Assembly-language 

interface 

yes 

yes 

yes 

yes 

Chaining 

yes 

yes 

yes 

yes 

Concurrent  processes 

yes 

yes 

yes 

yes 

Cursor/screen  control 

no 

yes 

no 

yes 

DOS  calls 

yes 

yes 

yes 

yes 

High-res  graphics 

no 

yes 

yes 

no 

In-line  code 

yes 

yes 

no 

yes 

Interrupts 

yes 

yes 

no 

no 

Mouse  interface 

yes 

yes 

yes 

no 

Overlays 

yes 

yes 

yes 

yes 

Time/date 

yes 

yes 

yes 

yes 

Table  3:  Programming  features 
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program  loader,  M2XA.EXE,  which  is 
responsible  for  an  on-the-fly  module 
linking  and  program  execution.  The 
second  alternative  is  to  use  the  linker 
LINKRLX  for  linking  the  object  files  of 
the  compiled  program  and  library 
modules  employed.  The  program 
loader  is  still  needed  to  run  the  linked 
file,  but  the  loading  operation  is  faster. 
The  third  alternative  is  to  invoke  the 
linker  LINKEXE  for  linking  the  pro¬ 
gram  object  file  with  the  library  mod¬ 
ules  and  run-time  support,  producing 
a  stand-alone  .EXE  file.  PC  Modula-2's 
two  linkers  operate  similarly  to  the 
way  in  which  the  compiler  does. 
LINKRLX  has  one  directive — namely, 
the  query  option — whereas  LINKEXE 
has  no  directives. 

ModuIa-2PC 

The  Modula-2PC  compiler  is  invoked 
from  DOS  by  typing  m2pc  followed  by 
an  optional  program  source  file 
name  and  compiler  switches.  If  the 
file  name  is  omitted  at  the  DOS  level, 
the  compiler  prompts  you  for  one. 
There  are  four  compiler  switches. 
They  control  range  checking  (for  ar¬ 
ray  indices  and  verfication  of  valid 
integer  and  long  integer  values),  nil 
pointer  check,  and  conversion  of 
source  file  text  into  uppercase.  The 
fourth  switch  is  used  to  compile  a  sin¬ 
gle  file  and  exit  to  DOS.  Normally,  the 
compiler  prompts  for  another  file 
once  the  current  one  is  processed.  Er¬ 
ror  messages  are  sent  to  a  ,LST  file  and 
are  not  displayed  on  the  screen. 

Modula-2PC  provides  M2X.EXE  as  a 
run-time  environment.  You  can  in¬ 
voke  its  sole  directive  to  create  a 
stand-alone  .EXE  file.  The  manual 
states  that  there  is  no  link  step.  Thus 
M2X.EXE  has  a  dual  role — it’s  used  ei¬ 
ther  to  run  your  compiled  program 
or  to  produce  an  .EXE  file  and  stop. 

Editors 

Modula-2/86 

The  MOD  editor  that  Logitech  offers 
to  go  along  with  its  Modula-2/86  com¬ 
piler  and  linker  has  several  interest¬ 
ing  features.  It  operates  as  a  free¬ 
form  editor  with  optional  macros  for 
program  constructs.  Moreover,  it 
supports  windows  and  a  mouse  and 
becomes  the  core  of  an  integrated 
system.  You  can  invoke  the  compiler 
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or  linker  or  run  any  program  from 
within  the  editor  and  return  to  it 
upon  either  completion  or  interrup¬ 
tion.  When  compilation  errors  occur, 
the  MOD  editor  remembers  them  and 
allows  you  to  view  the  compiler  er¬ 
ror  messages  as  a  circular  list  of  mes¬ 
sages  appearing  inside  a  window. 

The  Emacs-like  editor  is  very  easy 
to  use.  You  use  function  keys  to  dis¬ 
play  the  main  menu  (which  appears 
as  a  pop-up  window)  or  to  carry  out  a 
variety  of  tasks,  such  as  calling  an  on¬ 


Table  4:  File  I/O  library  support 


Table  S:  Concurrency  features 


line  help  screen  for  the  MOD  com¬ 
mands,  loading  and  saving  files,  call¬ 
ing  the  compiler  or  linker,  and 
invoking  a  very  fast  syntax  checker. 
The  latter  verifies  the  basic  Modula-2 
syntax;  it  does  not  detect  misspelled 
variables,  undeclared  identifiers,  and 
so  on.  In  other  words,  the  MOD  syntax 
checker  does  not  duplicate  the  com¬ 
piler’s  task  of  verifying  the  correct¬ 
ness  of  the  source  code,  but  it  is  useful 
for  detecting  missing  colons,  semico¬ 
lons,  and  other  Modula-2  keywords. 

MOD  supports  multiple  windows 
that  can  be  opened  vertically  or  hori¬ 
zontally.  Adjusting  window  shapes  is 


also  supported.  The  F7  function  key 
lets  you  navigate  from  one  window 
to  another.  The  editor  also  has  search 
and  find/replace  features.  You  can 
search  downward  or  upward  start¬ 
ing  at  the  current  cursor  position. 
When  finding/replacing  text, 
prompts  ask  you  if  this  should  be 
done  in  automatic  or  query  modes. 
Although  the  line  and  column  posi¬ 
tions  of  the  cursor  are  not  displayed 
constantly,  pressing  Alt-F3  reveals 
that  information.  The  Alt-F4  key 
combination  allows  you  to  reposition 
the  cursor  at  the  beginning  of  a  speci¬ 
fied  line. 

You  move  a  block  of  text  by  mark¬ 
ing  the  block,  deleting  it  into  a  buffer, 
and  then  inserting  it  at  the  new  loca¬ 
tion.  For  WordStar  users  this  seems  a 
bit  different  and  somewhat  danger¬ 
ous  because  deleting  more  text  clears 
the  buffers  of  any  previous  contents. 
The  editor  would  be  improved  if 
markers  could  be  used  directly  for 
moving  and  copying  text.  Text  can 
also  be  moved  between  windows. 

I  mentioned  earlier  that  the  MOD 
editor  has  special  macros  for  pro¬ 
gram  constructs.  Pressing  Alt-F2 
causes  a  special  configuration  file  to 
be  read  assigning  macros  to  alternate 
keys.  If  you  use  keyboard  macro  pro¬ 
grams  such  as  SuperKey,  you  should 
clear  the  keyboard  definition  to 
make  way  for  the  MOD  assignments. 
Pressing  Alt-letter  will  result,  in  most 
cases,  in  the  appearance  of  some  con¬ 
struct  related  to  the  letter — for  exam¬ 
ple,  Alt-W  causes  a  while-do  loop  to 
appear  and  the  cursor  is  placed  be¬ 
tween  the  while  and  do  keywords. 
The  beauty  of  MOD  is  that  you  are  still 
free  to  move  around. 

M2SDS 

The  M2SDS  syntax-oriented  editor  is 
among  the  most  flexible  syntax-ori¬ 
ented  editors  I  have  tested.  You  have 
to  develop  a  reflex  to  use  this  type  of 
editor.  It  provides  you  with  syntacti¬ 
cally  arranged  placeholders  that  are 
based  on  Modula-2  syntax.  The  place¬ 
holders  are  filled  by  assigning  decla¬ 
rations  to  them  using  Alt  key  combi¬ 
nations — for  example,  to  declare 
constants  you  press  Alt-C,  to  declare 
variables  you  press  Alt-V,  and  so  on. 
These  declarations  insert  Modula-2 
keywords  and  other  placeholders. 
For  example,  to  create  an  import  list, 
you  type  Alt-I,  and  the  editor  inserts 


Modula-2/86 

M2SDS 

PC  Modula-2 

Modula-2PC 

ASCII  files 

yes 

yes 

yes 

yes 

Binary  files 

yes 

yes 

yes 

yes 

Untyped  files 

no 

no 

no 

no 

Sequential 
Manipulate  file 

yes 

yes 

yes 

yes 

position 

Access  file 

yes 

yes 

yes 

yes 

directory 
Manipulate  file 

yes 

yes 

yes 

yes 

directory 

yes 

yes 

yes 

yes 

Modula-2/86 

M2SDS 

PC  Modula-2 

Modula-2PC 

ststem  Module 

process  type 

yes 

no 

yes 

yes 

NEWPROCESS 

yes 

yes 

yes 

yes 

TRANSFER 

yes 

yes 

yes 

yes 

tOTRANSFER 

yes 

yes 

no 

yes 

Process  Module 

signal  data  type 

yes 

no 

yes 

no 

StartProcess 

yes 

no 

yes 

no 

SEND 

yes 

no 

yes 

no 

WAIT 

yes 

no 

yes 

no 

Awaited 

yes 

no 

yes 

no 

Init 

yes 

no 

yes 

no 

Compiler 

Source 

EXE 

Compile  +  Link 

Run  Time 

(bytes) 

(mm:ss) 

(mm:ss) 

Modula-2/86 

768 

27728 

4  pass  1 :23 
M2C.EXE  0:54 

00:18 

M2SDS 

768 

21370 

0:31 

00:17 

PC  Modula-2 

768 

42064 

0:24 

00:23 

Modula-2PC 

768 

41472 

0:14 

00:35 

Turbo  Pascal 

768 

11495 

0:02 

00:13 

Table  6:  Results  of  the  sieve  benchmark  test 


56 


Dr.  Dobb's  Journal,  October  1986 

697 


MODULA-2 


FROM  <id>  IMPORT  <id-list>.  You 
then  fill  in  the  <id>  and  <id-list> 
placeholders.  The  editor  provides 
placeholders  for  declarations,  proce¬ 
dural  parameters,  data  types,  and 
statements. 

Cursor  movement  is  achieved  by 
using  the  four  arrow  keys,  Home, 
End,  and  PgUp.  The  latter  is  used  to 
move  up  one  program  level.  The  edi¬ 
tor  also  provides  the  ability  to  search 
and  replace  program  text,  scanning 
forward  or  backward.  You  can  scan 
tokens  (that  is,  complete  identifiers), 
strings,  and  declarations.  You  can 
copy  and  move  single  or  multiple 
statements. 

The  editor  has  an  interesting  fea¬ 
ture  that  allows  you  to  transform  a 
construct.  This  is  very  useful  in  cor¬ 
recting  or  editing  a  program — for  ex¬ 
ample,  you  can  transform  a  for  loop 
with  no  step  clause  into  one  that  has 
it.  A  second  example  is  converting  a 
procedure  into  a  function  by  append¬ 


ing  a  returned  value  declaration. 

Language  Features 

All  the  Modula-2  implementations 
support  the  basic  data  types  and  the 
imported  types  WORD  and  ADDRESS, 
defined  by  Wirth  in  the  second  edi¬ 
tion  of  Programming  in  Modula-2 
(Berlin:  Springer-Verlag,  1983).  The 
long  integer  LONGINT,  introduced  in 
Wirth’s  third  edition  of  the  language 
reference  book,  is  supported  by  the 
M2SDS,  PC  Modula-2,  and  Modula-2PC 
compilers.  The  BYTE  type  is  support¬ 
ed  by  Modula-2/86  and  M2SDS.  All 
Modula-2  implementations  except 
Modula-2PC  support  the  8087  chip. 
As  mentioned  earlier,  PColliers  Sys¬ 
tems  intends  to  offer  8087  support  lat¬ 
er  this  year. 

M2SDS  defines  the  type  STRING  in  its 
SYSTEM  module.  Variables  that  are 
defined  as  strings  use  STRlNG[nl, 
where  n  is  the  string  length  varying 
from  1  to  255.  The  string  length  is 
stored  at  index  0.  STfl/JVG-typed  vari¬ 
ables  are  compatible  with  ARRAY  OF 
CHAR  (open  arrays  of  characters)  used 


as  parameters  in  procedures.  All  the 
other  Modula-2  implementations  fol¬ 
low  the  standard  language  and  treat 
strings  as  arrays  of  characters.  All  im¬ 
plementations  support  procedural 
and  functional  types. 

All  the  Modula-2  packages  imple¬ 
ment  the  standard  Modula-2  loops 
and  decision-making  constructs.  Lo¬ 
gitech's  Modula-2/86  follows  Wirth’s 
second  edition  of  the  language  refer¬ 
ence  book. 

User-defined  procedures  and  func¬ 
tions  also  follow  the  standard  lan¬ 
guage  definition.  Modula-2PC  imple¬ 
ments  the  Pascal  FORWARD  statement. 

Libraries 

Modula-2  is  a  small  core  language 
that  relies  heavily  on  library  modules 
for  extensions.  This  includes  modules 
that  export  additional  data  types,  file 
I/O  routines,  screen  handling,  low- 
level  access,  and  so  on. 

All  the  Modula-2  implementations 
export  the  WORD  and  ADDRESS  data 
types  from  the  pseudomodule  SYS¬ 
TEM.  Modula-2/86  and  M2SDS  also  ex¬ 
port  the  BYTE  type  from  SYSTEM.  Mo- 
dula-2/86  supports  18-digit  decimals 
through  the  Decimals  module,  which 
provides  arithmetic  operations, 
string-to-decimal  conversion,  and  er¬ 
ror  checking.  In  addition,  M2SDS  ex¬ 
ports  the  STRING  type  discussed  earli¬ 
er  and  provides  a  String  module  that 
manipulates  strings  and  arrays  of 
characters.  The  other  Modula-2  im¬ 
plementations  offer  string-handling 
modules  that  tackle  arrays  of  charac¬ 
ters.  PC  Modula-2  and  the  extended 
library  of  M2SDS  (that  is,  that  of  SDS-XP) 
provide  a  module  for  LongSets  with 
set  membership  size  exceeding  the 
dismal  standard  of  16  members.  Logi¬ 
tech  is  providing  a  similar  module 
with  its  Translator  that  converts  Tur¬ 
bo  Pascal  programs  to  Modula-2/86 
programs.  All  the  Modula-2  vendors 
include  data-conversion  modules  to 
convert  numeric  data  types  (integers, 
long  integers,  cardinals,  and  reals) 
into  strings  and  vice  versa. 

Modula-2/86  and  M2SDS  include  the 
standard  Wirth  version  of  the  math 
function  library  MathLibO.  PC  Mo¬ 
dula-2  offers  its  MathLibl  library  that 
includes  a  large  set  of  functions,  such 
as  a  complete  set  of  trigonometric 
functions  and  their  inverses,  base-10 
log,  hyperbolic,  power,  and  magni¬ 
tude  functions.  PC  Modula-2  includes 


Compiler 

Source 

EXE 

Compile  +  Link 

Run  Time 

Comments 

(bytes) 

(mm:ss) 

(mm:ss) 

Modula-2/86 

1536 

35696 

4  pass  1 :50 

no  8087 

M2C.EXE  1:21 

00:21 

no  8087 

33040 

4  pass  1 :39 

with  8087 

M2C.EXE  1:13 

00:07 

with  8087 

M2SDS 

1536 

30884 

0:37 

00:22 

no  8087 

30852 

0:39 

error 

with  8087 

PC  Modula-2 

1536 

63424 

0:29 

error 

no  8087 

62896 

0:29 

error 

with  8087 

Modula-2PC 

1536 

39936 

0:15 

00:17 

no  8087 

Turbo  Pascal 

1792 

12245 

0:02.5 

00:15 

no  8087 

11072 

0:02.4 

00:06 

•  with  8087 

Table  7:  Results  of  the  sort  benchmark  test 


Compiler 

Source 

EXE 

Compile  +  Link 

Run  Time 

(bytes) 

(mm:ss) 

(mm:ss) 

Modula-2/86 

2304 

28224 

4  pass  1 :26 
M2C.EXE  1:01 

00:37 

M2SDS 

2304 

21834 

0:33 

00:34 

PC  Modula-2 

2304 

42781 

0:26 

00:40 

Modula-2PC 

2304 

30720 

0:13 

01:24 

Turbo  Pascal 

2045 

11886 

0:02.4 

00:25 

Table  8:  Results  of  the  matrix-inversion,  floating-point  test 
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Compiler 

Source 

EXE 

Compile + Link 

Run  Time 

Comments 

(bytes) 

(mm:ss) 

(mm:ss) 

Modula-2/86 

2432 

36448 

4  pass  1 :54 

no  8087 

M2C.EXE  1:29 

00:54 

SQRT( ) 

02:11 

LN( ) 

01:55 

EXP() 

02:10 

ARCTAN( ) 

01:25 

SIN( ) 

2432 

32240 

4  pass  1:48 

with  8087 

M2C.EXE  1:24 

00:08 

SQRT( ) 

00:09 

LN( ) 

00:28 

EXP() 

00:11 

ARCTAN( ) 

00:12 

SINK) 

M2SDS 

2432 

36870 

0:39 

no  8087 

03:28 

SQRT( ) 

05:36 

LN() 

05:25 

EXP() 

05:44 

ARCTAN( ) 

05:13 

SIN() 

2432 

24952 

0:35 

with  8087 

error 

SQRT( ) 

error 

LN( ) 

error 

EXP() 

error 

ARCTAN( ) 

error 

SIN() 

PC  Modula-2 

2432 

72864 

0:32 

no  8087 

01:52 

SQRT( ) 

01:51 

LN( ) 

02:03 

EXP() 

01:56 

ARCTAN( ) 

01:47 

SIN() 

2432 

61520 

0:31 

with  8087 

00:12 

SQRT( ) 

00:15 

LN() 

error 

EXP() 

00:11 

ARCTAN( ) 

00:12 

SIN( ) 

Modula-2PC 

2432 

39424 

0:15 

no  8087 

36:46 

SQRT( ) 

27:43 

LN() 

08:01 

EXP() 

28:39 

ARCTAN( ) 

06:49 

SIN() 

Turbo  Pascal 

1947 

12607 

0:02.6 

no  8087 

01:41 

SQRT( ) 

02:39 

LN() 

02:17 

EXP() 

02:23 

ARCTAN( ) 

01:56 

SIN() 

11482 

0:02.6 

with  8087 

00:08 

SQRT( ) 

00:09 

LN() 

00:12 

EXPO 

00:10 

ARCTAN( ) 

00:11 

SIN() 

Table  9:  Results  of  mathematical-functions  benchmark  test 
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a  second  module  to  provide  mathe¬ 
matical  constants  and  the  range  of 
reals.  Modula-2PC  includes  similar 
extensions. 

Console  I/O  is  generally  supported 
by  the  InOut  and  ReallnOut  modules 
in  standard  Modula-2.  Each  imple¬ 
mentation  offers  a  superset  of  this 
standard — Modula-2/86,  PC  Modula- 
2,  and  Modula-2PC  include  WORD  I/O 
routines;  M2SDS  adds  STRING  and  Re¬ 
cord  I/O  procedures.  PC  Modula-2  of¬ 
fers  routines  for  formatted  output  of 
REAL  numbers  and  for  displaying 
them  as  octal  numbers. 

M2SDS  and  Modula-2PC  provide 
screen/cursor-control  modules. 
M2SDS  and  PC  Modula-2  supply  high- 
resolution  color-graphics  modules. 
PC  Modula-2  includes  support  for  us¬ 
ing  a  mouse  in  graphics  mode.  Mo¬ 
dula-2/86  has  no  modules  for  any  of 
these  operations. 

Each  Modula-2  package  provides  a 
collection  of  routines  for  file  I/O.  The 
Modula-2  vendors  have  used  the  stan¬ 
dard  Wirth  modules  as  a  starting 
point  and  added  more  procedures 
and  new  modules  to  tap  into  the  rou¬ 
tines  of  PC-DOS/MS-DOS  that  perform 
file,  directory,  and  drive  manipula¬ 
tion.  Modula-2/86,  M2SDS,  and  PC  Mo¬ 
dula-2  provide  many  additional  and 
practical  I/O  routines,  including  file¬ 
name  query,  path  manipulation,  and 
byte-block  I/O. 

Accessing  PC-DOS/MS-DOS  routines 
and  the  8088  CPU  registers  opens  the 
door  for  you  to  use  more  hardware 
and  operating-system  capabilities. 
The  four  Modula-2  packages  permit 
such  access.  With  the  exception  of  PC 
Modula-2,  the  Modula-2  implementa¬ 
tions  allow  in-line  code  to  be  inserted 
in  the  source  program. 

All  the  implementations  support 
concurrency.  Only  Modula-2/86  and 
PC  Modula-2,  however,  provide  the 
Process  module,  which  is  used  in 
concurrent-process  synchronization . 
M2SDS  implements  concurrent  pro¬ 
cesses  slightly  differently  from  stan¬ 
dard  Modula-2. 

Benchmarks 

I  ran  the  following  benchmarks  using 
an  IBM  PC/XT  with  512K  RAM,  an  8087 
chip,  20-megabyte  hard  disk,  and  PC- 
DOS/MS-DOS  (3.1).  The  benchmark  pro- 
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grams  were  taken  from  popular  tests  I 
or  common  operations,  such  as  sort-  I 
ing  and  matrix  inversion.  I  used  two 
types  of  timing  schemes,  depending 
on  the  test  program.  In  the  first  meth¬ 
od,  a  timer  was  turned  on  after  the 
program  name  was  typed  at  the  DOS 
level  and  turned  off  once  the  program 
ended  and  the  DOS  prompt  reap¬ 
peared.  The  second  method  used  in¬ 
ternal  prompts  to  start  and  stop  tim- 
j  ing.  The  tests  I  used  were: 

•  Sieve  test — the  popular  sieve  of  Era¬ 
tosthenes,  which  finds  prime  num¬ 
bers.  The  upper  limit  of  the  prime 

|  numbers  is  7,000. 

j  •  Integer  sort  test — measures  the  | 
\  speed  of  manipulating  integer  arrays. 
A  1,000-member  array  is  created  in  or-  j 
der  and  reverse-sorted  ten  times  using 
the  Shell-Metzner  sort  method. 

•  Matrix-inversion  test — measures 
the  speed  of  basic  floating-point  oper¬ 
ations.  A  square  matrix  with  20  rows  ; 
and  columns  is  created  by  assigning  | 
Is  to  all  nondiagonal  elements  and  2s  ( 
to  all  the  diagonal  elements.  The  test 

j  was  carried  out  once  without  8087 
[  support  and  once  with  it. 

•  Mathematical-functions  test — mea- 
|  sures  the  speed  of  the  square  root,  nat- 
I  ural  logarithm,  exponential,  arctan¬ 
gent,  and  sine  functions.  The 
arguments  of  each  function  are  var¬ 
ied.  The  tests  were  carried  out  once 
without  8087  support  and  once  with 
8087  support. 

•  Disk-write  test — measures  the  speed 
of  writing  512  blocks  of  128  charac¬ 
ters  to  a  text  file  stored  on  a  floppy 
disk.  Initially,  the  disk  is  empty. 

•  Disk-read  test — measures  the  speed 
of  reading  512  blocks  of  128  charac¬ 
ters  from  a  text  file  stored  on  a  floppy 
disk.  The  disk  contains  no  other  files. 

•  Recursive  quicksort  test — measures 
the  speed  of  recursion.  A  1,000-inte¬ 
ger  array  is  created  in  order  and  re-  ! 
verse-sorted  using  a  recursive  quick¬ 
sort.  The  above  process  is  repeated 

]  ten  times. 

•  Dynamic-allocation  and  pointer 
test — measures  the  speed  of  dynami¬ 
cally  allocating  a  binary  tree  and  the 
speed  of  accessing  the  tree  elements 
using  pointers.  The  test  program  cre¬ 
ates  an  array  of  1,000  integers  using 
truncated  sine-function  values. 

All  the  Modula-2  compilers  were 
made  to  produce  stand-alone  .EXE 


Compiler 

Source 

(bytes) 

EXE 

Compile  +  Link 

(mm:ss) 

Run  Time 

(mm:ss) 

Comments 

Modula-2/86 

768 

27568 

4  pass  1:31 
M2C.EXE  1:06 

01:25 

M2SDS 

768 

21258 

0:31 

09:01 

PC  Modula-2 

768 

41888 

0:25 

01:49 

Modula-2PC 

768 

27648 

0:13 

06:28 

Turbo  Pascal 

512 

11478 

0:02 

00:57 

Buffered  Pascal 
output 

Table  lO:  Results  for  disk-write  benchmark  test 


files,  as  opposed  to  intermediate  com¬ 
piled  programs  that  run  within  Mo- 
dula  shells. 

The  Modula-2PC  index  and  pointer¬ 
checking  directives  were  turned  on 
during  program  compilation  because 
all  the  other  compilers  that  were  test¬ 
ed  had  their  checking  switches  on  by 
default.  Batch  files  were  used  in  com¬ 
piling  and  linking  the  test  programs 
that  I  have  listed  above. 

Bugs 

I  encountered  several  bugs  while  car¬ 
rying  out  the  benchmark  testing. 
They  were: 

•  The  Modula-2PC  compiler  did  not 
accept  array  indices  that  were  INTE¬ 
GERS.  The  loop  control  variables 
were  changed  into  CARDINALS  for  the 
sieve  and  matrix-inversion  tests. 

•  The  matrix-inversion  test  program 
compiled  by  PC  Modula-2  exhibited  a 
run-time  error  with  and  without  the 
8087  support.  In  the  first  case,  a  "CAR¬ 
DINAL  OVERFLOW”  error  message  ap¬ 
peared;  in  the  second,  a  "REAL  OVER¬ 
FLOW”  error  message  was  displayed.  I 
informed  Modula  Corp.  about  this 
bug. 

•The  8087  support  of  M2SDS  did  not 
function  properly.  I  experienced  run¬ 
time  errors  with  all  the  benchmark 
programs  compiled  with  the  8087 
support  turned  on.  I  wrote  additional 
programs  to  further  test  and  inspect 
the  proper  function  of  the  basic  four 
floating-point  operations  and  the 
math  functions  used  in  the  bench¬ 
marks.  The  results  showed  a  severe 
malfunction  of  the  8087  support.  I  in¬ 
formed  ITC  of  this  malfunction. 

•  PC  Modula-2  had  a  bug  with  the  ex¬ 
ponential  function  when  used  with 
8087  support.  All  valid  arguments 


supplied  to  this  function  returned  an 
overflow  message. 

•The  disk-write  program  compiled 
by  Modula-2PC  hung  the  system.  I 
contacted  PColliers  Systems  and  was 
asked  to  remove  the  Resetf )  state-  ' 
|  ment  in  the  program.  The  recom¬ 
mendation  worked,  and  I  was  able  to 
run  the  benchmark, 
j  •  The  square  root  function  of  Modula- 
2PC  hung  the  system  when  given  the 
argument  zero  (0.0).  I  had  to  modify 
the  benchmark  so  that  the  square 
root  argument  varied  from  1  to  1,001. 

I  contacted  PColliers  Systems  and  re¬ 
ported  the  bug  and  was  later  in¬ 
formed  that  it  was  fixed. 

•  Running  the  dynamic-allocation  and 
pointer  test  with  M2SDS,  I  noticed  that 
the  pointer-access  test  was  unusually 
fast.  Inserting  some  WriteStringf ') 
statements,  I  was  able  to  detect  some 
shortcircuiting  in  the  program  flow. 

Test  Results 

The  results  of  the  benchmark  tests  are 
shown  in  Tables  6 — 13,  pages  56 — 62. 1 
have  included  results  from  running 
Turbo  Pascal  with  Pascal  versions  of 
the  benchmarks.  The  main  purpose  is 
to  compare  run-time  speed  and  not 
compilation  speed  or  code  size.  Notice 
that  the  Turbo  Pascal  programs  run 
faster  than  any  compiled  Modula-2 
program  except  for  the  mathematical 
functions  when  no  8087  support  is 
used.  This  should  answer  a  lot  of  ques- 
;  tions  about  comparing  the  speed  of 
Turbo  Pascal  programs  with  those  I 
produced  by  various  Modula-2  i 
compilers. 

M2SDS  produces  the  smallest  files, 
closely  followed  by  Modula-2/86,  ! 
then  Modula-2PC  and  PC  Modula-2. 
Looking  at  the  data  for  the  speed  of 
producing  .EXE  files,  you  can  see  that 
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|  Modula-2PC  is  the  clear  winner.  It  is 
followed  by  PC  Modula-2.  M2SDS  is 
J  the  third  in  rank,  and  Modula-2/86 
lags  on  the  average  by  1  minute  and 
10  seconds  behind  Modula-2PC. 
Looking  at  run-time  speed  data, 


]  you  can  see  that  different  implemen¬ 
tations  may  shine  when  running  dif¬ 
ferent  tests.  M2SDS  comes  first  in  the 
sieve  and  integer-sort  tests.  Modula- 
2PC  does  well  with  the  matrix-inver¬ 
sion  test.  Logitech's  Modula-2/86  is 


the  only  one  that  runs  the  same  test 
with  8087  support. 

Looking  at  the  math-functions  test 
with  no  8087  support,  you  can  see 
that  Modula-2/86  and  PC  Modula-2 
compete  for  first  place,  M2SDS  comes 
third,  and  Modula-2PC  a  distant 
fourth.  The  data  for  the  same  test 
running  with  8087  support  shows  a 
close  timing  between  Modula-2/86 
and  Modula-2PC. 

The  disk-write  and  -read  tests  re¬ 
flect  the  use  of  faster  buffered  I/O  by 
Modula-2/86  and  PC  Modula-2.  In 
writing  to  the  disk,  Modula-2PC  came 
third  and  M2SDS  fourth.  The  last  two 
compilers  reverse  their  ranks  in  the 
disk-read  test. 

The  recursive  quicksort  test  places 
M2SDS  in  the  lead,  followed  by  Mo- 
dula-2/86  and  with  PC  Modula-2  a 
close  third.  Modula-2PC  took  twice  as 
long  to  finish  the  test  as  did  M2SDS. 

In  the  dynamic-allocation  test,  Mo-  J 
dula-2/86  performed  very  well  and  [ 
was  followed  by  PC  Modula-2  and  Mo- 
dula-2PC.  M2SDS  took  the  longest  time. 

To  give  you  a  general  idea  of  overall 
run-time  speed,  I  present  some  basic 
statistics  in  Table  14,  page  62.  The  cal¬ 
culations  are  based  on  the  following 
conditions: 

1.  For  each  test,  divide  the  run-time 
values  by  the  least  observed  value.  | 
This  gives  a  relative  run-time  speed 
index. 

2.  The  use  of  8087  support  is  regarded 
as  a  different  set. 

3.  Run-time  errors  creating  missing 
data  are  ignored. 

4.  For  each  compiler,  I  calculated  the 
average  and  standard  deviations  of 
the  relative  run-time  speed  values. 

Table  14  shows  that  Modula-2/86 
benchmark  programs  have  the  fast¬ 
est  run  times  overall,  followed  close¬ 
ly  by  PC  Modula-2.  The  standard  de¬ 
viation  gives  you  an  idea  of  the 
spread  in  speed.  Notice  that  Modula- 
2PC  has  a  standard  deviation  greater 
than  its  average  value,  indicating  that 
it  did  very  well  on  some  tests  and 
lagged  behind  on  others. 

DDJ 


Compiler 

Source 

(bytes; 

EXE 

Compile  +  Link 

(mm:ss) 

Run  Time 

(mm:ss) 

Comments 

Modula-2/86 

693 

27552 

4  pass  1 :31 
M2C.EXE  1:06 

00:57 

M2SDS 

768 

21242 

0:32 

07:36 

PC  Modula-2 

693 

41840 

0:24 

01:22 

Modula-2PC 

768 

27648 

0:13 

04:54 

Turbo  Pascal 

384 

11355 

0:02 

00:30 

Buffered  Pascal 
input 

Table  11:  Results  for  disk-read  benchmark  test 

Compiler 

Source 

(bytes; 

EXE 

Compile  +  Link 

(mm:ss) 

Run  Time 

(mnrss) 

Modula-2/86 

1920 

28080 

4  pass  1 :29 
M2C.EXE  1:04 

00:11 

M2SDS 

1920 

21690 

0:27 

00:09 

PC  Modula-2 

1920 

42672 

0:26 

00:12 

Modula-2PC 

1920 

30720 

0:14 

00:19 

Turbo  Pascal 

1685 

11822 

0:03 

00:07 

Table  12:  Results  for  recursion  benchmark  test 

Compiler 

Source 

(bytes; 

EXE 

Compile  +  Link 

(mm:ss) 

Run  Time 

(mnrss) 

Comments 

Modula-2/86 

2816 

34720 

4  pass  1 :46 
M2C.EXE  1:24 

00:24 

00:08 

allocate 

search 

M2SDS 

2816 

36086 

0:39 

01:55 

00:05(err) 

allocate 

search 

PC  Modula-2 

2816 

71984 

0:32 

01:05 

00:20 

allocate 

search 

Modula-2PC 

2816 

43520 

0:15 

01:29 

00:19 

allocate 

search 

Turbo  Pascal 

2521 

12216 

0:03 

00:22 

00:06 

allocate 

search 

Table  13:  Results  for  dynamic-allocation  and  pointer  test 


Compiler 

Average 

Index 

Standard 

Deviation 

Sample 

Size 

Modula-2/86 

1.047 

0.082 

19 

M2SDS 

3.317 

2.225 

12 

PC  Modula-2 

1.462 

0.531 

16 

Modula-2PC 

7.930 

10.872 

13 

Table  14:  Statistics  for  relative  run-time  speed  indices 
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Listing  One  (Text  begins  on  page  23.) 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 


Listing  1  —  more.c 


•include  <stdio.h> 

•include  <ctype.h> 

•include  <fcntl.h> 

•include  <process.h> 

/*  MORE.C  Page  input  to  stdout. 

*  (C)  1986,  Allen  I.  Holub.  All  rights  reserved. 

* 

*  Usage:  more  [-<offset>]  file... 

* 

*  Exit  status:  0  always 

*/ 

/* - */ 


extern 

int 

b_getc  () ; 

/*  Direct  console  input  function 
/*  source  in  /src/tools/b  getc.c 

*/ 

*/ 

extern 

int 

look  () ; 

/*  Char,  lookahead  function. 

/*  source  in  /src/tools/look.asm 

*/ 

*/ 

extern 

long 

ftell 

(  FILE  *);  /*  Standard  library  functions: 

*/ 

extern 

long 

atol 

(  char*  ) ; 

extern 

FILE 

*fopen 

(  char*,  char*  ); 

extern 

int 

fclose 

(  FILE*  ) ; 

extern 

int 

spawnl 

(  int,  char*,  char*,  ); 

extern 

char 

*getenv 

{  char*  ) ; 

extern 

char 

*fgets 

(  char*,  int,  FILE*  ); 

extern 

long 

filelength 

(  int  ); 

/* - */ 


•define 

CAN  0x18 

/*  AX  */ 

•define 

ESC  Oxlb 

/*  A[  */ 

•define 

max(a,b)  ((a) 

>  (b)  ?  (a)  : 

(b)) 

•define 

min(a,b)  ((a) 

<  (b)  ?  (a)  : 

(b)) 

•define 

BSIZE  256 

/*  Maximum  length  of  a  line  in 

the  file  */ 

•define 

PAGESIZE  23 

/*  •  of  lines  to  output  before 

stopping  */ 

•define 

E(x) 

fprintf (stderr, "%s\n",  x) 

•define 

HAS_D0T  (p) 

strchr (p, ' . ' 

) 

FILE 

*Ifile 

-  stdin; 

/* 

Current  input 

file 

*/ 

char 

*Ifile  name 

-  “/dev/con" 

;  /* 

Name  of  file  associated  w/  Ifile 

*/ 

int 

Repeat  count 

-  1; 

/* 

Repeat  count 

for  most  recent  cmd 

*/ 

long 

Line 

-  0; 

/* 

•  of  output  Lines  printed  so  far 

*/ 

long 

Flen 

-  0; 

/* 

Length  of  input  file  in  chars 

*/ 

long 

Start_here 

-  0; 

/* 

Seek  to  here 

when  prog  starts 

*/ 

*  Stack  used  to  keep  track  of  start  of  lines.  Maximum  number 

*  of  lines  is  determined  by  STACKSIZE. 

*/ 


typedef  long  STACKTYPE; 

•define  STACKSIZE  (1024*6)  /*  Must  be  divisible  by  2  */ 


STACKTYPE  Stack [  STACKSIZE  ); 

STACKTYPE  *Sp  -  Stack  +  STACKSIZE; 


•define  STACKFULL 
•define  STACKEMPTY 
•define  CLEAR_STACK() 
•define  TOS 
•define  BACK  SCRN 


(Sp  <-  Stack) 

(Sp  >-  Stack  +  STACKSIZE  ) 

Sp  -  Stack  +  STACKSIZE  ; 

(STACKEMPTY  ?  0  :  *Sp) 

*(  min (  Sp+  (PAGESIZE-1) ,  Stack+ (STACKSIZE-1) )  ) 


•define  erase_line()  line(  1  0  )  /*  Draw  a  line  of  spaces  */ 


/*■ 


•*/ 


help() 

{ 

register  int  i; 

/*  Print  a  help  message  with  a  box  around  it,  special  IBM  graphics 
*  characters  are  used  for  the  box 
V 


putc(  0xd6,  stderr  ); 


for(  i  -  56  ;  — i  >«  0;  putc(  0xc4,  stderr)  ) 

E  ("\267") ; 

E("\272  b . go  (B)ack  a  page  \272") ; 

E  ("\272  e . go  to  end  of  file  \272")  ; 

E  ("\272  n . go  to  (N)ext  file  \272“); 

E  ("\272  o . print  (O) ffset  from  start  of  file  \272") ; 

E  ("\272  q .  (Q)uit  (return  to  DOS)  \272")  ; 

E("\272  s  .  (S)kip  one  line  (w/o  printing)  \272") ; 

E("\272  r  .  (R)ewind  file  (go  back  to  beginning)  \272"); 

E("\272  l  .  execute  a  program  (type  blank  line  \272") ; 

E(M\272  at  prompt  to  execute  last)  \272") ; 

E(M\272  /  .  search  for  regular  expression  \272") ; 

E(M\272  (type  blank  line  at  prompt  for  last)  \272") ; 

E("\272  ESC . Scroll  until  any  key  is  hit  \272") ; 

E(M\272  CR . next  line  \272“) ; 

E("\272  SP  .  next  screen  \272") ; 

E ("\272  anything  else  ...  print  this  list  \272") ; 

E (“\272  \272-); 


E(''\272  All  commands  may  be  preceeded  by  a  count.  \272")  ; 

putc(  0xd3,  stderr  ); 
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Listing  One  (Listing  continued,  text  begins  on  page  22.) 


for(  i  -  56  ;  — i  >-  0;  putc(  0xc4  , stderr)  ) 


E("more:  Copyright  (C)  1986,  Allen  I.  Holub.  All  rights  reserved.**); 
E (“NnUseage:  more  [+<num>]  [file...]  \n**); 

E ("Print  all  files  in  list  on  the  screen,  pausing  every  23  lines"); 
E("If  +  is  specified,  more  will  start  printing  at  character  <num>“); 
E(**One  of  the  following  commands  is  executed  after  each  page:'*); 

help() ; 
exit  (1); 


push(  file  posn  ) 
i  long  file_posn; 


if (  STACKFULL  ) 

comp_stk  () ; 

M  — Sp  )  “  file_posn; 


/*  Push  file_posn  onto  the  stack  V 
/*  If  the  stack  is  full,  compress  it  */ 


Pop  one  entry  off  the  stack  and  return  the  file 
position. 


return  STACKEMPTY  ?  0  :  *Sp++ 


comp_stk  () 

{ 


Conpress  the  stack  by  removing  every  other  entry. 
This  routine  is  called  when  the  stack  is  full  (we've 
read  more  lines  than  the  stack  can  hold) . 


register  STACKTYPE  *dest,  *src; 

fprintf (stderr, "\007Stack  Full:  CompressingNn") ; 

src  -  dest  -  Stack  +  STACKSIZE; 

while (  (src  —  2)  >-  Stack  ) 

* — dest  “  *src; 


Get  one  character  from  the  console  using  a  direct 
bios  call.  Map  \r  into  \n  if  one  is  encountered. 


register  int  c; 

c  -  b_getc()  &  0x7f; 
put  char  (c) ; 


return  (  c  —  *\r'  )  ?  '\n* 


/*  Get  a  character  from  console  */ 
/*  Echo  character  */ 


/*  Clears  the  entire  I/O  queue,  both  at  the  bios  and  the 

*  bdos  level . 


while  (  look()  ) 

b_getc()  ; 

#ifdef  NEVER 

while  (  kbhit  ()  ) 

get  char  () ; 

fendif 


if(  look()  ) 

{ 


/*  Return  true  if  a  key  has  been  hit  on  */ 
/*  the  physical  keyboard  (as  compared  */ 
/*  with  a  character  available  on  stdin)  */ 
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Listing  One 


(Listing  continued,  text  begins  on  page  22.) 


206  clear_io  () ; 

207  return  1; 

208  } 

209  return  0; 

210  } 

211 

212  /* - */ 

213 

214  char  *getbuf (  p  ) 


215  register  char  *p; 

216  { 

217 

218 

219 

220 
221 
222 

223 

224 

225 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 

239 

240 

241 

242 

243 

244 

245 

246 

247 

248 

249 

250 

251 

252 

253 

254  } 

255 


256  /* - */ 

257 

258  percent (s) 

259  char  *s; 

260  { 

261  /*  Print  the  percentage  of  the  file  that  we've  seen  so  far  */ 

262 

263  printf (M%4.1f%%%sM,  ((double)TOS  /  (double) Flen)  *  100.00,  s  ); 

264  } 

265 

266  /* - V 

267 

268  int  get  and  () 

269  { 

270  /*  Get  a  canmand  from  the  keyboard,  using  direct 

271  *  bios  I/O.  Commands  take  the  form  [nunjco.  Returns 

272  •  the  conmand.  Repeat_count  is  initialized  to  hold  (numj 

273  *  or  1  if  no  num  is  entered. 

274  */ 


Get  a  line  of  input  using  direct  console  I/O  and  put  it 
into  buf.  Return  a  pointer  to  the  first  whitespace  on  the 
line  or  to  end  of  line  if  none.  This  routine  is  for 
getting  commands  from  the  user,  not  for  getting  normal 
input.  *H  is  supported  as  a  destructive  backspace  but  no 
other  editing  is  available. 


register  int 

int 

char 

char 


c; 

gottail  -  0; 
•start  -  p; 
•tail 


clear_io  () ; 

while (  (c-getcon())  !-  '\n'  ) 
( 

if (  c  —  ' \b'  ) 

{ 


) 

else 

{ 


if  (  p  o  start  ) 

fputs (  "  \007",  stderr  ); 

else 

{ 

— p; 

fputs (  "  \b",  stderr  ); 


if(  isspace(c)  &&  !gottail  ) 

gottail  -  (int) (  tail  -  p  ); 
*p++  -  c; 


•p  -  ' \0 ' ; 

return (  p  <-  start  ?  NULL  :  tail  ) ; 


275 

276  int  c; 

277 

278  clear_io  () ; 

279  percent (HM); 

280  printf (",  line  %ld  (?  for  commands):  ",  Line  ); 

281 

282  Repea t_count  -  0; 

283  while (  'O'  <-  (c  -  getconO)  (i  c  <-  '9'  ) 

284  Repeat  count  -  (Repeat  count  *  10)  +  (c  -  '0'); 

285  “  “ 

286  if (  Repeat_count  --  0  ) 

287  Repeat  count  -  1; 

288  “ 

289  erase_line()  ; 

290 

291  if(  c  —  0x03  )  /*  *C  —  abort  */ 

292  exit (  1  ) ; 

293 

294  return (  c  ); 

295  } 

296 

297  /* - */ 

298 

299  char  *inputline(  suppress  ) 

300  { 

301  /•  Get  a  line  from  the  file  being  processed  and  put  it  into 

302  •  buf.  Push  the  start  of  line  character  onto  the  stack. 

303  •  return  0  on  end  of  file,  a  pointer  to  the  line  (ie.  to  buf) 

304  *  otherwise. 

305  */ 

306 

307  register  int  rval; 

308  register  long  start  of  line  ; 

309  static  char  buf(BSIZE); 
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310 

311  start_of_line  -  ftell  (  Ifile  ); 

312 

313  if(  rval  -  (int)  fgets (buf #  BSIZE,  Ifile)  ) 

314  { 

315  Line++; 

316  push(  start_of_line  ); 

317  if(  ! suppress  ) 

318  fputs (  buf,  stdout  ) ; 

319  ) 

320 

321  return  rval  ?  buf  :  NULL  ; 

322  } 

323 

324  /* - */ 

325 


326  printpage{) 

/*  Print  an  entire  page  fran  the  input  file  V 

register  int  i; 

for(  i  -  PAGESIZE-1;  — i  >-  0  &&  inputline (0) ;  ) 

(continued  on  nepct  page) 


327  { 

328 

329 

330 

331 

332 

333 

334  ) 

335 


C  CHEST 

Listing  One 

(Listing  continued,  text  begins  on  page  22.) 

336  /* 

- */ 

337 

338  search  () 

339  { 

340 

/*  Prompt  for  a  pattern  and  then  search  for  it  in  the 

341 

*  file.  Stop  searching  if  the  pattern  is  found  or  if 

342 

*  any  key  is  hit.  The  previous  pattern  is  remembered 

343 

*  in  a  local  array  so,  if  CR  is  entered  instead  of  a 

344 

*  pattern,  the  previous  pattern  is  used. 

345 

V 

346 

347 

static  char  pat (128),  opat(128)  ; 

348 

char  * iline; 

349 

extern  int  "make pat  () ; 

350 

int  ‘template; 

351 

352 

printf (U/H) ; 

353 

354 

if(  !getbuf(  pat  )  ) 

355 

strcpy(  pat,  opat  ); 

356 

357 

if (  ! (template  -  makepat (  pat,  0  ))  ) 

358 

printf ("Illegal  regular  expression:  %s\n",  pat  ); 

359 

else 

360 

i 

361 

erase  line(); 

362 

printf (M/%s\nM,  pat  ); 

363 

364 

while  (  (iline  -  inputline  (1) )  &&  !khit()  ) 

365 

{ 

366 

percent  ("\r") ; 

367 

if (  matchs  (  iline,  template,  0)  ) 

368 

break; 

369 

) 

370 

371 

unmakepat (  template  ) ; 

372 

fseek  (  Ifile,  pop(),  0  );  /*  back  up  one  line  */ 

373 

— Line; 

374 

line  (  Oxcd,  1); 

375 

printpage  () ; 

376 

) 

377 

378 

strcpy(  opat,  pat  ); 
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Spawn  off  a  child  process.  When  the  process  terminates 
print  a  message  and  redraw  the  current  page.  Note  that 
spawn{)  is  used  (rather  than  systemO)  so  you  can't 
execute  a  batch  file  or  a  built-in  contnand.  This 
subroutine  will  set  the  CMDLINE  environment  variable 
to  a  null  string  for  the  sake  of  those  routines  that 
are  executing  under  the  shell  which  will  use  it. 


static 

char 


static  char  obuf(128),  -otail  -obuf; 


register  char 
register  int 
int 

printf  ("!"); 

if  (  !  (tail 

{ 


} 

else 

{ 


379  } 

380 

381  /* - 

382 

383  execute ( 

384  { 

385 

386 

387 

388 

389 

390 

391 

392 

393 

394 

395 

396 

397 

398 

399 

400 

401 

402 

403 

404 

405 

406 

407 

408 

409 

410 

411 

412 

413 

414 

415 

416 

417 

418 

419 

420 

421 

422 

423 

424 

425 

426 

427 

428 

429 

430 

431 

432 

433 

434 

435 

436 

437 

438 

439 

440 

441 

442 

443 

444  ) 

445 

446  /* - 

447 

448  line(  c  ,  newline  ) 

449  { 

450 

451 

452 

453 

454 

455 

456 

457 

458 


char  buf  [128] ; 

-tail  -  " 


*p; 

c; 

got_tail 


getbuf (buf) )  ) 


tail  -  otail; 
memcpy(  buf,  obuf,  128  ); 
printf {  "\n!%s  %s\n",  buf,  tail  ); 


if  (  -tail  ) 

*tail++  -  *\0'; 


/*  If  no  ccrrmand  entered,  */ 
/-  use  the  same  one  we  -/ 
/-  used  last  time  */ 


if  (  HAS_DOT  (buf)  ) 

{ 

/ 


} 

else 

( 


) 


Spawnlp  will  actually  try  to  execute  any  file  that  you 

-  give  it.  If  you  say  to  execute  an  ASCII  file,  it  will 
*  load  that  file  into  memory,  try  to  execute  it,  and  die 

-  a  horrible  death.  We  attempt  to  avoid  this  by  checking 

-  for  a  dot  in  the  file  name.  You  may  want  to  put  a 

-  more  rigorous  test  here. 

V 

fprintf (stderr,  "\007<%s>  is  not  a  command\n",  buf); 


putenv  ("CMDLINE-") ; 

if (  spawnlp (P  WAIT,  buf,  buf,  tail,  NULL)  - 1) 

fprintfTstderr, "Can't  execute  <%s  %s>\n",  buf,  tail  ); 


printf ("Hit  any  key  to  continue 
get  con  () ; 
erase_line  ()  ; 
putchar(*\n') ; 

otail  -  tail; 

memcpy(  obuf,  buf,  128  ); 


Print  a  line  of  characters  to  mark  top  of  page.  Oxcd 
is  the  IBM  graphics  character  for  a  horizontal  double 
line.  The  cursor  is  put  at  the  beginning  of  next  line 
if  "newline"  is  true,  else  it's  put  at  beginning  of 
current  line. 


register  int 


459  put char ('\r') ; 

460 

461  for(  i  -  79;  — i  >-  0  ;  putchar(  c  )  ) 

462 

463 

464  putchar(  newline  ?  *\n'  :  '\r‘  ); 

465 

466  ) 

467 

468  /* - -/ 

469 

470  backapage (  count  ) 

471  ( 

472  /-  Go  back  count  pages  and  print  the  resulting  page. 

473  -/ 

474 

475  register  int  i; 

476 

477  i  -  ( (count+1)  *  PAGESIZE)  -1; 

478 

479  while  (  — i  >-  0  ) 

480  ( 

481  Line--; 

482  pop(); 

483  ) 

484 

485  line  (  Oxcd,  1) ; 

486  fseek(  Ifile,  pop(),  0  ); 

487  Line  -  max  (  Line  -  1,  0  ) ; 

488  printpage{); 
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Listing  Ofl©  (Listing  continued,  text  begins  on  page  22.) 

489  } 

490 

491  /* - 

- V 

4  92 

493  docmd(  and,  ateof  ) 

494  { 

495  /* 

Do  a  single  canmand,  return  1  if  next  file  is  requested. 

496  * 

Actually  call  exit  on  a  "quit"  comnand  or  AC. 

497  */ 

498 

499  register  int  rval  -  0; 

500  register  int  i; 

501  long 

posn; 

502 

503  do  ( 

504 

switch  (  and  ) 

505 

{ 

506 

case  CAN:  break;  /*  NOP  V 

507 

case  'q':  exit  (0) ;  /*  abort  */ 

508 

509 

case  ' \n' :  /*  FORWARD  MOTION  */ 

510 

if (  ateof  )  /*  one  line  */ 

511 

rval  -  1; 

512 

else 

513 

input  line  (0) ; 

514 

break; 

515 

516 

case  1  ' :  /*  one  page  V 

517 

if (  ateof  ) 

518 

rval  -  1; 

519 

520 

printpageO ; 

521 

break; 

522 

523 

case  'e':  /*  To  end  of  file  V 

524 

erase  line(); 

525 

while!  inputline  (1)  ss  IkhitO  ) 

526 

percent ("\r") ? 

527 

break; 

528 

529 

case  's':  /*  one  line  w/o  printing  */ 

530 

if (  ateof  ) 

531 

rval  -  1; 

532 

else 

533 

{ 

534 

erase  line  () ; 

535 

inputTine(l) ; 

536 

percent ("\r") ; 

537 

} 

538 

break; 

539 

540 

case  ESC:  /*  scroll  till  key  is  hit  */ 

541 

if(  ateof  ) 

542 

rval  -  1; 

543 

else 

544 

while  (  inputline  (0)  &&  !khit()  ) 

545 

clear  io  () ; 

546 

547 

clear  io  () ; 

548 

Repeat  count  -  0;  /*  Ignore  repeat  count  */ 

549 

break;  /*  if  it's  set  */ 

550 
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551 

case  'n':  /*  to  next  file 

V 

552 

rval  -  1; 

553 

break; 

554 

555 

case  /*  search  for  pattern 

*/ 

556 

search  {) ; 

557 

break; 

558 

559 

case  *r':  /*  to  start  of  file 

*/ 

560 

line{  Oxcd,  1  ); 

561 

CLEAR  STACK (); 

562 

Line  -  0; 

563 

f seek (  Ifile,  0L,  0  ); 

564 

printpage() ; 

565 

break; 

566 

567 

case  'b':  /*  to  previous  page 

*/ 

568 

back a page (  Repeat  count  ) ; 

569 

Repeat  count  -  0; 

570 

break; 

571 

572 

case  'o';  /*  print  file  position 

V 

573 

574 

print f( “Top  line  -  %ld,  ",  BACK  SCRN  ); 

575 

print f ("Bottom  line  -  %ld\n“,  TOS  ); 

576 

break; 

577 

578 

case  ' ! ' : 

579 

/*  Close  the  file  and  spawn  another  shell. 

580 

*  when  we  come  back,  reopen  the  file 

581 

*  and  position  to  the  same  place  we 

582 

*  were  before.  This  is  necessary  because  of 

583 

*  a  bug  in  Microsoft  C  ver.  3.0's  spawn  functions 

584 

*  (they  trash  the  IOB) .  It  will  cause  problems 

585 

*  if  standard  input  is  used  as  the  input  source 

586 

*  (as  in  a  pipe)  because  we  won't  be  able  to 

587 

*  successfully  reopen  stdin. 

588 

V 

589 

590 

Repeat  count  -  0;  /*  Ignore  repeat  count 

V 

591 

fcloseT  Ifile  ) ; 

592 

execute  () ; 

593 

posn  -  pop() ; 

594 

595 

if  (  Ifile  -  fopen(Ifile  name,  "r")  ) 

596 

i 

597 

fseek  (  Ifile,  posn,  0  ); 

598 

backapage(  0  ); 

599 

1 

600 

else 

601 

i 

602 

fprintf (stderr, “more:  can't  open  %s\n". 

603 

Ifile  name); 

604 

rval  -  1; 

605 

} 

606 

break; 

607 

608 

default  :  /*  Print  the  help  msg. 

V 

609 

help  () ; 

610 

and  -  getcmdO;  /*  get  a  new  command 

V 

611 

Repeat  count ++; 

612 

brea)^; 

613 

) 

614 

615 

)  while (  — Repeat  count  >  0  ); 

616 

617 

return (  rval  ) ; 

618  } 

619 

621 

622  dofile ( 

fname  ) 

623  char 

*  fname; 

624  { 

625 

/*  Process  lines  from  an  input  file  having  the  indicated 

626 

*  name. 

627 

V 

628 

629 

if (  (Ifile  name  -  fname)  &&  !  (Ifile  -  fopen  (fname,  “r"))  ) 

630 

fprintf  (stderr,  “more:  can't  open  %s\n",  fname  ); 

631 

else 

632 

{ 

633 

Flen  -  filelength(  fileno (Ifile)  ); 

634 

fseek  (  Ifile,  Start  here,  0  ); 

635 

636 

CLEAR  STACK (); 

637 

doand('  ',  0  );  /*  dump  the  first  page 

V 

638 

639 

for(;;> 

640 

I 

641 

for(;;) 

642 

{ 

643 

if(  docmd(  getcmdO,  0)  ) 

644 

return; 

645 

646 

if  (  feof  (Ifile)  ) 

647 

break; 

648 

} 

649 

650 

E  ("\n\020\020\020  LAST  LINE  IN  FILE  \021\021\021") ; 

651 

if  (  docmd  (  getcmdO,  1)  ) 

652 

break; 

653 

) 

654 

655 

f close (  Ifile  ); 

656 

) 

657  } 

658 

660 
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C  CHEST 


Listing  Two  (Text  begins  on  page  22.) 

Listing  2  —  b_getc.c 


1  # include  <stdio.h> 

2  iinclude  <dos.h> 

3 

4  /*  B_GETC.C  Get  a  character  with  a  direct  video  bios  call. 

5  *  this  routine  can  be  used  to  complement  stderr  as 

6  *  it  can  be  used  to  get  characters  from  the  keyboard,  even  when  input 

7  *  redirected.  The  typed  character  is  returned  in  the  low  byte  of  the 

8  *  returned  integer,  the  high  byte  holds  the  auxiliary  byte  used  to 

9  *  mark  ALT  keys  and  such.  See  the  Technical  Ref  for  more  info. 

10  * 

11  *  Copyright  (C)  1985  Allen  I.  Holub.  All  rights  reserved. 

12  * 

13  * - 

14  */ 

15 

16  extern  int  int86(int,  union  REGS  *,  union  REGS  *) ; 

17 


18  /* - */ 

19 

20  f define  KB_INT  0x16  /*  Keyboard  BIOS  interrupt  */ 

21  Idefine  GETC  0x00  /*  Getc  is  service  0  V 


22 

23 

24  int  b  getc() 

25  { 

26  union  REGS  Regs; 

27 

28  Regs. h. ah  -  GETC  ; 

29  int86 (  KB  INT,  &Regs,  &Regs  ); 

30  return (  (Int) Regs. x. ax  ); 

31  ) 

End  Listing  Two 

Listing  Three 

Listing  3  —  look. asm 


1  ; 

2  ; 

3 

4 

5  _TEXT 

6  _TEXT 

7  CONST 

8  CONST 

9  _BSS 

10  _BSS 

11  _DATA 

12  DATA 

13  ; 

14  DGROUP 

15 

16  ? 

17  DATA 

18  EXTRN 

19  _DATA 

20  ? 

21  TEXT 

22  7 

23  ;  int 

24  ; 

25  ; 

26  ; 

27  ; 

28  ; 

29  ; 

30 

31  _look 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42  exit; 

43 

44 

45 

46  look 

47 

48  TEXT 

49  End 


End  Listings 


Static  Name  Aliases 
TITLE  foo 

SEGMENT  BYTE  PUBLIC  'CODE' 

ENDS 

SEGMENT  WORD  PUBLIC  'CONST* 

ENDS 

SEGMENT  WORD  PUBLIC  *BSS' 

ENDS 

SEGMENT  WORD  PUBLIC  'DATA' 

ENDS 

GROUP  CONST,  _BSS,  _DATA 

ASSUME  CS:  _TEXT,  DS:  DGROUP,  SS;  DGROUP,  ES:  DGROUP 

SEGMENT 

_ C hk fit k: NEAR 

ENDS 

SEGMENT 

look(); 

Tests  the  bios  to  see  if  a  key  has  been  hit.  If  no  key  has  been 
hit  then  0  is  returned,  else  an  int  is  returned  in  which  the 
high  byte  is  the  scan  code  and  the  low  byte  is  the  character 
code,  if  the  low  byte  is  0  then  a  non-ascii  key  has  been  hit 


PUBLIC  _look 
PROC  NEAR 


push 

bp 

mov 

bp,  sp 

mov 

ax,  2 

call 

_ chkstk 

mov 

ah,  1 

;  service  1,  Report  on  charact 

int 

01 6H 

?  BIOS  keyboard  interrupt. 

jnz 

exit 

;  jump  if  a  key  is  available 
;  (return  the  character) 

mov 

ax,  0 

;  else  (return  0) ; 

mov 

sp,bp 

pop 

ret 

ENDP 

ENDS 

bp 
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TNZ 


These  Softstrips  by  Cauzin  Systems 
contain  the  listing  for  Richard  A. 
Campbell's  TNZ  program.  To  read 
them  into  a  computer  through  a  Cau¬ 
zin  Sofistrip  System  Reader,  start  on 
this  page  with  strips  1  —  6.  Then  turn 
page  84  upside  down  and  read  in 
strips  7— 12. 


I 


A 
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_ 16  BIT 

Listing  One  (Text  begins  on  page  96.) 


Boyer-Moore  text  matching  algorithm 

described  in  Scientific  American  Sept.  1984,  pp.  67-68. 
Implemented  for  8086  by  Ray  Duncan,  June  1986. 


Call  with:  DS:SI  =  pattern  address 

AX  =  pattern  length 
ES:DI  =  address  of  string  to  be  searched 
DX  =  length  of  string  to  be  searched 
assumes  "CTAB"  in  same  segment  as  pattern  string 


;  Returns: 

CY 

=  True  if  no  match 

or 

CY 

=  False  if  match,  and 

ES:DI 

=  pointer  to  matched  string 

boyer  proc 

near 

mov 

bp,  si 

;  save  pattern  offset 

push 

di 

;  save  searched  string 

offset 

push 

es 

;  save  searched  string 

segment 

push 

dx 

;  save  searched  string 

length 

push 

ds 

pop 

es 

;  point  to  table  with 

ES 

mov  cx,256  ;  initialize  all  of  table 

mov  di, offset  ctab  ;  to  length  of  pattern 

cld 

rep  stosb 


dec  ax 

xor  cx,  cx 

xor  bh,  bh 


;  AX  =  pattern  length  -  1 
;  init  pattern  char,  counter 
;  BX  will  be  used  to  index, 

;  with  char  in  the  lower  half 


bl: 

mov  bl, [si] 


;  build  table  of  increments 
;  for  each  possible  char,  value 
;  get  character 


FTL  Modula-ll 

$49.95! 


Your  next  computer  language.  The  successor  to  Pascal, 
Modula  is  powerful.  Why?  Once  a  routine  is  written,  it  need 
never  be  recompiled.  Programs  work  everywhere  from  Z80 
through  VAX. 

FTL  Modula-ll  is  a  full  Z80  CP/M  compiler  (MSDOS  version 
soon)!  It’s  fast  —  18K  source  compiles  in  7  seconds!  The 
built-in  split  screen  editor  is  worth  $60  alone.  Some  stan¬ 
dard  features:  full  recursion,  15  digit  reals,  CP/M  calls, 
coprocesses,  assembler  and  linker.  The  one-pass  compiler 
makes  true  Z80.COM,  ROMable  code,  too.  Get  the  language 
you’ve  waited  for  now.  Only  $49.95! 


FTL  Editor  Toolkit 

Full  source  to  our  split-screen  programming  editor.  Curious? 
Want  to  customize  to  your  tastes?  Want  sample  Modula-ll 
code?  This  is  perfect  for  you.  Comes  with  all  you  need  for 
your  personal  editor  or  terminal  installer.  Just  $39.95! 

WORKMAN  &  ASSOCIATES 
1925  East  Mountain  St. 

Pasadena,  CA  91 104 
(818)  791-7979 

We  have  over  200  formats  in  stock!  Please  specify  your  for¬ 
mat  when  ordering.  Add  $2.50  per  order  for  shipping.  We 
welcome  COD  orders! 


MacTutor 

The  Macintosh  Programming  Journal 


Simply  the  finest  monthly  technical  Journal 
available  for  the  Macintosh.  Contains  no 
fluff,  only  programs  in  C,  Asm,  Pascal, 
Basic  &  Forth.  US  3rd  class:  $30;  US  1st 
class,  or  Canada:  $45.  All  Overseas:  $60. 


(714)  630-3730. 

MacTutor 

P.O.  Box  400 

Placentia,  CA.  92670 

Circle  no.  187  on  reader  service  card. 
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16  BIT 


Listing  One  (Listing  continued,  text  begins  on  page  96.) 


mov 

dx,  ax 

;  calc  distance  from  end 

sub 

dx,  cx 

;  of  pattern 

mov 

[bx+ctab] ,  dl 

;  put  into  table 

inc 

si 

;  advance  through  pattern 

inc 

cx 

cmp 

cx,  ax 

;  done  with  pattern? 

jne 

bl 

;  no,  loop 

pop 

dx 

;  restore  searched  string  length 

pop 

es 

;  restore  searched  string  segment 

pop 

di 

;  restore  searched  string  offset 

std 

;  strings  will  be  compared 

;  from  their  ends  backwards 

b2: 

mov 

si,  bp 

;  get  pattern  addr 

add 

di,ax 

;  point  to  ends  of  strings 

add 

si,  ax 

mov 

cx,  ax 

;  get  length  to  compare 

inc 

cx 

repz  cmpsb 

;  now  compare  strings 

jz 

b3 

;  jump  if  whole  string  matched 

inc 

di 

;  point  to  mismatched  char 

mov 

bl,es: [di] 

;  and  fetch  it,  then 

mov 

bl,  [bx+ctab] 

;  get  displacement  amount 

sub 

di,  cx 

;  restore  searched  string  address 

add 

di,bx 

;  update  searched  string  pointer 

sub 

dx,bx 

;  update  remaining  length 

cmp 

dx,  ax 

;  enough  left  to  compare  again? 

ja 

b2 

;  jump  if  searched  string  not  exhausted 

stc 

;  no  match,  return  CY=True 

jmp 

b4 

b3: 

inc 

di 

;  match  found,  return  CY=False 

clc 

;  and  ES:DI  =  pointer  to  matched  string 

b4: 

cld 

;  return  to  caller  with  direction 

ret 

;  flag  cleared 

boyer 

endp 

;  Table  of  possible  byte  values:  if  the  value  exists  in  the  pattern 
;  string,  its  byte  contains  its  offset  from  the  end  of  the  pattern. 

;  If  the  value  does  not  occur  in  the  pattern,  its  byte  contains  the 
;  length  of  the  pattern. 


ctab  db  256  dup  (?) 

Listing  Two 


End  Listing  One 


General  string  matching  routine  for  8086 
(brute  force  version  using  8086  string  primitives) 
by  Ray  Duncan,  June  1986 

Call  with:  DS:SI  =  pattern  address 

AX  =  pattern  length 

ES:DI  =  address  of  string  to  be  searched 

DX  =  length  of  string  to  be  searched 


Returns:  CY  =  True  if  no  match 

or 

CY  =  False  if  match,  and 
ES:DI  =  pointer  to  matched  string 


smatch 


si: 


s2: 


proc 

near 

mov 

bp,  si 

;  save  pattern  offset 

mov 

bx,  ax 

;  BX  :=  pattern  length 

dec 

cld 

bx 

;  decrement  it  by  one 

mov 

lodsb 

si,  bp 

;  AL  :=  first  char  of  pattern 

mov 

cx,  dx 

;  remaining  searched  string  length 

repnz 

scasb 

;  look  for  match  on  first  char. 

jnz 

s3 

;  searched  string  exhausted,  exit 

mov 

dx,  cx 

;  save  new  string  length 

mov 

cx,bx 

;  get  pattern  length  -  1 

repz 

cmpsb 

;  compare  remainder  of  strings 

jz 

s2 

;  everything  matched 

add 

di,  cx 

;  no  match,  restore  string  addr 

sub 

di,bx 

;  advanced  by  one  char. 

cmp 

dx,bx 

;  searched  string  exhausted? 

ja 

si 

;  some  string  left,  try  again 

jmp 

s3 

;  no  match,  jump  to  return 

sub 

di,bx 

;  match  was  found. 

dec 

di 

;  let  ES:DI  =  addr  of  matched  string 
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16  BIT 


Listing  Two  (Listing  continued,  text  begins  on  page  96.) 


smatch  endp 


Listing  Three 

C .  > 

C  C2I  > 

C  Convert  .COM  file  to  Inline  Code  > 

C  by  George  F.  Smith,  1986  > 

C  > 

{  Sample  usage:  > 

C  A>C2I  File.Com  >File.inl  > 
C .  > 

C$P1024,D-> 


and  return  CY=False 


no  match, 

return  CY=True 


Reset (Com); 

write( ' InLine  ( 
ctr  :=  10; 


i  initialize  counter  > 


While  not  eof(Com)  do 
begin 

read( Com, bits);  C  Get  com 

WriteC/S',  C  .  .  .  pu 

hex  [  bits  shr  4  and  $0F  ]  , 
hex  [  bits  and  $0F  ]  , 

ctr  :=  ctr  +  5; 
if  ctr  =  LineSize  then 
begin 


C  Get  com  data  .  .  .  > 

{  .  .  .  put  it  inline  > 


ctr  :=  0; 
write In; 
end; 
end; 

WriteC  );'); 
Wri te(AZ); 
Close(Com); 

END.  C  C2I  > 


C  Reset  counter  and  > 
{  start  a  new  line  > 


t  Finish  inline  statement  > 


ctr, 

bits  :  byte; 

Com  :  file  of  byte; 


i  LineSize  counter  > 
{  com  file  byte  > 
i  com  f i le  handle  > 


const 

LineSize  =  70; 

hex  :  array [0.. 15]  of  char  =  '0123456789ABCDEF ' 


Assign(Com,ParamStr(1 ));  t  com  file  name  from  command  line  ) 


End  Listings 


90 


Dr.  Dobb's  Journal,  October  1986 

715 


STRUCTURED  PROGRAMMING 


Listing  One  (text  begins  on  page  104.) 

Listing  1:  Calculating  and  printing  percentage 


:  OCTAVE  (  creates  a  note  of  double  the  frequency  ) 
2*  CREATE  , 

DOES>  (  <adr>  —  freq  )  @  ; 


0  CONSTANT  US>D  (  convert  unsigned  single  to  double  ) 

%  (  nl  n2  -  )  (  calculates  and  prints  percentage  to  tenths  ) 
35  10  GOTOXY  (  position  cursor  ) 

10000  SWAP  */  5  +  10  /  (  figure  percentage  and  round  ) 

US>D  <#  #  ASCII  .  HOLD  #S  #>  (  format  number  as  string  ) 

TYPE  ASCII  %  EMIT  ;  (  type  it  with  %  ) 

(  Note:  Cursor-positioning  is  vendor  dependent.  ) 

(  ASCII  is  inmediate.  It  puts  on  the  stack  the  ) 

(  ASCII  value  of  the  character  that  follows  it.  ) 


A  OCTAVE  A' 


(  defines  the  frequency  of  the  octave  ) 


Listing  Two 


Listing  2:  A  more  general  approach 

:  .0%  (  nl  n2  -  n3  )  (  n3  -  %age  nl  is  of  n2,  rounded  to  tenths  ) 
10000  SWAP  */  5  +  10  /  ; 

:  TENTHS  (  n  -  a dr  cnt  )  US>D  <#  »  ASCII  .  HOLD  #S  #>  ; 

:  %.  (  nl  n2  -  )  ?DUP  (  check  for  0  divisor  ) 

IF  .0%  TENTHS  TYPE  ASCII  %  EMIT 
ELSE  DROP  ."  n/a"  THEN  ; 

:  %.R  (  #  nl  n2  -  )  (  #  is  width  of  field;  display  flush  right  ) 
?DUP  {  check  for  0  divisor  ) 

IF  .0%  TENTHS  ROT  OVER  -  SPACES  TYPE  ASCII  %  EMIT 
ELSE  DROP  3  -  SPACES  . "  n/a"  THEN  ; 


Listing  Three 


Listing  3:  Using  CONSTANT  in  a  defining  word 

440  CONSTANT  A  (  note  defined  by  its  frequency  ) 


:  OCTAVE  2*  CONSTANT  ;  (  alternate  definition  ) 


End  Listing  Three 


Listing  Four 


End  Listing  One 


Listing  4:  Execution  array,  first  definition 

CREATE  OPTIONS  ]  >PRINTER  >DISK  >SCREEN  >DOS  [ 

;  DO-OPTION  (  n  -  )  2*  OPTIONS  +  @  EXECUTE  ; 

0  DO-OPTION  (  to  printer  ) 

1  DO-OPTION  (  to  disk  ) 

3  DO-OPTION  (  to  DOS  ) 

4  DO-OPTION  (  unpredictable  results  ) 


End  Listing  Four 


Listing  Five 


End  Listing  Two 


Listing  5:  A  defining  word  for  execution  vectors 

0  CONSTANT  F  -1  CONSTANT  T 

:  VECTOR:  :  {  compile  operators  ) 

DOES>  SWAP  2*  +  @  EXECUTE  ; 

VECTOR:  OPTION  >PRINTER  >DISK  >SCREEN  >DOS  ; 


0  OPTION  (  to  printer  ) 
2  OPTION  (  to  screen  ) 


End  Listing  Five 


Listing  Six 

Listing  6:  Bit  twiddlers 

CREATE  BITS  1C,  2  C,  4  C,  8  C,  16  C,  32  C,  64  C,  128  C, 

:  S>B  (  ?  -  f  )  0<>  ;  (  forces  to  a  boolean:  -1  or  0  ) 

:  MASK  (  bit#  -  mask  )  BITS  +  C@  ; 

:  AIM  (  #  a  -  bit#  a  )  SWAP  8  /MOD  ROT  +  ; 

:  +BIT  (  bit#  a  -  )  AIM  SWAP  MASK  OVER  C@  OR  SWAP  C!  ; 

:  -BIT  (  bit#  a  -  )  AIM  SWAP  MASK  NOT  OVER  C@  AND  SWAP  C!  ; 

:  0BIT  (  bit#  a  -  f  )  AIM  C@  SWAP  MASK  AND  S>B  ; 

:  -BIT  (  bit#  a  -  )  AIM  2DUP  @BIT  IF  -BIT  ELSE  +BIT  THEN  ; 


Listing  Seven 


End  Listing  Six 


Listing  7:  Bits  for  valid  file  name  characters 

CREATE  TEST  16  ALLOT 
:  SET flags  TEST  16  ERASE 
ASCII  !  TEST  +BIT 

ASCII  &  1+  ASCII  #  DO  I  TEST  +BIT  LOOP 

ASCII  (  TEST  +BIT  ASCII  )  TEST  +BIT  ASCII  '  TEST  +BIT 

ASCII  '  TEST  +BIT  ASCII  _  TEST  +BIT  ASCII  -  TEST  +BIT 

ASCII  {  TEST  +BIT  ASCII  }  TEST  +BIT 

ASCII  Z  1+  ASCII  @  DO  I  TEST  +BIT  LOOP 

ASCII  9  1+  ASCII  0  DO  I  TEST  +BIT  LOOP  ; 

:  READOUT  128  0  DO  I  TEST  @BIT  IF  I  EMIT  THEN  LOOP  SPACE  ; 

:  READ  16  0  DO  TEST  I+@.2  +LOOP  ; 

SETflags  ok 

READOUT  ! #$%& '  () -01234 5678 90ABCDEFGHIJKIMNOPQRSTUVWXYZ  '{)  ok 


READ  0  0  9210  1023  -1  -30721  1  10240  ok 


Listing  Eight 

Listing  8:  Checking  characters 


End  Listing  Seven 


CREATE  LEGAL  0 


9210  ,  1023  ,  -1  ,  -30721  ,  1  ,  10240 


(  Bit  set  in  LEGAL  only  if  character  is  legal  in  filename  ) 

(  Map  is  by  ASCII  value  of  the  character.  ) 

:  OK-CHAR?  (  ASCII-char  —  f  ;  T  -  valid  character  for  filename  ) 
LEGAL  @BIT  ; 


End  Listings 
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String  Compares 

he  article  "Data  Structures  and 
Algorithms”  written  by  Niklaus 
Wirth  (who  else?)  in  the  special  soft¬ 
ware  issue  of  Scientific  American 
(September  1984)  included  mention 
of  an  intriguing  text-searching  algo¬ 
rithm  attributed  to  Robert  Boyer  and 
J.  Strother  Moore.  The  description  of 
the  algorithm  itself  is  informal,  but 
an  example  diagram  and  enough  in¬ 
formation  were  provided  so  that  I 
could  implement  it  in  8086  assembly 
language  (Listing  One,  page  86). 

The  algorithm  uses  a  clever  trick  to 
reduce  the  number  of  comparisons 
of  the  pattern  against  the  text  string 
being  searched.  At  the  initial  entry  to 
the  searching  procedure,  a  table  is 
built  for  the  pattern  string  in  which 
each  entry  corresponds  to  a  possible 
value  of  a  member  of  the  pattern, 
and  the  entry  contains  the  distance 
from  the  end  of  the  pattern  of  the  last 
occurrence  of  that  member  in  the 
pattern.  If  a  given  value  does  not  oc¬ 
cur  in  the  pattern  at  all,  its  slot  in  the 
lookup  table  contains  the  length  of 
the  pattern  itself.  The  overhead  of 
constructing  this  table  turns  out  to  be 
insignificant  when  the  string  being 
searched  is  long. 

In  the  main  loop  of  the  searching 
procedure,  the  comparison  of  the 
pattern  with  a  segment  of  text  pro¬ 
ceeds  backward  from  the  end  of  the 
pattern.  When  a  mismatch  is  found, 
the  value  in  the  table  for  the  charac¬ 
ter  failing  the  match  is  looked  up;  this 
value  specifies  the  number  of  posi¬ 
tions  to  shift  the  pattern  forward 
along  the  text  string.  Thus,  the  mis- 
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matched  character  is  used  as  a  pivot 
point,  and  the  pattern  leapfrogs  its 
way  through  the  text  string  until  a 
complete  match  is  found  or  the  text 
string  being  searched  is  exhausted. 
Note  that  this  routine  could  be  gener¬ 
alized  to  patterns  and  searched 
strings  with  16-bit  elements,  al¬ 


though  of  course  the  lookup  table 
would  be  quite  large  (128K). 

Wirth  seems  to  admire  this  algo¬ 
rithm  but  resorts  to  a  little  bit  of  hand- 
waving  when  explaining  why  it 
works.  He  says  (page  68),  "The  Boyer- 
Moore  algorithm  may  be  faster,  but 
can  one  have  confidence  in  its  cor¬ 
rectness?  In  particular,  how  can  one 
be  certain  in  shifting  the  word  [pat¬ 
tern]  several  places  to  the  right  with¬ 
out  making  any  comparisons  that  no 
matching  alignments  were  passed 
over?  An  informal  argument  is  that  a 
match  requires  identity  of  all  the  let¬ 
ter  pairs,  and  the  alignments  passed 
over  necessarily  differ  in  at  least  one 
position,  namely  the  pivot  position.” 

Frankly,  even  with  both  working 
code  and  Wirth's  explanation  in 
hand,  I  am  still  a  little  perplexed  with 
this  routine.  Although  I  had  no  trou¬ 
ble  writing  the  code  from  Wirth’s 
brief  blueprint — all  the  pieces  make 
sense  to  me,  and  I  can  trace  the  code 
and  watch  its  operation — it  still 
seems  a  little  magical.  A  deep  under¬ 
standing  of  why  it  works  continues 
to  escape  me. 

One  thing  that  seems  evident, 
though,  is  that  the  Boyer-Moore  algo¬ 
rithm  is  designed  for  processors  with¬ 
out  special  string  instructions.  As  an 
experiment,  I  coded  a  string  search 
routine  (Listing  Two,  page  89)  that  em¬ 
ploys  a  sort  of  brute-force  approach 
with  the  8086 's  SC  AS  (scan  string)  and 
CMPS  (compare  string)  instructions.  It 
does  a  fast  scan  for  a  match  on  the  first 
character,  then  performs  a  full  string 
compare.  In  a  simple  test  (searching 
the  ROM  space  of  a  Compaq  Portable 
for  the  string  " COMPAQ >”),  the  pro¬ 
gram  in  Listing  Two  proved  to  be 
about  30  percent  faster  than  the  pro¬ 


gram  in  Listing  One. 

I  suspect  that  a  hybrid  approach  of 
the  Boyer-Moore  algorithm  with  the 
fast  forward  scan  might  give  excel¬ 
lent  results,  though  I  will  defer  this 
exercise  to  a  later  column.  By  the 
way,  the  routines  in  Listings  One  and 
Two  have  purposely  been  made 
completely  symmetrical  in  their  call¬ 
ing  conventions.  If  you  embed  these 
routines  in  other  programs,  you  can 
make  some  further  optimizations  to 
the  front  end  of  either  routine  be¬ 
cause  symmetry  will  be  of  no  con¬ 
cern  to  you  at  that  point. 

Resources  for  MS-DOS 
Programmers 

Readers  responded  to  my  recent  cap¬ 
sule  reviews  of  MS-DOS  programming 
books  by  suggesting  the  following  ad¬ 
ditional  references  and  resources: 

Rollins,  Dan.  IBM-PC  8088  MACRO  As¬ 
sembler  Programming.  New  York: 
Macmillan,  1985.  $16.95. 

Jourdain,  Robert.  Programmer's 
Problem  Solver  for  the  IBM  PC,  XT,  and 
AT.  New  York:  Brady  Publishing  (Si¬ 
mon  and  Schuster),  1986.  $22.95 
Generic  PC-DOS  newsletter  about  PC- 
DOS  on  non-IBM  systems,  published 
by  Fred  Greeb,  8403  W.  Illiff  Lane, 
Lakewood,  CO  80227. 

Assembly  Language  Supplement 
Newsletter,  published  by  William  J. 
Claff,  7  Roberts  Road,  Wellesley,  MA 
02181. 

I  will  include  more  detailed  descrip¬ 
tions  of  these  books  and  newsletters 
in  future  columns,  after  I  have  seen 
them  myself. 

In-Line  Assembly  for 
Turbo  Pascal 

George  F.  Smith  of  Lilburn,  Georgia, 
writes:  "Some  of  your  readers  may 
be  writing  assembler  routines  for 
Turbo  Pascal,  as  I  have  done  in  my 
user-supported  package  Boosters. 
Routines  written  in  assembler  for 
Turbo  Pascal  may  run  as  external 
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.COM  files  or  in-line  code.  Once  a  rou¬ 
tine  is  running  properly,  I  like  to  use 
it  as  in-line  code  because  it  compiles 
at  maximum  velocity  and  doesn't 
bother  the  disk  drives. 

"I’m  enclosing  a  utility  program, 
C2I  [Listing  Three,  page  90],  that 
makes  it  easy  to  get  from  .COM  to  in¬ 
line  code.  The  program  reads  a  char¬ 
acter  from  a  file,  converts  each  nib¬ 
ble  to  hex/ASClI,  then  applies 
formatting  for  syntax  requirements 
and  token  readability.  It  writes  the 
result  to  standard  output  and  repeats 
this  process  until  it  reaches  an  end  of 
file. 

"To  run  C2I,  convert  it  to  a  .COM  file 
first,  then  from  DOS  type: 

A>C2I  filename.COM  >filename.INL 

Filename.COM,  of  course,  must  be  a 
machine-code  file  that  works  as  a 
Turbo  Pascal  function  or  procedure 
and  that  you  understand  how  to  use. 
When  C21  finishes,  filename.INL  will 
contain  the  in-line  code. 

"To  merge  the  generated  in-line 
code  file  into  your  Pascal  program, 
read  filename.INL  into  the  Turbo  edi¬ 
tor  using  Ctrl-K-R,  then  add  header 
and  trailer  information  (here  assum¬ 
ing  a  procedure): 

Procedure  Some  (  parameters  .  .  .  ); 
begin 

InLine  ( 

$1E  .  . . 

/$1F  ); 

end; 

"A  little  doctoring  is  usually  neces¬ 
sary  before  the  in-line  routine  will 
work  properly.  The  .COM  files  Turbo 
Pascal  uses  as  externals  usually  begin 
with  the  sequence: 


Push 

BP 

;  /$55 

Mov 

BP,SP 

;  /$8B  /$EC 

and  end  with 

Mov 

SP,BP 

;  /$8B  /$E5 

Pop 

BP 

;  /$5D 

Ret 

;  /$C2  /$00  /$00 

The  corresponding  object  code  as  it 
appears  in  the  in-line  file  is  shown 
above  on  the  right.  Turbo  Pascal  pro¬ 
vides  this  code  for  you  when  it  com¬ 
piles  the  routine's  header  and  termi- 
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nating  END  statement.  If  you  edit  out 
these  bytes  from  the  in-line  code,  it 
should  behave  as  well  as  the  external 
COM  file.” 

WINDOW. ASM  Revisited 

Chris  Dunford,  one  of  the  sysops  of 
the  IBM  PC  SIG  on  CompuServe,  has 
some  useful  comments  and  sugges¬ 
tions  regarding  John  Seal’s 
WINDOW. ASM  program  that  was  pub¬ 
lished  in  the  May  1986  16-Bit  Toolbox 
column. 

"First,  the  EGA  adds  BIOS  video  ser¬ 
vices  lOh,  llh,  and  IZh,  so  the  pro¬ 
gram  won't  run  on  an  EGA-equipped 
PC.  Better  stated,  it  would  probably 
run,  but  my  guess  is  that  it  would  fail 
the  'already  installed'  test  and  refuse 
to  install  itself.  If  it  did  install,  then 
those  EGA  functions  wouldn’t  be 
available  to  other  programs.  I  realize 
that  WINDOW.ASM  was  probably  writ¬ 
ten  before  the  EGA  was  available. 

"Second,  statements  such  as  ‘All  reg¬ 
isters  preserved  except  ay '(in  the  pro¬ 
logue  to  the  set— window  routine)  may 
be  misleading.  WINDOW.ASM  uses 
some  standard  BIOS  video  services, 
which  do  not  guarantee  to  preserve 
si,  di,  and  bp.  Those  registers  are  usu¬ 
ally  returned  unchanged  on  a  stan¬ 
dard  PC  (but  not  always — check  bp  af¬ 
ter  a  BIOS  scroll);  however,  some 
compatibles  do  use  them  more  exten¬ 
sively.  I  know  of  one  programmer 
who  came  to  grief  by  actually  testing 
to  see  whether  si  was  affected  by  a 
particular  operation  on  his  PC.  It 
wasn't,  so  he  saved  himself  the  2  bytes 
of  a  push/pop  and  everything  ran 
fine — until  the  program  was  execut¬ 
ed  on  one  particular  compatible.  Si 
was  altered,  the  program  failed,  and  it 
took  him  forever  to  figure  out  why. 

“Finally,  in  checking  for  com¬ 
mand-line  parameters,  WINDOW.ASM 
scans  the  full  127-byte  unformatted 
parameter  area  beginning  at 
PSP:0081h  looking  for  a  (.  This  is  not 
safe  because  there  is  no  guarantee 
that  the  area  following  the  actual  pa¬ 
rameters  has  been  zeroed  by  the  MS- 
DOS  loader:  It  could  easily  contain 
junk  left  behind  after  the  execution 
of  some  other  program.  The  length  of 
the  actual  command  tail  passed  to  the 
program  is  available  at  PSP:0080h  and 
should  be  used  when  scanning  for  ar- 
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guments  passed  to  a  program.” 

Modifying  the  Master 
Environment  Block 

Whenever  MS-DOS  programmers  get 
together  to  talk  about  the  subjects  that 
really  aggravate  them,  the  machina¬ 
tions  that  are  necessary  to  modify  the 
system’s  master  environment  block 
are  always  high  on  the  list  of  topics. 

The  environment  block  is  a  para¬ 
graph-aligned  data  block  that  con¬ 
tains  a  series  of  ASCIIZ  (null-terminat¬ 
ed)  strings,  the  whole  set  of  strings 
being  terminated  by  an  additional 
null  byte.  Each  string  is  in  the  form: 

variable= parameter 

Under  DOS  Versions  2  and  3,  three 
particular  variables — COMSPEC= 
parameter,  PATH = parameter,  and 
PROM PT= parameter — are  always 
found  in  the  environment  block. 
These  are  initialized  during  the  sys¬ 
tem  boot  process  and  tell  COMMAND 
.COM  where  to  find  the  transient  por¬ 
tion  of  itself  for  reloading,  the  subdir¬ 
ectories  to  search  for  executable  files, 
and  the  format  of  the  user  prompt, 
respectively.  These  three  environ¬ 
mental  variables  may  be  modified, 
and  new  variables  may  be  added,  by 
SET  commands  entered  at  the  DOS 
command  level. 

The  environment  block  can  be  as 
large  as  32K  and  can  be  a  very  effec¬ 
tive  means  of  passing  "global”  config¬ 
uration  information  to  executing 
programs.  The  Microsoft  C  compiler 
and  Microsoft  linker,  for  instance, 
use  environmental  variables  to  find 
include  and  object  library  files.  You 
would  also  think  that,  because  the 
environment  block  can  be  so  large,  it 
would  also  be  a  very  nice  way  to  pass 
data  between  sequentially  executing 
programs — a  sort  of  built-in  system 
“COMMON.”  Although  simple  in  con¬ 
cept,  this  kind  of  use  of  the  environ¬ 
ment  block  turns  out  to  be  very  diffi¬ 
cult  in  practice. 

A  pointer  to  the  environment  block 
for  a  given  process  is  found  at  offset 
002ch  in  that  process's  program  seg¬ 
ment  prefix  under  current  versions  of 
DOS.  This  is  not  a  pointer  to  one,  cen¬ 
tralized  environment  block  for  the 
system,  however,  but  is  a  pointer  to  a 
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static  copy  of  the  environment  block 
of  the  parent  program  that  caused  the 
current  process  to  be  executed.  The 
parent  program  may  be  the  system’s 
command  processor  (usually  COM- 
MAND.COM),  but  it  may  also  be  any 
other  process  that  can  perform  an 
EXEC  call  ( inf  21h,  function  4bh). 
Changes  made  by  a  program  to  its 
own  environment  block  are  visible 
only  to  other  programs  that  it  spawns 


explicitly  and  have  no  effect  on  its 
own  parents  or  on  programs  that  exe¬ 
cute  after  it  terminates. 

The  environment  block  for  a  given 
process  sits  inside  a  memory  block 
(memory  arena)  that  has  been  allocat¬ 
ed  by  the  system  loader  via  the  MS- 
DOS  allocate  memory  block  function 
(int  Zlh,  function  48h),  and  the  pro¬ 
gram  code  and  data  for  a  process  sit 
inside  another  such  block.  Each  allo¬ 
cated  memory  arena  is  controlled  by 
a  16-byte  memory  control  block 
(called  an  arena  header),  which  sits 


immediately  below  it.  The  control 
blocks  contain  three  items  of  useful 
information:  a  byte  designating 
whether  the  control  block  is  a  mem¬ 
ber  or  the  last  in  the  chain  of  all  con¬ 
trol  blocks,  the  segment  of  the  PSP  of 
the  program  "owning”  the  allocated 
memory  block  (this  slot  is  zero  if  the 
block  is  free),  and  the  length  of  the 
allocated  block  in  paragraphs.  Thus, 
the  control  blocks  are  chained  im¬ 
plicitly  because  you  can  jump  from 
one  control  block  to  the  next  toward 
high  memory  with  the  length  infor¬ 
mation  that  each  contains. 

Because  the  chain  of  memory  con¬ 
trol  blocks  can  be  followed  in  only 
one  direction,  and  your  program  is 
usually  sitting  at  or  near  the  end  of 
the  chain,  there  is  no  well-behaved 
(for  that  word  read  documented )  way 
to  trace  back  through  the  allocated 
memory  blocks  toward  low  memory 
and  find  the  master  environment 
block  owned  by  COMMAND.COM  or 
another  shell.  At  first  glance  then,  it 
seems  impossible  for  your  program 
to  affect  the  master  environment  in  a 
way  that  will  pass  information  to  all 
other  programs  that  are  executed. 
Hackers  will  be  hackers,  though,  and 
there  are  at  least  three  ways  to  ac¬ 
complish  the  effect  of  a  SET  com¬ 
mand  against  the  master  environ¬ 
ment  block  from  the  level  of  an 
executing  application.  I’ll  discuss 
these  techniques  in  next  month's  col¬ 
umn.  See  you  then! 


DDJ 

(Listings  begin  on  page  86.) 
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Factoring  in  Forth 


REATE  . . .  DOES>  is  the  pearl  of 
Forth,  a  way  to  wrest  control 
from  the  compiler  and  vest  it  in  the 
programmer,  where  Forth  program¬ 
mers  believe  it  rightfully  belongs.  But 
CREATE . . .  DOES>  is  not  just  a  power 
play,  a  blow  struck  for  programmer 
independence;  it  is  also  an  example 
of  superb  factoring.  In  this  column,  I 
want  to  talk  about  factoring,  an  elu¬ 
sive  thread  woven  throughout  the 
fabric  of  Forth.  Because  it  is  so  elu¬ 
sive,  sneaking  up  on  it  metaphorical¬ 
ly  might  be  the  best  approach. 

You  first  find  factoring  when  you 
create  commands.  Forth  program¬ 
mers  routinely  create  new  com¬ 
mands;  that  is  how  Forth  programs 
are  written.  Many  Forth  program¬ 
mers  arrive  from  other  languages 
and  are  familiar  with  procedures 
and  named  subroutines.  Their  habits 
and  expectations  from  that  prior  ex¬ 
perience  lead  them  astray.  Instead  of 
short  commands,  they  write  large 
chunks  of  code,  difficult  to  debug  and 
fitting  only  the  particular  situation 
that  prompted  them. 

Their  former  languages  required 
separate  compilation  and  linking,  and 
the  economics  of  that  overhead  made 
it  sensible  to  pack  procedures  with 
enough  code  to  balance  the  time  and 
effort  to  compile  and  test  it.  In  Forth, 
though,  the  totally  interactive  compil¬ 
er  is  right  at  hand,  and  each  word  is  a 
self-contained  module  that  can  be  run 
alone.  Compilation  is  cheap,  linking  is 
less,  so  the  module  can  be  small — in 
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fact,  it  should  be  small. 

Veteran  Forth  programmers  smile 
tolerantly  at  the  novice's  monster 
word  and  in  its  place  produce  two 
dozen  tiny  words.  These  words  are 
typically  bug-free,  each  being  utterly 
simple,  and  they  snap  together  like 
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Leggo  blocks  to  build  a  command 
that  efficiently  accomplishes  the 
same  task  as  the  beginner's  awkward 
monster.  Even  better,  the  little  words 
can  be  assembled  in  many  ways  and 
thus  find  many  uses. 

The  veteran  builds  general-pur¬ 
pose  tools  from  the  elements  of  the 
solution.  The  beginner,  unable  to  lo¬ 
cate  the  separate  essences,  constructs 
a  word  that  addresses  the  entire  com¬ 
pound  situation.  The  veteran’s  skill  at 
factoring  consists  of  being  able  to  find 
the  independent  components  implic¬ 
it  in  the  task  and  to  define  those 
words  first. 

To  take  a  simple  example:  Suppose 
the  programmer  needs  to  calculate  a 
percentage,  rounded  to  tenths,  and 
display  it  at  a  certain  location  on  the 
screen.  Listing  One,  page  94,  shows 
how  a  beginner  might  do  this:  The 
word  %  does  everything  required — 
that  is,  too  much.  The  veteran  auto¬ 
matically  factors  the  requirement 
into  several  commands,  as  shown  in 
Listing  Two,  page  94.  One  word  calcu¬ 
lates  the  percentage  to  tenths,  leaving 
the  result  on  the  stack.  Another  for¬ 
mats  an  ASCII  string  that  represents 
the  number  found  on  the  stack,  as¬ 
suming  the  least  significant  digit  rep¬ 
resents  tenths.  These  two  words  are 
then  used  to  define  a  word  that  calcu¬ 
lates  the  percentage,  formats  the 
string,  and  then  displays  it.  Cursor 
placement  is  handled  separately  so 
that  this  word  can  be  used  for  a  dis¬ 
play  anywhere  on  the  screen — or  on 
a  printer,  for  that  matter.  In  fact,  in 
addition  to  the  general-purpose  per¬ 
centage-display  word,  we  now  have  a 
word  that  calculates  percentages  and 
a  word  that  shows  a  number  as 


tenths.  Other  words  can  be  defined 
from  these  tools — for  example,  the 
word  %  .  R  displays  the  percentage 
flush  right  in  a  field  of  specified 
width. 

But  factoring  involves  more  than 
writing  a  series  of  small  definitions 
that  fit  together  to  address  a  task.  It 
requires  finding  the  "true”  divisions, 
teasing  apart  the  whole  to  reveal  its 
internal  structure.  To  factor  proper¬ 
ly,  find  the  subtasks  nestled  within 
the  task.  Factoring  requires  a  sensitiv¬ 
ity  to  the  underlying  structure  of  the 
situation.  If  the  problem  itself  is  ele¬ 
mentary,  to  find  its  parts  is  of  course 
no  problem.  For  programmers,  how¬ 
ever,  problems  arrive  entangled  in 
each  other,  embedded  in  assump¬ 
tions  and  past  practice,  and  often  not 
even  announced  as  problems.  The 
first  hint  that  the  factoring  is  bad 
may  be  that  the  definition  is  difficult 
to  write. 

The  rightness  of  the  factoring  is 
marked  by  a  simplicity,  but  that  sim¬ 
plicity  is  not  easily  attained  and  is  also 
somewhat  deceptive.  To  call  a  defini¬ 
tion  simple  just  because  it  contains 
few  commands  is  a  triumph  of  syn¬ 
thesis.  Our  ability  to  chunk  knowl¬ 
edge  and  convert  a  name  from  point¬ 
er  to  entity  enables  us  to  hide 
intricacies  beneath  the  skin  of  a  single 
concept.  From  complexity  we  can  ex¬ 
tract  simplicity. 

Our  minds  want  to  find  or  make  a 
unity.  Factoring  fights  upstream 
against  this  tendency.  Factoring  re¬ 
quires  us  to  forsake  unity  and  probe 
the  problem  to  locate  the  separate 
masses  that  form  the  unit:  locate 
them,  separate  them,  and  name  them. 

Good  analysis  teases  apart  the 
whole,  finding  and  revealing  the  true 
divisions.  It  is  done  less  by  logic  than 
by  an  inward  tactile  sense  that  can 
somehow  distinguish  masses  still  hid¬ 
den  in  the  dark  of  ignorance.  Once 
we  grasp  the  inner  structure  and 
break  the  problem  down,  the  divi¬ 
sions  stand  exposed  to  the  illumina- 
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tion  of  understanding.  Anyone  can 
see  them  once  the  job  is  done.  But 
when  the  problem  is  still  murky — 
perhaps  not  even  yet  seen  as  a  prob¬ 
lem — recognizing  its  separate  parts  is 
difficult.  And  if  the  analysis  is  done 
humpty-dumpty,  the  pieces  won’t  fit 
together  again.  Factoring  thus  re¬ 
quires  us  to  understand  which  func¬ 
tions  belong  together  and  which  do 
not.  Functions  are  factored  together 
or  apart  depending  on  how  they  fit 
in  the  overall  structure.  In  both  direc¬ 
tions,  names  are  the  navigation 
lights.  We  recognize  (create?)  a  unity 
by  assigning  a  name  to  a  group;  we 
analyze  a  unity  by  naming  its  parts. 
Names  are  our  guide  and  our  tool. 

Analysis  is  very  good  indeed  at 
marking  the  path  once  a  good  factor¬ 
ing  has  been  reached,  but  the  factor¬ 
ing  itself  may  have  been  achieved  di¬ 
rectly  through  an  alert  awareness 
toward  your  experience  with  the 
problem.  You  live  and  work  with  the 
problem  for  days  or  even  weeks, 
then  "suddenly”  the  solution  is  obvi¬ 
ous.  Analysis  then  discovers  or  con¬ 
structs  the  reasons  this  approach  is 
sound. 

For  example,  I  wrote  a  program  re¬ 
cently  in  which  the  user  enters  the 
date.  To  avoid  possible  ambiguity,  I 
labeled  separate  fields  for  the  month, 
day,  and  year.  The  user  can  move 
from  field  to  field  with  the  arrow 
keys,  and  when  he  or  she  types  an 
entry  and  presses  Enter,  the  cursor 
moves  to  the  next  field.  For  weeks  I 
unconsciously  first  pressed  /  (associ¬ 
ated  in  my  mind  with  entering  the 
date)  and  then,  when  /  had  no  effect, 

i 

]  automatically  pressed  Enter.  One  day 
j  I  noticed  what  I  was  doing.  Once  I 
j  had  noticed,  the  solution  was  simple: 
j  I  made  /  (and  for  good  measure  —  as 
j  well)  equivalent  to  Enter  in  the  date- 
entry  routine. 

Another  example  of  the  slow  sur¬ 
facing  of  a  buried  problem  occurred 
in  the  same  routine.  The  routine  is 
smart  enough  to  know  that  months 
get  no  larger  than  12  and  days  no  larg¬ 
er  than  the  maximum  for  the  current 
month.  It  observes  these  limits  when 
you  type  new  digits,  which  enter  the 
display  from  the  right.  If  you  enter  1 
for  a  day  and  then  type  7,  for  exam¬ 
ple,  the  display  shows  17;  typing  th» 
same  sequence  for  a  month  leaves  the 
display  with  7,  not  17. 

With  this  routine,  you  can  usually 


correct  a  typo  just  by  typing  the  cor¬ 
rect  number:  If  you  type  7  instead  of 
8,  you  can  correct  it  simply  by  typing 
8 — 78  will  not  appear  for  a  month  or 
a  day.  Sometimes,  however,  you 
have  to  repeat  a  key  to  get  it  to 
"take” — for  the  month,  if  you  type  1 
when  you  mean  2,  following  the  1  by 
2  results  in  12  (still  not  what  you 
mean),  but  typing  a  second  2  pro¬ 
duces  2  (not  22,  which  is  invalid  for  a 
month).  The  same  pattern  works  for 
the  day.  Suppose  you  type  2  instead 
of  5.  If  you  now  type  5,  you  get  25,  but 
|  typing  another  5  produces  the  5  you 
want  because  55  is  invalid  for  a  day. 

Repeating  the  number  feels  famil¬ 
iar,  like  repeating  something  to  an  in¬ 
attentive  listener.  It  fails,  however,  to 
work  with  11  and  with  22  (for  day).  If 
you  type  1  when  you  mean  2,  for  ex- 
j  ample,  typing  the  2  produces  12,  a 
|  second  2  produces  22,  and  all  subse- 
j  quent  2s  leave  the  number  22.  It  took 
[  me  a  long  time  to  become  aware  that 
1  and  2  didn't  work  in  the  same  way 
as  did  the  other  numbers,  even 
though  I  did  experience  their  behav¬ 
ior.  I  was,  however,  vaguely  aware 
that  something  was  wrong,  and 
when  I  finally  realized  what  it  was,  I 
easily  changed  the  program  so  that  it 
would  realize  that  1  typed  when  11 
was  present  did  not  mean  11 — 11  was 
already  there.  In  that  case  the  pro¬ 
gram  drops  11  and  leaves  only  1.  Sim¬ 
ilarly,  2  typed  when  22  is  showing 
now  produces  2,  not  another  22.  So 
now  all  numbers  act  the  same:  if  you 
want  the  number  by  itself,  just  type 
it,  possibly  more  than  once. 

Analysis  can  serve  as  a  touchstone 
to  verify  the  accuracy  of  a  solution 
reached  by  other  means,  and  some¬ 
times  analysis  can  itself  lead  you  to- 
i  ward  the  right  factoring.  But  you  can 
]  augment  analysis  with  other  ap- 
!  proaches.  Activate  them  deliberately 
by  immersing  yourself  in  the  prob¬ 
lem  early  on  so  that  your  translogical 
processes  have  time  to  play  with  the 
problem  and  deliver  their  results. 

Forth’s  interactivity  naturally 
leads  to  an  experimental  and  explor¬ 
atory  approach  that  encourages  an 
early  intimacy  with  the  characteris¬ 
tics  and  implications  of  a  problem, 
which  ultimately  leads  to  a  deep  un¬ 
derstanding.  The  feedback  loop  thus 
established  often  leads  to  long  ex¬ 
changes  in  which  an  idea  is  tried  and 
gives  a  result  that  points  to  another 


idea:  experience  gives  an  insight  on 
which  to  base  a  new  attempt,  pro¬ 
ducing  a  repeating  cycle  that  moves 
to  the  heart  of  the  problem. 

Charles  Moore,  Forth’s  father, 
found  the  FORTRAN  compiler  he  was 
using  uncomfortable  and  awkward 
to  use.  He  had  the  insight  to  see  that, 
for  his  needs,  it  was  factored  incor¬ 
rectly.  The  factoring  of  the  FORTRAN 
compiler  placed  it  outside  the  lan¬ 
guage.  Moore  saw  that  the  correct 
factoring  for  his  purposes  put  the 
compiler  inside  the  language,  where 
he  could  use  it  directly. 

With  the  compiler  now  at  hand,  he 
factored  it  into  its  separate  functions. 
He  eliminated  the  complexities  of  pa¬ 
renthesis  parsing  by  eliminating  the 
parentheses.  He  made  some  words 
“immediate,”  to  execute  during  com-  j 
pilation  and  thus  function  as  compil¬ 
er  directives.  (The  directive  [COM¬ 
PILE],  for  example,  is  immediate;  it 
forces  the  following  immediate  word 
to  be  compiled  even  when  it  normal¬ 
ly  would  execute.)  He  eliminated 
rarely  used  compiler  constructs.  The 
programmer  could  easily  add  them 
when  they  were  needed,  now  that 
the  compiler  was  a  part  of  the  lan¬ 
guage.  Thus,  in  place  of  the  old  do- 
everything,  batch-oriented  compiler 
that  stood  outside  the  program, 
Moore  built  into  the  language  a  com¬ 
piler  factored  into  tools  that  the  pro¬ 
grammer  could  use  in  tailoring  it  to 
the  current  job. 

CREATE  and  DOES>  were  found  in 
the  factoring  of  the  compiler.  These 
words  give  the  programmer  a  strong 
voice  in  compiler  activities.  The  pro¬ 
grammer’s  CREATE .  .  .  DOES>  words  1 
are  added  to  the  compiler  and  define  [ 
new  kinds  of  words  targeted  at  the 
task  at  hand.  These  words  owe  their 
existence  to  the  idea  of  factoring  the 
compiler  into  the  language,  making  it 
accessible  for  this  kind  of  control. 

CREATE  and  DOES>  also  factor  the 
definition  into  phases.  When  the  de¬ 
fining  word  is  compiled  (called  its 
compile  time),  the  (nonimmediate)  j 
words  in  its  definition  are  laid  down 
in  the  dictionary  for  later  execution. 
Its  run  time  comes  when  it  is  execut¬ 
ed  to  define  a  child  word;  this  is  the 
child’s  compile  time.  At  that  time,  the  j 
defining  word’s  CREATE  clause  is  exe¬ 
cuted,  putting  the  child's  definition 
into  the  dictionary.  Only  at  the 
child’s  run  time,  when  the  child  itself 
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is  executed,  does  the  DOES>  clause  in 
the  parent  quicken  at  last  to  life. 

Moore's  factoring  of  the  compiler  | 
also  offers  other  words  that  can  serve 
for  defining  words.  The  word  OC¬ 
TAVE,  for  example,  doubly  defined  in 
Listing  Three,  page  94,  might  be  used 
in  a  music  application  to  define  the 
frequency  of  a  note  an  octave  above  a 
given  note.  The  first  definition  of  OC¬ 
TAVE  uses  CREATE  and  DOES>  as  you 
would  expect.  CREATE  puts  a  header 
into  the  dictionary,  with  CREATE’ s 
usual  code  field.  When  the  CREATEd 
word  is  executed,  its  code  field  con¬ 
tributed  by  CREATE  puts  the  address 
of  the  beginning  of  its  parameter 
field  on  the  stack. 

The  next  step  after  CREATE  (taken 
at  the  defined  word’s  compile  time)  is 
to  comma  the  number  on  the  stack  (at 
compile  time)  into  the  current  top  of 
the  dictionary — the  beginning  of  the 
parameter  field  of  the  new  word. 
Comma  advances  the  dictionary 
pointer  past  this  parameter  field. 
(Normally  a  CREATEd  word  has  no  pa¬ 
rameter  field;  here  comma’s  action 
reserves  the  parameter  field.) 

The  DOES>  stored  in  OCTAVE'S  defi-  j 
nition  terminates  the  compile-time  I 
action  of  the  word  being  defined  [ 
(when  OCTAVE  is  executed  to  define  a 
word).  DOES>  also  replaces  the  CRE¬ 
ATE  code  field  in  the  child  with  a 
code  field  that  points  to  itself. 

When  the  child  is  run,  its  code  field 
points  to  the  DOES>  in  OCTAVE,  and 
so  it  follows  the  dictates  of  its  parent. 
DOES>  now  places  on  the  stack  the 
address  of  the  child's  parameter 
field.  Then  DOES>  executes  the 
j  phrase  in  the  parent  following  itself 
j  until  it  reaches  the  parent's  semico¬ 
lon.  In  this  example,  the  only  word 
following  DOES>  is  @,  which  re¬ 
places  the  address  on  the  stack  with 
the  contents  of  that  address:  the  dou¬ 
bled  frequency  stored  when  the 
child  was  defined. 

The  second  definition  of  OCTAVE 
uses  CONSTANT  as  the  defining  word. 
CONSTANT  itself  does  everything  we 
need  except  double  the  number,  and 
so  we  can  eliminate  CREATE  and 
DOES>  altogether. 

Execution  Arrays 

A  well-factored  word  can  be  used  in 
unexpected  ways  because  it  is  not  en¬ 
meshed  in  the  particularities  of  its 
original  implementation.  In  the  pre- 

Dr.  Dobb's  Journal,  October  1986 


vious  example,  CONSTANT  was  used 
as  a  substitute  for  CREATE  and 
DOES>.  The  next  example  uses  the 
colon  in  an  unexpected  way  by  ex¬ 
ploiting  DOES>’  s  powers. 

In  Forth,  an  execution  vector  or  ex¬ 
ecution  array  contains  the  compila¬ 
tion  addresses  of  Forth  words.  The 
program  dips  into  the  array  using  an 
offset  somehow  derived,  fetches  the 
address  found  there,  and  executes  it. 
Different  offsets  can  thus  produce  ar¬ 
bitrarily  different  results. 

Execution  arrays  are  a  common 
tool  when  the  users  of  a  program  se¬ 
lect  options  from  a  menu.  The  natu¬ 
ral  implementation  of  a  menu  re¬ 
turns  the  number  of  the  selected 
item,  and  this  number  can  be  used  as 
the  offset  into  an  array  of  actions. 
The  obvious  approach  is  shown  in 
Listing  Four,  page  94.  CREATE  puts  the 
header  OPTIONS  into  the  dictionary. 
When  OPTIONS  is  later  executed,  it 
puts  on  the  stack  the  address  of  what 
amounts  to  the  parameter  field,  the 
first  byte  after  the  header.  In  this  ex¬ 
ample,  several  compilation  addresses 
have  been  stored  in  the  dictionary, 
beginning  at  this  location.  J  started 
the  compiler,  and  so  the  words  fol¬ 
lowing  it  were  not  executed.  Instead, 
the  compiler  found  their  compilation 
addresses  and  stored  them  in  the  dic¬ 
tionary,  word  by  word.  The  [  turned 
the  compiler  off  again.  The  words 
>PRINTER,  >D1SK,  >SCREEN,  and 
>DOS  are  assumed  to  have  been  de¬ 
fined  earlier  to  perform  the  desired 
actions.  The  word  DO-OPTIONS  uses 
the  number  on  the  stack  to  dip  into 
the  array  and  execute  the  word  thus 
referenced. 

However,  the  action  of  first  creat¬ 
ing  a  header  and  then  finding  the 
compilation  addresses  of  a  series  of 
words  and  storing  those  addresses 
into  the  dictionary  as  they  are  found 
is  precisely  the  action  of:  (colon).  I  use 
:  in  a  defining  word  that  creates  exe¬ 
cution  arrays,  as  shown  in  Listing 
Five,  page  94. 

In  a  typical  defining  word,  DOES> 
terminates  the  actions  that  follow 
CREATE  when  the  defining  word’s 
child  is  being  compiled.  VECTOR:, 
however,  contains  no  CREATE.  The 
compilation  begun  by  the  colon  con¬ 
tinues  until  a  semicolon  turns  off  the 
compiler.  As  soon  as  the  semicolon 
acts,  the  return  stack  takes  the  action 
back  to  the  word  being  executed  and 


continues  with  the  next  word  in  its 
definition.  The  word  being  executed 
(at  compile  time)  is  VECTOR:,  and  the 
next  word  in  its  definition  is  DOES>. 
DOES>  replaces  the  compilation  ad¬ 
dress  of  the  child,  which  this  time 
I  contains  not  the  CREATE  code  field 
but  the  colon  code  field — the  run¬ 
time  colon  that  will  normally  exe¬ 
cute  the  words  in  the  definition  in 
turn.  DOES>,  however,  takes  no  no¬ 
tice  of  the  contents  of  the  code  field.  It 
simply  overwrites  them  with  the  ad¬ 
dress  of  VECTOR  ’S  does>. 

When  the  child  word  OPTION  is  ex- 
|  ecuted,  VECTOR:’ s  DOES>  places  the 
address  of  OPTION’S  parameter  field 
on  the  stack  and  swaps  that  address  to 
find  the  number  beneath.  This  num- 
|  ber  is  doubled  and  then  added  to  the 
{  parameter  field  address  to  get  the 
[  compilation  address  of  the  word  to  be 
executed.  That  address  is  then  fetched 
[  and  executed. 

VECTOR:  defines  an  execution  array 
and  also  makes  it  produce  and  exe¬ 
cute  the  right  element  of  itself.  Be¬ 
cause  the  word  itself  does  the  work, 
the  surrounding  code  is  simplified. 
Harry  Wilker,  author  of  Back  to  Basics 
Accounting,  which  was  written  in 
Forth  and  is  published  by  Peachtree, 
says  that  he  begins  a  new  program  by 
figuring  out  what  data  structures  he 
will  need  and  what  he  wants  these 
structures  to  do.  He  creates  the  appro- 
i  priate  defining  words  and  writes  his 
program  outward  from  there,  with 
the  data  structures  themselves  doing 
much  of  the  program’s  work. 

Wilker’s  approach  is  strong  because 
it  exploits  some  of  Forth’s  special 
strengths  and  because  it  is  theoretical¬ 
ly  correct:  the  program  should  indeed 
be  rooted  in  the  data  structures.  Prob¬ 
ably  more  programmers  would  fol¬ 
low  his  example  except,  as  noted  ear¬ 
lier,  many  come  to  Forth  from  other 
languages  and  are  accustomed  to  pro¬ 
gramming  techniques  that  depend  on 
developing  algorithms  rather  than  on 
defining  new  structures.  We  all  are 
|  reluctant  to  discard  a  tool  that  once 
|  has  worked. 

Naming  Style 

VECTOR:  is,  I  think,  a  bad  name:  me¬ 
chanical,  klunky,  and  earthbound.  In 
my  July  column  I  gave  the  name  FOR 
to  an  array-defining  word.  As  a 
name,  FOR  has  what  VECTOR:  lacks — 
FOR  is  a  short  English  word  that 
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makes  the  code  read  naturally,  and  it 
doesn’t  belabor  the  reader  with  de¬ 
tails  of  the  implementation.  For  this 
example,  I  think  the  name  EMPOWER 
is  vastly  superior  to  VECTOR: — EM¬ 
POWER  fits  the  task  and  has  more  pa- 
i  nache.  VECTOR:  was  the  working 
name;  once  the  word  is  complete,  it 
pays  to  take  a  minute  to  find  a  better 
!  name.  I  dub  the  word  EMPOWER. 

Naming,  however,  takes  on  some 
aspects  of  style,  and  matters  of  taste 
j  seldom  find  unanimity.  Many  Forth 
I  programmers  find  names  such  as 
J  FOR  and  EMPOWER  about  as  agreeable 
;  as  eggshell  in  a  souffle'.  They  prefer 
i  names  such  as  ARRAY  and  VECTOR:, 

|  which  they  find  direct  and  descrip¬ 
tive;  FOR  and  EMPOWER  strike  them 
as  pretentious  and  ethereal,  abstract 
and  unrelated  to  what  is  happening.  I 
suspect  that  they  also  find  names  of 
this  ilk  to  be  inappropriately  playful 
in  a  programming  context. 

I,  of  course,  believe  that  1  tread  a 
middle  course  of  elegance  and  econo¬ 
my.  For  example,  I  rejected  the  idea 
of  defining  with  as  an  immediate  no- 
|  op  to  be  used  with  EMPOWER: 

EMPOWER  OPTION  with  >PRINTER  .  .  . 
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( with  must  be  immediate  so  that  it  will 
leave  no  tracks  in  the  compiled  defini¬ 
tion).  1  also  take  comfort  from  a  name 
such  as  DROP,  which  also  speaks  to  the 
idea  of  what  is  happening  rather  than 
to  the  mechanism  that  does  it.  DROP 
grasps  the  metaphoric  center  of  the 
action. 

But  it  is  only  fair  to  recognize  that 
some  Forth  programmers  shudder 
when  they  encounter  names  that  de¬ 
light  others  by  the  unexpected  apt¬ 
ness  of  a  word  found  in  a  new  but 
fitting  context.  Some  find  delight  in 
wordplay;  others  do  not.  For  both 
groups,  though,  names  are  indeed  im¬ 
portant — on  that  they  agree.  In  Think¬ 
ing  Forth  (Englewood  Cliffs,  N.J.:  Pren¬ 
tice-Hall,  1984)  Leo  Brodie  offers 
sound  advice  on  choosing  names: 
choose  names  according  to  "what” 
not  "how”;  find  the  most  expressive 
word;  favor  short  words;  hyphenated 
names  may  be  a  sign  of  bad  factoring; 
and  many  others,  with  plenty  of  ex¬ 
amples. 


Correction  Prevention 

Can  you  tell  what  the  following  se¬ 
quence  means  and  give  the  next  two 


|  numbers?  (No  peeking.) 

0  0  9210  1023  -1  -30721 

These  numbers  turn  out  to  be  useful 
in  an  application  I  wrote  recently. 
Following  is  a  description  of  how 
they  arose.  (The  next  two  numbers 
are,  of  course,  1  and  10240.  Let  me 
know  if  this  is  too  easy.) 

I  mentioned  earlier  how  Moore 
simplified  the  handling  of  parenthe¬ 
ses  in  arithmetical  expressions  by 
eliminating  parentheses.  The  same 
technique  works  well  in  other  con¬ 
texts.  In  a  program  I  am  working  on 
now,  for  example,  the  user  is  asked  to 
enter  a  file  name.  In  PC-DOS  and  MS- 
DOS,  all  characters  in  the  ASCII  charac¬ 
ter  set  are  equal  but  some  are  more 
equal  than  others.  The  less-equal 
ones  are  not  allowed  in  file  names. 
Some  of  the  less-equal  characters  can 
be  used,  but  they  limit  DOS  activi¬ 
ties — for  example,  an  embedded 
blank  in  a  file  name  prevents  COPY 
and  DEL  from  performing  their  func¬ 
tions. 

The  first  approach  that  occurred  to 
me  was  that  I  should  edit  the  file 
name  for  a  new  file  and  warn  the 
user  when  an  illegal  character  had 
!  been  used,  asking  for  correction  or 
reentry.  Then  I  realized  this  was  a 
poor  factoring  of  effort.  Why  not 
write  code  to  keep  the  illegal  charac¬ 
ters  from  being  entered  in  the  first 
!  place,  rather  than  to  detect  and  fix 
them  later? 

I  set  up  a  bit  array  16  bytes  long  (128 
bits)  and  turn  on  the  bits  correspond¬ 
ing  to  the  ASCII  values  of  the  legal  file¬ 
name  characters.  When  the  user  en¬ 
ters  the  file  name,  I  simply  don't 
accept  any  character  for  which  the  bit 
is  off.  A  little  checking  saved  me  from 
having  to  write  a  (more  complex)  rou¬ 
tine  that  would  detect  errors  after  the 
fact  and  also  saved  me  from  having  to 
figure  out  a  good  interface  to  commu¬ 
nicate  errors  to  the  user  and  collect 
corrections  (or  allow  the  user  to  quit). 

My  first  solution  was  to  set  the  ar¬ 
ray  bits  in  an  initialization  word, 
which  used  the  bit  words  shown  in 
Listing  Six,  page  94.  (These  are  re¬ 
prised  from  my  last  column,  with 
one  name  improvement.)  But  then  I 
realized  that  setting  the  bits  took 
more  room  than  the  bit  table  itself,  so 
I  removed  the  bit  setting  from  the 
program  (Listing  Seven,  page  94). 


Note  that  I  don’t  use  the  lowercase  | 
alphabet:  When  the  user  is  entering 
file  names,  the  program  shifts  any 
lowercase  letters  to  uppercase. 

After  using  READOUT  to  verify  the 
correctness  of  the  bits,  I  used  READ  to 
list  the  equivalent  sequence  of  num¬ 
bers — the  sequence  of  eight  numbers 
shown  at  the  beginning  of  this  sec¬ 
tion.  These  are  used  to  create  an  ar¬ 
ray,  as  shown  in  Listing  Eight,  page 
94.  Voila:  no  need  to  edit  the  file  name 
because  illegal  information  is  barred 
at  the  door. 

The  bit  words  in  Listing  Six  were 
factored  differently  when  I  first 
wrote  them.  AIM  was  not  originally 
included  in  the  bit  words  ( +BIT,  —BIT, 
and  so  on).  It  was  only  after  I  used  the 
words  for  a  while  that  I  realized  that 
AIM  should  be  factored  into  the  bit  op¬ 
erators.  By  putting  AIM  inside  the 
words,  I  hide  that  particular  opera¬ 
tion. 

I  have  discussed  how  Forth  repre¬ 
sents  a  new  way  to  factor  a  compiled 
language,  with  the  compiler  factored 
into  the  language.  I  have  also  talked 
about  how  the  compiler  itself  is  fac¬ 
tored  into  a  variety  of  words  that  can 
be  used  in  new  combinations  for 
new  results.  And  now  I  factor  "regu¬ 
lar”  Forth  words  to  hide  complexity 
where  appropriate.  Factoring  is  a 
part  of  Forth  at  every  level. 

How  can  you  improve  your  factor¬ 
ing  skills?  The  answer  really  is, 
"Try.”  I  have  outlined  some  methods 
in  this  article,  but  like  any  intuitive 
skill,  factoring  is  developed  through 
experience.  There  is  no  algorithm 
that  will  invariably  arrive  at  the  right 
result.  Like  the  right  word  in  a  poem, 
the  right  factoring  comes  with  a 
click.  You  may  approach  it  step  by 
step,  but  ultimately  you  make  a  leap. 
Once  there,  it  is  easy  to  build  a  bridge 
of  analysis  back  to  where  you  were. 
Leaping  is  learned  by  trying  to  leap. 

Factoring  in  fact  is  not  merely  a 
Forth  issue  nor  even  limited  to  pro¬ 
gramming.  Two  good  books  on  the 
processes  that  factoring  involves  con¬ 
cern  arts  other  than  programming. 
These  books  are  Writing  Without 
Teachers  by  Peter  Elbow  (New  York: 
Oxford  University  Press,  1973)  and 
The  Art  of  Craft  by  Carla  Needleman 
(New  York:  Avon  Books,  1981).  Proba¬ 
bly  the  best  discussion  of  Forth  fac¬ 
toring  is  in  Brodie's  book  Thinking 
Forth,  mentioned  earlier.  Richard 
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|  Bolles  wrote  a  book  (The  Three  Boxes 
of  Life,  Berkeley,  Calif.:  Ten  Speed 
Press,  1981)  in  which  he  discusses 
how  people  factor  their  lives.  He  be¬ 
lieves  that  people  incorrectly  factor  j 
learning,  work,  and  play  (retirement, 
for  example)  into  three  separate 
times  in  their  lives,  and  he  explores 
other  factorings  to  stretch  the  three 
j  as  strands  lengthwise  along  your  life. 

Good  factoring  is  generally  the  re¬ 
sult  of  a  creative  insight  that  trans¬ 
forms  your  view  of  the  problem.  Ed¬ 
ward  de  Bono  has  written  a  variety 
of  books  that  directly  address  lateral 
thinking,  which  is  his  term  for  this 
mode  of  thought.  Some  of  his  books  I 
have  liked  are  The  Mechanism  of  \ 
Mind  (1971),  Po  (1974),  The  Five-Day  ■ 
Course  in  Thinking  (1974),  and  The  Use  j 
of  Lateral  Thinking  (1975).  All  are  pub-  ! 
lished  by  Penguin  Books,  Middlesex, 
England,  but  are  readily  available  in 
this  country  as  well.  Pergamon  Press 
(Fairview  Park,  Elmsford,  NY  10523) 
publishes  the  CoRT  Program,  a  six- 
lesson  course  in  creativity  and  think- 
j  ing,  which  was  developed  by  de 
Bono  and  his  associates.  CoRT  is  an 
acronym  from  The  Cognitive  Re¬ 
search  Trust. 

Outline  Processors  and 
Programming 

I  have  found  that  an  outline  processor 
is  a  great  tool  for  analyzing  a  pro¬ 
gramming  problem.  Outline  proces¬ 
sors  seem  particularly  suited  to  a  lan¬ 
guage  such  as  Forth,  whose  words 
form  a  hierarchy  that  can  mimic  the 
structure  of  the  outline.  The  outline 
develops  naturally  from  a  top-down 
analysis. 

I  use  an  outline  processor  to  sketch 
the  overall  shape  of  a  program,  but  it 
is  also  very  useful  ad  hoc.  When  I  get 
stuck,  or  find  myself  lost  or  confused, 

I  call  on  my  trusty  outliner.  I  aim  the  j 
outline  just  at  the  problem  of  the  mo¬ 
ment.  A  short  session  of  outlining  i 
usually  produces  a  "script”  that  I  can  j 
take  back  to  Forth  and  use  to  direct 
the  code  I  write.  The  Forth,  of  course, 
is  written  from  bottom  up,  or  inside 
out — in  the  inverse  order  of  the  out- 
{  line  structure.  In  writing  the  outline, 

I  don’t  attempt  to  write  Forth  com¬ 
mands.  I  simply  write  simple  English 
statements  that  describe  what  needs 
to  be  done  as  clearly  as  I  can. 

My  first  pass  through  the  problem 
I  usually  produces  a  rambling  set  of 


statements  in  the  wrong  order.  The 
advantage  of  the  outline  processor  is 
the  ease  with  which  I  can  revise  and 
reorder  the  topics,  insert  new  topics, 
and  move  topics  (with  or  without 
their  subtopics)  up  or  down  in  the  hi¬ 
erarchy. 

The  outline  processor  I  like  most  is 
MaxThink  [MaxThink,  230  Crocker 
Ave.,  Piedmont,  CA  94610;  (800)  227- 
1590,  in  CA  (800)  642-2406],  MaxThink 
costs  $89  and  is  available  for  the  IBM 
PC  and  compatibles  and  for  the  Ap¬ 
ple  Macintosh.  It  is  not  copy  protect¬ 
ed.  In  addition  to  the  usual  set  of  out¬ 
line  commands  and  a  good  user 
interface,  it  has  a  variety  of  tools  to 
stimulate  thought.  Neil  Larson,  the 
designer,  is  a  longtime  fan  of  de 
Bono,  and  some  of  de  Bono’s  tech-  | 
niques  are  built  into  this  package. 
Framework  II  is  also  a  nice  package, 
but  because  it  is  copy  protected,  I 
would  not  base  any  important  work 
on  it. 

One  nice  side  effect  of  outlining  the 
solutions  is  that  the  outlines  become 
valuable  adjuncts  to  the  program 
documentation.  Also,  the  use  of  out¬ 
lines  allows  you  to  tackle  a  larger 
problem  than  you  could  otherwise 
manage:  the  outline  marks  the  trail 
and  organizes  the  effort,  letting  you 
focus  your  concentration  on  the 
parts  without  losing  a  grasp  of  the 
whole. 

Things  Mom  forgot  to 
Mention 

After  writing  a  large  program,  we 
are  painfully  aware  of  oversights  and 
missed  opportunities.  Our  most  pow¬ 
erful  tool  is  hindsight,  and  the  look 
backward  can  often  provide  good 
guidance  for  the  next  project.  Experi¬ 
ence  is  not  one  big  thing;  it  is  many 
little  things.  Here  are  a  few  words  I 
wish  I  had  read  before  starting  my 
latest  project. 

Screen  files  are  easier  to  use  than 
text  files  because  you  can  load  and  test 
individual  screens.  However,  because 
you  don't  have  to  deal  with  the  total 
file  as  you  work,  a  screen  file  grows 
without  your  realizing  it — especially 
if  you  save  a  precompiled  version  of 
the  work  to  date  so  that  you  are  al¬ 
ways  adding  on  just  a  little  bit. 

I  am  glad  I  used  screen  files,  but  I 
wish  I  had  paid  closer  attention  to 
factoring  the  functions  into  different 
files  instead  of  making  the  files 


match  the  program  modules.  The 
date  routine,  for  example,  should 
have  been  in  a  file  by  itself,  to  be  in¬ 
cluded  whenever  I  needed  it.  In¬ 
stead,  it  is  copied  into  the  different 
module  files — bad  show.  Next  time  I 
will  use  many,  many  little  files. 

The  gradual  accretion  that  builds 
the  file  also  puts  more  code  behind 
you  than  you  realize.  Next  time  I  will 
take  a  weekly  break  to  revisit  and 
spruce  up  all  the  code  written  during 
the  week.  Hindsight  is  so  powerful,  I 
will  arrange  to  use  it  early  and  often. 
My  solemn  pledge  is  that  during  this 
weekly  review  I  will  do  the  follow¬ 
ing: 

•  rearrange  the  code  so  the  screens 
are  easy  to  read,  adding  new  screens 
when  more  space  is  needed; 

•  ponder  the  names  I  have  chosen 
and  see  if  they  can  be  improved; 

•  verify  the  accuracy  of  the  stack 
comments; 

•  add  comments  to  the  code  to  ex¬ 
plain  not  what  it  is  doing  but  why; 

•  try  to  improve  the  way  the  words 
are  factored  and  in  particular  to  find 
factorings  that  produce  useful  tools. 

Do  you  have  any  resolutions  to  add 
to  this  list?  Send  them  in;  maybe  we 
can  make  a  poster  for  Forth 
programmers. 
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Professional 

Organizations 

The  most  well-known  pro¬ 
fessional  organizations  for 
programmers  are  the  ACM 
(Association  for  Computing 
Machinery)  and  IEEE  (Insti¬ 
tute  for  Electrical  and  Elec¬ 
tronics  Engineers),  each  of 
which  has  many  chapters, 
SlGs  (special-interest 
groups),  and  publications. 
There  are  also  many  state, 
regional,  and  local  groups 
that  help  software  devel¬ 
opers  deal  with  laws  on 
business  practices,  copy¬ 
right,  trade  secrets,  and  so 
on.  Many  of  these  groups 
work  actively  to  influence 
legislation  and  generally 
promote  the  cause  of  the 
software  developer. 

The  Massachusetts  Com¬ 
puter  Software  Council 


(MCSC),  which  was  founded 
in  1985,  is  a  nonprofit  indus¬ 
try  association  of  chief  ex¬ 
ecutive  officers  of  indepen¬ 
dent  software  companies  in 
Massachusetts.  The  main 
goal  of  this  group  is  to  rep¬ 
resent  the  interests  and 
viewpoints  of  its  members 
and  their  businesses.  Mem¬ 
bership  is  open  to  all  CEOs 
of  businesses  principally 
engaged  in  the  design,  de¬ 
velopment,  or  distribution 
of  computer  software  prod¬ 
ucts  or  services  and  whose 
primary  place  of  business  is 
in  Massachusetts.  Founding 
members  of  MCSC  include 
Mitchell  Kapor,  CEO  of  Lo¬ 
tus  Development  Corp.,  and 
Daviel  Bricklin,  founder  of 
Software  Arts  and  creator 
of  VisiCalc.  The  group 
meets  quarterly  to  discuss 
issues  of  importance  to 


Massachusetts'  software  in¬ 
dustry.  Dues  are  based  on 
the  size  of  the  company.  A 
membership  newsletter, 
Software  Council  News,  is 
published  quarterly. 

The  Washington  State 
Software  Industry  Devel¬ 
opment  Board  (WSSIDB)  is 
sponsored  by  the  Econom¬ 
ic  Development  Partner¬ 
ship.  WSSIDB  sponsors  semi¬ 
nars  that  focus  on  issues  of 
interest  to  software  compa¬ 
nies,  including  topics  on 
money,  legal  issues,  and 
marketing.  Some  SlGs  of 
WSSIDB  include  the  Educa¬ 
tion  Committee,  the  Con¬ 
sultants  and  Entrepre¬ 
neurs  Group,  and  the 
Northwest  Venture  Club. 
Software  Board  News  is 
published  quarterly  for 
due-paying  members. 

The  Software  Entrepre¬ 
neurs’  Forum  (SEF)  meets  in 
the  Silicon  Valley  area.  The 
monthly  seminars  cover 
such  topics  as  legal,  tax, 
and  marketing  issues,  as 
well  as  future  trends  in  the 
computer  industry.  SlGs 
sponsored  by  SEF  include 
Macintosh,  CD-ROM,  Verti¬ 
cal  Markets,  IBM  Technical, 
and  Marketing.  The  SlGs 
meet  monthly  or  bimonth¬ 
ly.  A  monthly  newsletter  is 
sent  to  all  members. 

The  speakers  at  this  sum¬ 
mer’s  SEF  meetings  covered 
a  variety  of  interesting  top¬ 
ics.  Paul  Davis  of  Microsoft 
gave  an  overview  of  the 
Windows  system  and  dis¬ 
cussed  the  benefits  of  Win¬ 
dows  to  developers  in 
terms  of  I/O  device  inde¬ 
pendence,  compatibility 
with  next  generation  CPUs, 
and  overcoming  the  640K 
barrier.  Guy  Kawasaki  of 
Apple  Computers  gave  lis¬ 
teners  an  outline  of  Apple 
from  a  developer's  point  of 
view.  He  discussed  the  key 
to  success  in  the  Apple  mar¬ 
ketplace  and  explained  the 


concept  of  software  evan¬ 
gelism:  getting  people  excit¬ 
ed  about  doing  Apple  devel¬ 
opment.  Andy  Hertzfeld, 
who  created  much  of  the 
Macintosh  system  soft¬ 
ware,  as  well  as  Thunders- 
can  and  Switcher,  dis¬ 
cussed  his  new  product 
Servant,  which  is  designed 
to  replace  Finder. 

For  more  information  on 
these  professional  organi¬ 
zations,  please  contact 
them  at  the  following  ad¬ 
dresses: 

Association  for  Computing 
Machinery  (ACM) 

11  W.  42nd  St. 

New  York,  NY  10036 
(212)  869-7440 

The  Institute  of  Electrical 
and  Electronics  Engi¬ 
neers  (IEEE) 

345  E.  47th  St. 

New  York,  NY  10017 
(212)  705-7589 

Massachusetts  Computer 
Software  Council  (MCSC) 
c/o  MicroMentor  Inc. 

124  Mount  Auburn  St. 
Cambridge,  MA  02138 
(617)  497-5716 

Software  Entrepreneurs' 
Forum  (SEF) 

P.O.  Box  61031 
Palo  Alto,  CA  94306 
(415)  854-7219 

Washington  State  Software 
Industry  Development 
Board  (WSSIDB) 
c/o  The  Economic  Devel¬ 
opment  Partnership 
18000  Pacific  Highway  S. 
Seattle,  WA  98188 
(206)  433-1613 
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The  mass-storage  industry 
finally  seems  to  be  perking 
up  again,  now  that  CD- 
ROMs  (and  other  optical 
data-storage  devices)  are 
becoming  commercially 
feasible.  Prices  of  high-ca¬ 
pacity,  high-speed  disk 
drives  are  dropping  again, 
and  new  advances  are  be¬ 
ing  made  in  recording 
technology.  The  smallest 
hard  disks  of  all — the  ones 
that  live  on  their  own  in¬ 
terface  cards — are  starting 
to  show  some  pretty  im¬ 
pressive  storage  figures, 
and  the  data  densities  of 
the  physically  larger  de¬ 
vices  are  increasing  just  as 
rapidly.  Here  are  some 
examples: 

Express  Systems  offers  a 
range  of  hard  disks  on 
cards  for  the  IBM  PC  and  PC/ 
AT.  They're  called  Express 
Hard  DiskCards,  and  capac¬ 
ities  range  from  20  mega¬ 
bytes  to  60  megabytes. 


Prices  range  from  $449  to 
$1,095.  Reader  Service  No. 
16. 

Express  Systems 
1254  Remington  Rd. 
Schaumburg,  IL  60195 
(312)  882-7733  x3600 

A  21-megabyte  hard  disk 
on  a  card,  called  SlotMa- 
chine,  is  available  from  Ka- 
merman  Labs.  It  fits  into  a 
standard  IBM  PC  slot  and 
sells  for  $499.  Reader  Ser¬ 
vice  No.  17. 

Kamerman  Labs  Inc. 

7861  S.W.  Cirrus  Dr. 
Beaverton,  OR  97005 
(800)  522-2237 

Instar  Corp.  sells  an  opti¬ 
cal  disk  software  package 
called  ODI-PC  that  lets  an 
IBM  PC  randomly  access  up 
to  1  gigabyte  of  storage  on  a 
single  removable  disk.  The 
package  requires  a  write- 
once,  read-many  (WORM) 
optical  disk  drive  from  Al- 
cetel-Thompson,  Xerox,  or 
Sony.  The  interface  card, 
cable,  manual,  and  soft¬ 
ware  list  for  $1,575.  Reader 
Service  No.  18. 

Instar  Corp. 

141-6815  8th  St.  NE 
Calgary,  AB 
Canada  T2E  7H7 
(403)  275-3143 


The  DK815-10  is  an  8-inch 
hard-disk  drive  from  Hita¬ 
chi  that  stores  1,050  mega¬ 
bytes  of  unformatted  data. 
The  unit  uses  a  linear 
voice-coil  actuator  with 
double-wound,  thin  film 
heads  and  has  an  average 
access  time  of  15  millisec¬ 
onds.  The  price  is  $14,700 
in  sample  quantities  (no 
system  interface).  Reader 
Service  No.  19. 

Hitachi  America  Ltd. 

950  Elm  Ave. 

San  Bruno,  CA  94066 
(415)  872-1902 

Diskit  2  Plus  from  IDEAsso- 
ciates  is  an  external  hard¬ 
disk  drive  for  the  IBM  PC 
that  uses  hardware  en¬ 
cryption  to  protect  the  data 
on  its  removable  10-mega¬ 
byte  cartridges.  The  unit 
uses  the  Data  Encryption 
Standard  (DES)  to  prevent 
unauthorized  access.  It  also 
offers  on-line  backup  and 
an  intelligent  installation 
program  that  prompts  us¬ 
ers  with  plain-English 
questions.  The  price  of 
$3,595  includes  software, 
controller,  cabling,  two  10- 
megabyte  cartridges,  and  a 
maintenance  kit.  Reader 
Service  No.  20. 
IDEAssociates  Inc. 


29  Dunham  Rd. 

Billerica,  MA  01821 
(617)  663-6878 

For  the  Macintosh 

MORE  is  a  high-end  outline 
processor  and  organiza¬ 
tional  tool  from  Living  Vi¬ 
deotext.  The  integrated 
package  includes  full  out¬ 
lining  and  text  processing, 
tree  and  bullet  charts, 
cross-referencing,  pattern 
matching,  and  many  other 
features.  The  Macintosh 
version  costs  $295  and  is 
not  copy-protected.  Reader 
Service  No.  21. 

Living  Videotext 
2432  Charleston  Rd. 
Mountain  View,  CA  94043 
(415)  964-6300 

Hayes  Microcomputer 
Products  has  introduced  a 
communications  device 
that  connects  AppleTalk 
networks  locally  or  over 
modem  connections.  The 
product  is  called  Inter- 
Bridge  and  is  equipped 
with  AppleTalk  and  RS-232 
ports.  It  sells  for  $799.  Read¬ 
er  Service  No.  22. 

Hayes  Microcomputer 
Products  Inc. 

P.O.  Box  105203 
Atlanta,  GA  30348 
(404)  449-8791 
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The  Macintosh  can  talk  to 
Unix  through  MacNIX,  a 
Macintosh  icon-based  inter¬ 
face  to  Unix  systems.  Euro- 
soft  International’s  prod¬ 
uct  includes  a  virtual  file 
system  that  combines  local 
Macintosh  files  and  remote 
Unix  files  into  one  virtual 
directory  tree.  A  host  de¬ 
mon  implements  the  inter¬ 
face  on  the  Unix  end  while 
a  Macintosh  program  runs 
locally.  Installation  can  be 
done  completely  from  the 
Macintosh.  Prices  range 
from  $2,000  to  $7,000  for  the 
mainframe  software.  The 
local  Macintosh  disk  costs 
$49.95,  and  users  are  en¬ 
couraged  to  copy  it.  Reader 
Service  No.  23. 

Eurosoft  International  Inc. 
14082  Loma  Rio  Dr. 
Saratoga,  CA  95070 
(408)  741-0739 

MacBus  is  a  hardware  de¬ 
vice  from  National  Instru¬ 


ments  Corp.  that  lets  a 
Macintosh  Plus  use  IBM  PC/ 
AT  interface  cards.  The 
unit  has  five  AT-style  slots, 
two  of  which  are  used  for  a 
microprocessor  card  and 
an  interface  card  that  con¬ 
nects  to  the  SCSI  port  of  the 
Mac  Plus.  The  three  re¬ 
maining  slots  are  available 
for  any  cards  that  are  com¬ 
patible  with  the  AT  bus. 
The  microprocessor  card 
contains  a  National  Instru¬ 
ments  GBIP-V50  and  also 
supports  an  IEEE-488  inter¬ 
face.  The  hardware  unit 
lists  at  $1,495  and  the  Mac 
Plus  software  sells  for  $200. 
Reader  Service  No.  24. 
National  Instruments  Corp. 
12109  Technology  Blvd. 
Austin,  TX  78727 
(800)  531-4742 
in  TX  (800)  IEEE-488 

Hardware  for  the  PC 

The  386  Translator  from 

American  Computer  and 


OF  INTEREST 


Peripheral  is  a  plug-in  pig¬ 
gyback  card  that  replaces 
the  80286  processor  in  an 
IBM  PC/AT  with  an  80386. 
The  device  allows  software 
designers  to  take  advan¬ 
tage  of  the  capabilities  of 
the  80386  while  still  retain¬ 
ing  full  PC/AT  compatibil¬ 
ity.  With  an  80386  proces¬ 
sor  installed,  the  product 
costs  $895;  without  the  CPU 
it  costs  $395.  Reader  Service 
No.  25. 

American  Computer  and 
Peripheral  Inc. 

2720  Croddy  Way 
Santa  Ana,  CA  92704 
(714)  545-2004 

Intel's  Above  Board  PS/ AT 
is  an  expanded-memory 
multifunction  board  for 
the  IBM  PC/AT.  It  complies 
with  the  Lotus/Intel/Mi¬ 
crosoft  Expanded  Memory 
Specification  and  supports 


up  to  1.5  megabytes  of 
memory  alone  or  3.5  mega¬ 
bytes  with  the  Above 
Board  Piggyback  option. 
The  board  also  supplies  se¬ 
rial  and  parallel  ports  and 
several  software  utilities, 
including  a  RAM  disk  and 
print  buffer.  With  128K  the 
board  costs  $545;  a  512K 
version  sells  for  $695.  The 
Piggyback  memory  starts 
at  $295  for  a  128K  module. 
Reader  Service  No.  26. 

Intel  Corp. 

5200  N.E.  Elam  Young 
Pkwy. 

Hillsboro,  OR  97124 
(503)  629-7354 

Alloy  Computer  Prod¬ 
ucts’  Bi-TURBO  is  a  dual- 
tasking  accelerator  board 
that  allows  you  to  run  two 
programs  simultaneously 
by  dedicating  an  on-board 
NEC  V20  microprocessor  to 
the  second  task.  The  board 
also  contains  640K  RAM  for 
the  second  processor,  256K 


disk  cache  RAM,  and  a  pri¬ 
vate  COM2  port  for  the  sec¬ 
ond  task.  With  software  it 
costs  $995.  Reader  Service 
No.  27. 

Alloy  Computer 
Products  Inc. 

100  Pennsylvania  Ave. 
Framingham,  MA  01701 
(617)  875-6100 

Networking 

PC-Dial  is  a  modem  pro¬ 
gram  from  ButtonWare 
that  runs  on  the  IBM  PC. 
Features  include  automatic 
log-on  scripts  of  any 
length,  DOS  access,  a  mini- 
editor,  and  definable  mac¬ 
ro  keys.  It  costs  $59.95. 
Reader  Service  No.  28. 
ButtonWare 
P.O.  Box  5786 
Bellevue,  WA  98006 
(206)  454-0479 

Norton-Lambert’s  Close- 
Up  is  a  communications 
package  for  the  IBM  PC  that 
makes  a  remote  PC  into  a 


real-time  window  of  a  host 
PC.  The  package  allows  re¬ 
mote  printing,  graphics, 
file  transfer,  and  full  key¬ 
board  support.  The  host 
software  costs  $245,  and  the 
slave  software's  price  is  set 
at  $195.  Reader  Service  No. 

29. 

Norton-Lambert 
P.O.  Box  4085 
Santa  Barbara,  CA  93140 
(805)  687-8896 

A  communications  pro¬ 
gram  called  BackComm 
from  LaSalle  Micro  oper¬ 
ates  in  the  background  on 
IBM  PCs.  It  features  key¬ 
stroke  learning  for  auto¬ 
matic  connection,  pass¬ 
word  protection,  file 
encryption,  and  automatic 
call  scheduling.  It’s  priced 
at  $95.  Reader  Service  No. 

30. 

LaSalle  Micro  Inc. 

1350  Remington  Rd.,  #W 
Schaumburg,  IL  60195 
(312)  882-5171  x700 
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A  networking,  multitasking 
OS  called  Waterloo  Port  for 
the  IBM  PC  is  now  available 
in  the  U.S.  from  Waterloo 
Microsystems.  It  accom¬ 
modates  more  than  150  PCs 
and  runs  MS-DOS  as  one  of 
up  to  12  simultaneous  activ¬ 
ities  on  each  unit.  The  base 
price  is  $1,695.  Reader  Ser¬ 
vice  No.  31. 

Waterloo  Microsystems 
Inc. 

175  Columbia  St.  W 
Waterloo,  ON  N2L  5Z5 
Canada 

Languages 

Mach  2  from  MicroHelp  is 
a  collection  of  utilities  for 
BASIC  programmers  using 
MS-DOS  or  PC-DOS.  The  utili¬ 
ties  allow  the  programmer 
to  break  the  64K  data  limit 
of  BASIC  and  incorporate  a 
new  method  for  including 
assembly-language  rou¬ 
tines  in  interpreted  BASIC 
programs.  Reader  Service 
No.  32. 


MicroHelp  Inc. 

2220  Carlyle  Dr. 

Marietta,  GA  30062 
(404)  973-9272 

Chalcedony  Software  has 

released  Prolog/m  for  the 
Macintosh  and  Prolog/i  for 
the  IBM  PC.  The  languages 
support  floating-point 
arithmetic,  interactive  de¬ 
bugging,  and  more  than  100 
predefined  predicates  and 
operators.  They  come  with 
a  built-in  editor.  The  Macin¬ 
tosh  version  supports  the 
full  Mac  interface.  The  IBM 
version  supports  the  8087 
math  chip  and  the  large 
memory  model.  Prolog/m 
costs  $99.95,  and  Prolog/i 
costs  $69.95.  Reader  Service 
No.  33. 

Chalcedony  Software  Inc. 
5580  La  Jolla  Blvd. 

La  Jolla,  CA  92037 
(619)  483-8513 

Software  Development 
Systems  has  introduced 


the  Uni  Ware  68020  Cross- 
Compiler  System,  which 
runs  under  Unix,  Xenix, 
and  MS-DOS.  The  package 
includes  a  C  compiler,  link¬ 
er,  librarian,  and  utilities. 
ROMable  program  images 
can  be  generated  in  several 
standard  formats.  The  MS- 
DOS  version  costs  $595; 
Xenix  and  Unix  versions 
cost  $1,390  and  $2,790,  re¬ 
spectively.  Reader  Service 
No.  34. 

Software  Development 
Systems  Inc. 

3110  Woodcreek  Dr. 
Downer's  Grove,  IL  60515 
(312)  971-8170 

Microsoft  has  released  a 
new  BASIC  compiler  called 
QuickBASIC  2.0  for  the  IBM 
PC.  The  language  offers 
high-speed,  in-memory 
compilation  and  allows  us¬ 
ers  to  create  structured  and 
modular  programs.  It  in¬ 
cludes  a  built-in  editor  and 
debugger.  It’s  priced  at  $99. 


Reader  Service  No.  35. 
Microsoft  Corp. 

16011  N.E.  36th  Way 
Redmond,  WA  98052 
(206)  882-8080 

Microsoft's  Version  4.0  C 
compiler  has  several  en¬ 
hancements,  including  a 
new  debugger  called  Code¬ 
View  that  uses  windows  to 
give  programmers  more 
complete  control  over  the 
CPU  and  its  environment. 
The  Version  4.0  compiler 
also  implements  the  Unix 
System  V  C  library  and  sup¬ 
ports  the  proposed  ANSI 
standard.  The  new  compil¬ 
er,  debugger,  and  library 
cost  $450.  Reader  Service 
No.  36. 

Microsoft  Corp. 

16011  N.E.  36th  Way 
Redmond,  WA  98052 
(206)  882-8080 
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SWAINE'S  FLAMES 


The  question  is,  as  Mumpty  | 
Dumpty  said  to  Alice,  Which  is  I 
to  be  master?  j 

Andy  Hertzfeld  wrote  the  Macin-  j 
tosh  Finder  as  an  Apple  employee,  j 
He’s  no  longer  an  Apple  employee, 
but  he  hasn't  lost  his  fondness  for  the 
computer  and  hasn't  quit  tweaking  | 
its  operating  system.  His  Switcher  has 
become  for  many  users  of  the  Mac  an  j 
j  essential  component  of  the  system 
software,  making  the  difference  be¬ 
tween  feeling  like  the  machine's 
master  and  feeling  like  the  machine's 
the  master. 

And  now  there's  Servant,  Hertz¬ 
feld ’s  planned  replacement  for  Find-  j 
er.  Servant  will  allow  you  to  keep 
several  applications  open  at  a  time 
and  move  easily  between  applica¬ 
tions  and  the  desktop,  may  support 
batch-file  operations,  and  should 
generally  speed  up  the  operations 
that  tend  to  be  slow  on  the  Mac.  j 
Sounds  like  what  the  doctor  ordered,  j 
but  what  if  (  just  what  if)  Apple  should  ; 
j  decide  not  to  distribute  Servant  and  : 
Hertzfeld  decided  to  do  so?  Could  j 
Hertzfeld  simply  take  the  product  to 
the  users?  Will  the  Macintosh  come  i 
when  Andy  Hertzfeld  whistles? 

Phoenix  Technologies  would  like  ; 
someone  other  than  IBM  to  be  the  i 
master  of  the  80386.  Since  the  spring  i 
Comdex,  Phoenix  has  been  trying  to  ! 
j  get  companies  developing  80386-  i 
based  machines  to  agree  to  a  bus  stan¬ 
dard  for  the  machines.  Companies  I 
other  than  IBM,  that  is.  Whether  or  j 
not  Phoenix  gets  cooperation,  it  looks 
like  we  may  have  a  choice  of  “stan-  i 
dard"  80386  architectures.  j 

The  real  whfch-is-to-be-master  ! 
question  for  the  80386  concerns  the 
operating  system,  with  most  analysts 
insisting  that,  after  the  initial  phase  i 
in  which  the  80386  merely  will  serve  i 
to  make  PC-DOS  3.x  run  faster,  one  op-  j 
crating  system  must  emerge  as  the  j 
winner.  Microsoft  is  only  now  alpha¬ 
testing  its  nos  5.0  (which  supports 
[  protected  mode  for  the  80286)  and  i 


probably  won't  release  DOS  6.0  for 
the  80386  before  the  end  of  1987. 
AT&T,  on  the  other  hand,  has  Unix 
System  V/386  in  beta,  and  it's  sched¬ 
uled  for  release  in  November,  so  we 
can  expect  to  see  compilers  that  run 
under  Unix. 

In  fact,  a  bundle  recently  arrived 
from  Regis  McKenna  announcing  var¬ 
ious  artificial  intelligence  products  for 
the  80386  that  supposedly  are  coming 
out  in  the  next  six  months.  Gold  Hill, 
Lucid,  and  Franz  are  all  producing 
Common  LISP  compilers,  interpreters, 
and  development  tools.  Franz  is  also 
porting  Flavors,  its  object-oriented 
programming  environment,  to  the 
386.  And  Arity  is  bringing  its  version 
of  PROLOG  over.  All  the  products  have 
foreign-language  interfaces  for  C  and 
other  languages,  and  all  are  targeted 
for  Unix  System  V/386. 

It  makes  sense  to  use  the  80386  for 
AI  work.  Beyond  the  fact  that  AI 
work  simply  needs  a  lot  of  processing 
power,  AI  programs  typically  jump 
all  over  the  map  and  benefit  from  the 
flat  memory  space  of  a  processor  like 
the  80386. 

Meanwhile,  IBM  has  decided  to  dis¬ 
tribute  a  version  of  LISP  (Lucid's)  on  its 
32-bit  RISC-architecture  RT/PC.  The 
operating  system  of  the  RT/PC  is  a 
Unix  System  V  derivative. 

Of  course,  not  everyone  loves  Unix, 
Ken  Williams  of  Softguard  Systems  is 
traveling  around  talking  to  program¬ 
mers  about  VM386,  the  multitasking 
operating  system  his  company  is  de¬ 
veloping  for  the  80386  that  is  intend¬ 
ed  to  support  DOS  applications  while 


taking  advantage  of  the  advanced 
features  of  the  80386. 

Then  we  have  Hunter  Systems  try¬ 
ing  to  put  1X)S  on  68000  machines. 
Hunter  argues  that  if  DOS  were  speci¬ 
fied  in  C,  like  Unix,  it  would  be  as  por¬ 
table  as  Unix.  The  company  has  been 
working  with  several  hardware  and 
software  vendors  (including  Motor¬ 
ola)  to  develop  a  portable  DOS,  includ¬ 
ing  ROM  BIOS  and  video  RAM,  all  writ-  j 
ten  in  C.  The  DOS  would  be  , 
compatible  with  Microsoft’s  DOS  5.0 
as  well  as  existing  DOS  versions. 

In  the  August  Flames  I  wrote  of  my 
cousin  Corbett's  proposal  that  all  PRO¬ 
LOG  programmers  adopt  a  uniform  j 
commenting  style  so  that  some  future  j 
compiler  directive  could  turn  the 
comments  into  references  to  a  univer¬ 
sal  dictionary  of  PROLOG-style  facts, 
the  notion  being  that  the  comprehen¬ 
sion  of  comments  would  rely  on  hu¬ 
man  intelligence  only  until  some¬ 
thing  better  comes  along.  This  : 
prompted  Stan  Kelly-Bootle,  author  of 
the  wonderful  Devil's  DP  Dictionary, 
to  remind  me  that  he  presented  a  re-  j 
lated  idea  in  his  Devil’s  Advocate  col¬ 
umn  in  February’s  f  7uy  Review.  \ 
Stan's  yacc  (yet  another  comment  j 
compiler)  would  be  a  great  boon  in  j 
converting  programs  written  in  some 
soon-to-be-obsolete  language  like,  say,  j 
C.  to  powerful  AI  code.  It  would  ig¬ 
nore  code  and  interpret  comments,  ! 
turning  the  pedestrian 

+  +a  /*  increment  count  by  1  ”/ 

into  the  soaring 

I 

increment  count  by  1  /*  +  +a  */ 

with  all  the  obvious  resultant 
benefits. 

As  Humptv  Dumpty  said,  there's 
glory  for  you. 

Michael  Kwaine 
editor-in-chief 
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GRAPHICS:  Sew  Issues  in  PG  Graphics 

by  Ed  McNiemev 

Two  new  graphics  chips,  the  Intel  82786  and  the  I  I  34010, 
provides  graphics  power  and  complexity  previously 
unknown  in  PC  graphics.  They  also  represent  two 
strikingly  different  approaches  to  implementing  graphics 
on  a  chip. 

GRAPHICS:  A  Mandelbrot  Program  lor  the  Macintosh 

by  Howard  Katz 

The  curious  new  mathematical  abject  the  Mandelbrot  set  is 
so  popular  it  has  its  own  journal.  In  implementing  this 
elegant  assembly-language  application  the  author 
bypassed  the  Macintosh  SANE  floating-point  package  and 
used  fixed-point  ROM  routines  for  greater  speed. 
GRAPHICS:  A  Digital  Dissolve  for  Bit-Mapped 
Graphics  Screens 
by  Mike  Morton 

On  the  way  to  constructing  a  satisfying  visual  effect  the 
author  reveals  a  few  tricks  for  rapidly  generating 
pseudorandom  sequences  and  three  different  dissolve 
algorithms.  He  also  suggests  how  to  implement  the 
algorithms  efficiently  in  various  environments. 


Macintosh  ► 


68000  ^ 
graphics 


About  the  Cover 

Nick  Turner  generated  the  color 
pixels  on  a  plain  old  Apple  11;  Mi¬ 
chael  Hollister  and  photographer 
Michael  Carr  transferred  them  to 
the  glistening  surface  of  a  half- 
pound  of  liquid  mercury  to  si¬ 
multaneously  symbolize  and 
achieve  the  blending  of  technolo¬ 
gy  and  art. 


COLUMNS 


Hints  for  ► 
beginners 


C  CHEST:  Sets*  and  Microsoft  C  Version  4.0 

by  Allen  Holub 

Allen  implements  sets  in  C  and  discusses  Version  4  of 
Microsoft's  C  compiler  and  the  CodeView  debugger.  This 
column  also  marks  the  debut  of  Flotsam  and  Jetsam,  a 
series  of  hints  for  both  experienced  and  novice  C 
programmers. 

STRUCTURED  PROGRAMMING:  Error  Handling  in 
Ada  and  Modula-2,  ft*arge  Turbo  Pascal  Matrices 

bv  Namir  Clement  Shammas 

Namir  shows  some  wavs  to  trap  errors  in  Ada  and  Modula- 
2  and  examines  a  product  that  lets  Turbo  Pascal 
programmers  madly  matriculate,  creating  large  sparse 
matrices,  virtual  matrices,  and  expanded- memory 
matrices. 


Tliis  Issue 

The  release  of  the  Apple  HGS  this 
fall  isee  Nick’s  brief  report  in 
Running  Light,  page  8>  is  spark¬ 
ing  consumer  interest  in  comput¬ 
er  graphics,  but  to  programmers 
the  arrival  of  graphics  chips  that 
can  provide  up  to  10, 000-fold 
speed  increases  may  be  even 
more  intriguing.  Our  lead  article 
shows  how  to  use  the  new  chips 
from  Intel  and  T1  in  your  pro¬ 
grams.  We  also  present  a  digital 
dissolve  routine  that  selects  the 
most  appropriate  from  among 
three  algorithms,  and  a  clever 
Macintosh  graphics  application 
in  68000  assembly  language. 


Ada,  Modula-2,  ► 
and  Pascal 


PROGRAMMER'S 


FORUM 


SERVICES 


Next  Issue 

December  is  Operating  Systems 
month  at  OW.  The  new  80386- 
based  computers  have  got  us  in¬ 
trigued  with  multitasking,  and 
next  month  we  ll  publish  the 
task  scheduler  component  of  a 
multitasking  operating  system 
for  PC-class  machines. 
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Editorial 

Editor-in-chief  Michael  Swaine 
Editor  Nick  Turner 
Managing  Editor  Vince  leone 


Jim  Anderson,  the 
president  of  Digi- 
talk,  wrote  to  say  that 
the  classification  sys¬ 
tem  of  his  Smalltalk/V 
solves  a  problem  posed 
in  my  Swaine  s  Flames 
column  in  August.  Spe¬ 
cifically,  he  says,  it  al¬ 
lows  the  programmer 
to  handle  physical 
units  such  as  tempera¬ 
ture  and  humidity  realistically.  He’s 
right,  but  the  scheme  I  was  passing 
along  in  that  column,  and  it’s  not  a 
new  idea,  was  to  build  into  a  compiler 
the  constraints  and  checks  that  peo¬ 
ple  working  with  physical  quantities 
have  to  deal  with.  Things  such  as  not 
being  able  to  add  apples  and  oranges, 
having  feet  times  feet  yield  square 
feet,  and  having  the  units  in  a  com¬ 
plex  calculation  multiply  and  divide 
and  cancel  out  independently  of  (or  in 
parallel  with?)  the  quantities. 

Built  into  the  compiler,  such  fea¬ 
tures  would  constrain  the  program¬ 
mer  even  more  than  the  strong  data 
typing  of  Modula-2.  Laid  on  top  of 
data-type  constraints  would  be  con¬ 
straints  that  allowed  multiplying  two 
quantities  but  not  adding  them,  and 
perhaps  automatic  rescaling  that 
would  take  some  control  of  numeric 
precision  out  of  the  programmer’s 
hands.  Why  consider  such  con¬ 
straints?  The  benefits  would  seem  to 
te  increased  programmer  productivi¬ 
ty  and  increased  program  maintain¬ 
ability.  The  costs  would  be  in  general¬ 
ity  and  programmer  control.  These 
sound  like  the  trade-offs  of  fourth- 
generation-language  design. 

Most  4GLs  are  specialized  lan-  j 
guages,  appropriate  in  only  a  limited  j 
domain.  They  at  least  discourage,  if 
not  prohibit,  low-level  access  to  ma-  j 
chines.  They  are  designed  to  produce  ! 
easily  maintained  code  quickly. 

If  we  believe  Prentice-Hall's  human 
book  machine,  James  Martin,  most 
4GLs  are  remarkably  unknown 
among  those  who  know  the  most 


about  programming. 
Martin  recently  polled 
"experts  on  program¬ 
ming  languages”  (in¬ 
cluding,  1  assume,  pro¬ 
fessional  software 
developers)  and  found 
few  who  even  recog¬ 
nized  the  names  of  the 
most  powerful  fourth- 
generation  languages. 
Why? 

If  fourth-generation  languages  are 
perceived  as  being  bad  languages  in 
some  sense — if,  for  example,  they  are 
seen  as  imposing  too  great  a  perfor¬ 
mance  cost — maybe  that  explains 
their  being  ignored.  Unfortunately, 
their  being  ignored  means  in  turn  that 
if  the  perception  is  wrong  it  will  get 
corrected  only  slowly  and  if  it  is  right 
the  4GLs'  problems  will  get  corrected 
slowly,  because  they  won’t  benefit 
from  the  useful  feedback  of  those  ex¬ 
perts  who  understand  their  faults. 

There  are  signs  that  fourth-genera¬ 
tion  languages  may  have  been  chang¬ 
ing  while  unobserved  and  may  de¬ 
serve  another  look.  Fourth- 
generation  languages  are  no  longer 
restricted  to  mainframes  and  mini¬ 
computers.  Vendors  of  fourth-gener¬ 
ation  languages  for  micros  acknowl¬ 
edge  some  performance  limitations 
of  past  4GLs  but  claim  that  today's 
products  produce  fast,  efficient  code. 
They  claim  that  any  perception  that 
fourth-generation  languages  are  un¬ 
worthy  of  the  attention  of  serious 
software  developers,  if  it  was  ever 
correct,  is  no  longer. 

Perhaps  we  should  all  take  a  look  at 
this  claim  and  at  modern  fourth-gen¬ 
eration  languages.  At  the  very  least, 
we  should  recognize  that  4GLs  need 
not  be  just  elaborated  database 
managers. 

Michael  Swaine 
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DDJ  Looks  at  (hi;  IBM  PC 

“On  August  12,  IBM  announced  the  IBM 
Personal  Computer,  a  small  home  ma¬ 
chine,  It  will  he  sold  , . .  through  C.'ompu- 
terland  stores  and  Sears  Business  Machines 
outlets. 

"The  prices  quoted  for  the  machine 

ranges  from  S1B00  for  a  16K  starter  system 
up  to  $6300  for  a  machine  with  two  disks 
and  256K  of  storage  . .  we're  exited  about 
this  announcement.  IBM's  presence  in  the 
market  will  intensify  competition;  the 
standards  of  support  and  documentaion 
will  go  up  and  the  prices  will  go  down  as 
the  other  makers  prepare  to  meet  the  chal¬ 
lenge." — DaveGortesi,  dm,  October  13X1. 

"We've  had  our  hands  on  an  IBM  Person¬ 
al  Computer  for  a  few  days  now.  It’s  just  a 
computer,  after  all."— Dave  Cortesi,  001, 
June  1982. 

CP/M-80  was  a  sturdy  little  tyke,  but  by 
no  means  was  it  a  complete  operating  sys¬ 
tem.  After  examining  these  descendants  of 
CP/M-80,  my  strongest  feeling  is  one  of  dis¬ 
appointment.  It  disappoints  rne  that  two 
high-powered  software  houses  have 
worked  so  hard  to  produce  only  . ,  two 
more  CP/Ms.  —CP/M  vs.  MSDOS;  A  Technical 
Comparison,  Dave  Cortesi,  BOS,  July,  1982. 


A  pple’s  new  IIGS,  H m 

pit;  II  system,  has  just  Bfgfes 

boon  introduced.  The  IlL 

first  batch  of  these 
platinum-cased  bean-  S&g"’;  >>0 

ties,  with  their  65816 
processors  and  256K  PT 
memories,  have  even  j*\  \  \ 

been  signed  by  Steve  t  \  \ 
Wozniak  himself.  "GS”  Y\ 

stands  for  graphics  I.I..  \\ _ 

and  sound,  and  the  IIGS  lives  up  to  the 
title  grandly.  It's  got  everything  I've 
ever  wanted  from  a  H-series  comput¬ 
er  and  much,  much  more.  It's  about 
time  Apple  did  something  to  really 
spark  the  II  line.  Now  the  ball  is  in  our 
court;  we  re  the  software  designers, 
and  it's  our  efforts  that  will  directly 
influence  the  success  or  failure  of 
this  new  machine. 


V.  me  at  (415)  366-3600  if 

you  have  any  ideas. 

|  In  June  we’ll  be 

f;  looking  at  telecommu- 

,  ;  .  !  nications.  A  lot  has 

Pi  haPPenecl  since  our 

last  telecom  issue.  If 
/  -fig  you're  working  on 

r  ,  «  something  new  and  in- 

/t  «  teresting,  perhaps  you 
F  |  have  an  article  to  write 

1 _ JL »  for  us?  We  re  especial¬ 

ly  interested  in  material  about  high¬ 
speed  communications.  Is  there  any¬ 
body  who  would  like  to  write  about 
fiber  optics?  What  about  a  piece  on 
how  to  program  a  signal  processor 
CPU?  Anything  new  in  data  compres¬ 
sion  or  error  detection/correction? 
Call  me  with  ideas. 

Our  July  issue,  once  again,  will  be 
full  of  Forth.  We  encourage  all  you 
dedicated  and  persistent  Forthians  to 
take  part  as  you  have  in  the  past.  Re¬ 
cently  we’ve  been  able  to  increase 
our  coverage  of  Forth — Michael 
Ham’s  contributions  in  particular 
have  added  a  special  flavor  to  the 
magazine  (thank  you,  Mike!).  Let’s 
put  together  a  really  great  seventh 
annual  Forth  issue. 

August  will  be  our  C  issue,  and  Sep¬ 
tember  will  deal  with  algorithms. 
Were  also  thinking  about  covering 
fourth-generation  languages  in  Sep¬ 
tember.  What  do  you  think?  Should 
we  cover  them?  Would  you  like  to 
write  an  article? 

All  in  all,  1987  promises  to  be  a  ban¬ 
ner  year  for  DDJ.  We’re  consistently 
receiving  more  high-quality  article 
submissions  than  ever  before.  Your 
voices  are  being  heard,  both  in  the 
Letters  column  and  in  your  direct 
phone  calls  to  me.  Let’s  keep  improv¬ 
ing  together. 


DDJ  Looks  at  its  Readers 

"We  were  amazed  at  how  rapidly  many 
of  our  readers  have  aquired  IBM's  Personal 
Computer.  Equally  interesting  was  that  the 
68000  chip  has  a  greater  following  among 
our  readers  than  the  8606/8088,  although 
the  margin  is  not  overwhelming.  Among 
topics  eliciting  very  favorable  response' 
wereCP/M,  algorithms,  assembly  language, 
compilers  and  the  Z80/8080.  Pascal  and 
Sntall-C/C  were  among  the  languages  of 
evident  enthusiasm,  and  multi-user  sys¬ 
tems  are  becoming  worthy  of  more  editori¬ 
al  attention."  - Marlin  Ouverson,  MM,  Au¬ 
gust  1982. 


In  every  issue  of  DDJ,  toward  the 
middle  of  the  magazine,  there's  an  in¬ 
sert  with  some  tear-out  cards.  The  top 
two  cards  are  subscription  cards.  (You 
don't  have  a  subscription?  You  know 
what  to  do.)  The  third  card  is  very  spe¬ 
cial:  it’s  where  you  have  a  chance  to 
talk  directly  to  us.  Your  comments  on 
that  card  are  collected  every  month 
into  a  stack.  The  problem  is,  each 
month  the  stack  is  only  about  an  inch 
high.  We  would  love  to  see  that  stack 
grow  to  a  medium-size  mound,  or 
even  a  small  hill.  So  get  out  your  pen 
or  pencil  and  rip  out  that  little  card. 
We  want  to  know  what  you  think  of 
the  magazine,  and  we  promise  to  read 
all  the  cards. 


Ten  Years  Ago  in  DDJ 

DDJ  SEEKS  SUPER  LOGO:  Like  alt  massive  or¬ 
ganizations  intent  upon  changing  the  fabric 
of  society,  Or.  Dobb'sJournal  lias  concluded 
that  it  should  have  a  logo — a  symbol  by 
which  all  people  may  inslanly  recognize  us. 
It  might  lie  our  current  title  masthead., .hut 
that's  SO  iongwinded.  Ideally,  it  should  lie  a 
symlxil  or  figure  that  in  some  sense  illus¬ 
trates  our  activities  (now,  now — be  nice)." — 
DDJ,  November,.  December  1.976. 

"The  Polv-88  system — which  has  re¬ 
placed  my  Altair  8800  and  my  IMSAl  8080- 
lias  hut  two  controls  on  the  box.  An  on/off 
switch  with  a  power  indicator  light,  and  a 
reset  button  with  a  halt  light.  That's  all  you 
get;  that's  all  you  need.  U  surely  doesn’t 
look  impressive.  Sort  of  like  a  toaster 
•  •  •  " — Jef  Raskin ,  DDJ,  November /Decem¬ 
ber  1976. 


We  have  some  really  interesting 
themes  coming  up  in  future  issues. 
Our  May  issue,  for  example,  will  fo¬ 
cus  on  computer  music.  Who  makes 
the  best  computer  music?  What  ma¬ 
chines  are  the  most  musical?  Is  MIDI 
the  only  way  to  interface?  What's 
hottest  and  newest?  We’ve  never 
done  a  music  issue  before,  so  we  es¬ 
pecially  need  to  hear  from  authors 
and  experts  as  soon  as  possible.  Call 
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July  Forth 

Dear  DDJ, 

Thank  you  for  the  Forth  is¬ 
sue,  with  some  interesting 
and  thought-provoking  es¬ 
says.  I  was  even  more  grati¬ 
fied  by  the  promise  of 
more  to  come.  I  am  sure 
you  realize  the  vacuum  we 
of  the  Forth  community 
are  discovering  ourselves 
in.  The  language  is  far 
from  dead,  but  meaningful 
forums  appear  to  be  on  the 
endangered  list. 

Thank  you  for  Mike 
Ham's  column.  Mike  is  one 
of  the  truly  erudite  spokes¬ 
men  for  Forth.  It  is  a  plea¬ 
sure  to  see  he  has  a  plat¬ 
form  as  respected  as  DDJ 
from  which  to  share  his 
views. 

I  might  add  I  have  en¬ 
joyed  comments  from  both 
Mike  and  Ray  Duncan  on 
the  DDJ  Forum  on  Compu¬ 
Serve.  I  look  forward  to 
seeing  their  insight  on  fu¬ 
ture  pages  of  DDJ. 

Again,  thank  you. 

Gary  Smith 

P.O.  Drawer  7680 

Little  Rock,  AR  72217 

Dear  DDJ, 

The  first  sentence  of 
George  W.  Shaw  II’s  “Ex¬ 
tended  Control  Structures” 
(July  1986),  “The  control 
structures  in  the  Forth  83 
Standard  leave  something 
to  be  desired,”  is  an  opin¬ 
ion  that  I  stated  three  years 
ago  in  my  paper  refer¬ 
enced  by  Shaw.  Since  then 
I  have  realized  that  it  was 
not  the  control  structures 
that  left  something  to  be 


desired  but  my  knowledge 
of  how  to  use  them  to  write 
clear  and  understandable 
programs.  The  standard 
control  structures  are  just 
fine,  and  new  structures 
are  unnecessary. 

Shaw  is  making  the  same 
mistake  that  I  made  three 
years  ago.  Because  Forth 
does  not  have  all  the  con¬ 
trol  structures  that  other 
structured  languages  have, 
I  thought  something  was 
missing.  But  Forth  does  not 
need  other  control  struc¬ 
ture  words. 

Shaw's  examples  of  ex¬ 
tended  logical  structures 
are  all  instances  of  unsim¬ 
ple  logic.  He  acknowledges 
that  they  are  useful  only  10 
percent  of  the  time.  In 
Forth,  when  the  logic  be¬ 
comes  the  least  bit  compli¬ 
cated,  it  is  time  to  factor  the 
complication  out  and  give 


it  a  name  telling  what  it 
does  (but  not  how  it  does  it). 
This  is  also  a  good  idea  in 
other  languages.  If  this  is 
done  to  Shaw's  examples 
involving  BEGIN  and  IF,  his 
LEAVES  can  simply  become 
EXIT  THEN. 

In  traditional  Forth  sys¬ 
tems,  the  same  factoring 
cannot  be  done  with  exam¬ 
ples  involving  DO.  The  self- 
styled  Forth  83  Standard 
says  that  EXIT  "may  not  be 
used  within  a  DO  loop.” 
Rather  than  introduce 
new,  novel,  little-used,  and 
hard-to-teach  logic  struc¬ 
tures,  let’s  stick  to  the  struc¬ 
tures  that  are  already  pro¬ 
vided  but  remove  the 
above-mentioned  clause 
and  allow  EXIT  to  be  used 
anywhere  in  a  definition. 
This  is  easy  to  imple¬ 
ment — either  check  com¬ 
piler  security  or  increment 


a  counter  for  each  DO,  dec¬ 
rement  it  for  each  LOOP  or 
+LOOP,  and  make  EXIT 
smart  enough  to  know 
how  many  loops  to  undo.  It 
will  also  remove  a  restric¬ 
tion  in  the  language  and 
make  Forth  easier  to  learn 
and  use.  The  awkwardness 
that  Shaw  ascribes  to  han¬ 
dling  his  tithe  of  logic  dis¬ 
appears  by  removing  nar¬ 
row  restrictions  imposed 
on  existing  words,  not  on 
defining  new  words. 

Without  giving  any  justi¬ 
fication,  Shaw  asserts  that 
the  new  Forth  83  DO  loop  is 
better  than  the  Forth  79  DO 
loop.  There  are  many  who 
disagree.  I  do  agree  that  the 
immediate  LEAVE  is  bet¬ 
ter — it  makes  it  convenient 
to  observe  the  restrictions 
of  structured  program¬ 
ming.  I  also  agree  that 
LEAVE  should  work  with 
BEGIN  as  well  as  with  DO. 
But  Shaw's  argument  that 
LEAVE  is  always  followed 
by  THEN  and  so  should 
have  a  variation  that  im¬ 
plies  THEN  also  applies  to 
EXIT,  QUIT,  and  ABORT. 
Rather  than  select  one, 
some,  or  all  of  them  for  spe¬ 
cial  consideration,  leave 
well  enough  alone.  The  in¬ 
variable  THEN  aids  the 
reader  to  see  the  overall 
logical  structure  in  a 
definition. 

The  natural  meaning  of 
LEAVES,  found  in  some 
Forths,  is  that  2  LEAVES  es¬ 
capes  two  loops,  3  LEAVES 
escapes  three  loops,  and  so 
on. 

Shaw's  scheme  for  ex¬ 
tending  IF  is  intended  to  be 
general,  but  it  does  not  al¬ 
low  nesting. 

Wil  Baden 

339  Princeton  Dr. 

Costa  Mesa,  CA  92626 

Software  Taxation 

Dear  DDJ, 

I  read  with  interest  the  edi- 
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torial  and  the  lead  letter  in 
the  July  1986  DDJ.  The  for¬ 
mer  complains  that  soft¬ 
ware  is  not  enough  of  a 
"thing”  that  its  sale  should 
be  subject  to  sales  tax.  The 
latter  observes  that  soft¬ 
ware  is  enough  of  a  thing 
that  we  can  talk  of  the 
rights  of  ownership  in  it. 

A  software  author's  pri¬ 
mary  concern  should  be 
that  the  state  recognize  and 
protect  his  relationship  to 
the  thing  he  has  created.  To 
the  extent  that  a  state  pro¬ 
tects  this  relationship,  the 
author  has  a  "property”  in¬ 
terest.  If  the  author  trans¬ 
fers  all  or  part  of  that  right 
to  another  person,  he  has 
transferred  a  thing,  albeit 
an  intangible  one.  Once  the 
state  recognizes  the  exis¬ 
tence  of  a  thing  and  defines 
the  rights  that  a  person  has 
in  that  thing,  assorted  laws 
can  come  into  play.  The 
state  may  invoke  its  crimi¬ 
nal  laws  to  protect  the  own¬ 
er  from  wrongful  depriva¬ 
tion  of  the  right  to  use  and 
enjoy  the  software.  The 
owner  may  invoke  conver¬ 
sion,  trespass,  or  a  host  of 
other  civil  actions  to  recov¬ 
er  exclusive  use  and  enjoy¬ 
ment  or  to  force  the  wrong¬ 
doer  to  pay  for  his  deed. 
The  alternative  is  to  hold 
that  property  rights  do  not 
attach  to  software.  If  the 
state  will  not  protect  any 
person's  relationship  to  a 
given  piece  of  software,  it 
may  be  freely  "trans¬ 
ferred”  in  voluntary  and  in¬ 
voluntary  (unilateral) 
transactions. 

Once  we  determine  that 
property  has  been  trans¬ 
ferred  in  a  commercial 
transaction,  the  decision  to 
apply  or  not  to  apply  a  state 
sales  tax  becomes  a  policy 
decision.  Perhaps  there  are 
reasons  that  the  states 
should  not  tax  commercial 
transactions  in  software.  I 


find  the  blatant  assertion 
that  it  is  "grossly  unfair”  to 
be  unconvincing.  It  is  not 
immediately  evident  that  a 
sales  tax  on  software  is 
more  or  less  invidious  that 
the  same  tax  on  file  cabinets 
or  electricity. 

My  own  crusade  is  to 
persuade  legislatures  and 
courts  that  laws  should  be 
written  and  interpreted  to 
break  away  from  the  eigh¬ 
teenth-century  notion  that 
the  law  protects  only  tangi¬ 
ble  things.  For  that  reason  I 
applaud  laws  and  regula¬ 
tions  that  treat  software  as 
a  thing  in  which  individ¬ 
uals  can  have  property 
rights.  Those  of  us  who  cre¬ 
ate  and  use  software  stand 
to  gain  much  more  than 
we  lose. 

Simon  B.  Buckner 

1605-D  Jefferson  Heights 

Jefferson  City,  MO  65101 

The  Last  Square 
Root  Letter? 

Dear  DDJ, 

The  July  1986  Letters  col¬ 
umn  contained  a  letter  by 
Dorothy  Wolfe  that  con¬ 
cerns  my  "Square  Roots  on 
the  NS32000”  article  pub¬ 
lished  in  The  Right  to  As¬ 
semble,  March  1986.  Wolfe 
has  a  criticism  to  which  I 
would  like  to  respond. 

Wolfe  points  out  that,  ac¬ 
cording  to  my  definition  of 
the  (integer)  square  root  as 
the  smallest  of  two  nearly 
equal  factors,  "the  square 
root  of  17  (or  of  any  prime 
number)  would  be  1.”  The 
following  should  apply  to 
any  prime  number;  I  will 
use  the  example  of  17. 

The  problem  seems  to  in¬ 
volve  the  meaning  of  the 
word  integer.  In  the  con¬ 
text  of  integer  arithmetic, 
the  term  integer  implies  a 
number  that  may  have  a 
nonzero  decimal  compo¬ 
nent,  but  the  decimal  com¬ 
ponent  is  not  represent¬ 
ed — that  is,  17  divided  by  4 
equals  4.  In  the  context  of 
prime  numbers,  the  term 


integer  implies  a  number 
that  has  a  zero  decimal 
component  that  is  repre¬ 
sented.  In  this  context 
Wolfe's  comment  is  valid. 
The  only  integer  factors  of 
17  are  1  and  17 — that  is,  17 
divided  by  4  equals  4.25. 

However,  there  are 
many  factors  of  17 — 1  and 
17,  2  and  8.5,  3  and 

5.666  .  .  .  ,  4  and  4.25,  5  and 
3.4,  6  and  2.833  . .  .  ,  for  ex¬ 
ample.  The  two  "most 
nearly  equal  factors" 
above  are  4  and  4.25,  of 
which  4  is  the  smallest  and 
is  therefore  the  integer 
square  root  of  17.  The  "ex¬ 
act”  square  root  of  17  is 
4.12310  .  .  . — this  is,  of 
course,  another  factor. 

Richard  A.  Campbell 

198  Washington  Hwy. 

Snyder,  NY  14226 

Update 

Dear  DDJ, 

Let  me  compliment  you  on 
your  commitment  to  pro¬ 
viding  in-depth  coverage 
of  MS-DOS  C  compilers.  I  ea¬ 
gerly  awaited  this  year’s 
August  offering  and  read  it 
with  great  interest  and  in 
great  detail. 

I  discovered  that  "Bench¬ 
marking  C  Compilers”  by 
Richard  Relph  et  al.  unfor¬ 
tunately  provided  uneven 
coverage  of  the  important 
issues  and  omitted  infor¬ 
mation  about  many  of  the 
advanced  features  of  Mark 
Williams  Co.’s  C  compiler 
products. 

A  few  of  the  product  fea¬ 
tures  omitted  from  the  dis¬ 
cussion  of  MWC's  C  Pro¬ 
gramming  System  were: 

1.  Full  support  for  recent 
extensions  to  C,  including 
void,  enum,  and  structure 
rule  extensions. 

2.  A  powerful  make  utility 
and  a  Unix-style  cc  com¬ 
mand  that  provides  one- 
step  compiling  and  linking 
and  accepts  wildcards. 

3.  An  automated  install 
procedure  that  provides 


unparalleled  ease  of  instal¬ 
lation. 

4.  An  environment  vari¬ 
able  that  provides  full 
search  path  capabilities. 

5.  An  assembler,  linker, 
and  archiver,  all  included 
at  no  extra  charge. 

6.  A  set  of  advanced,  Unix- 
style  file  utilities,  including 
diff,  egrep,  cmp,  sort,  tail, 
pr,  and  many  others. 

Mark  Williams  Co.  pro¬ 
vides  cross  compilers,  C 
compilers,  and  operating 
systems  to  many  of  the 
largest  computer  manufac¬ 
turers  for  8086,  68000, 
Z8000,  Z80,  VAX,  and  other 
types  of  hardware. 

Barry  D.  Bowen 
Mark  Williams  Co. 

1430  W.  Wrightwood 
Chicago,  IL  60614 

We  will  publish  updates 
about  the  C  compilers  we 
have  reviewed  as  often  as  is 
necessary.  The  DDJ  Elec¬ 
tronic  Edition  on  Compu¬ 
Serve  will  contain  even 
more  information  about 
these  products. — eds. 

Correction 

Dear  DDJ, 

Ray  Duncan’s  July  1986  16- 
Bit  Software  Toolbox  con¬ 
tains  a  statement  that  Com¬ 
puter  Innovations'  Version 
1.31  C  compiler  is  now  in 
the  public  domain.  This  is 
incorrect.  As  I’m  sure  you 
realize,  the  ramifications  of 
announcing  free  software 
to  the  public,  when  in  truth 
it  is  not,  only  adds  to  the 
problem  of  preventing  soft¬ 
ware  piracy.  It  also  is  quite 
distracting  for  us  because 
readers  have  been  calling 
and  asking  for  copies. 

I  appreciate  your  coop¬ 
eration  in  this  matter. 

Keith  Wimberley 
Computer  Innovations 
Inc. 

980  Shrewsbury  Ave. 
Tinton  Falls,  NJ  07724 
(201)  542-5920 

DDJ 
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Sets  in  C 

've  been  writing  a  book  on  com¬ 
piler  design  of  late.  Unlike  most 
such  books,  this  one  is  going  to  in¬ 
clude  a  lot  of  code.  It  will  explain 
how  various  algorithms  work  by  pre¬ 
senting  real  code  to  implement  those 
algorithms.  Not  wanting  to  secrete  all 
this  useful  stuff  until  the  book  is  final¬ 
ly  published,  I'm  going  to  publish  an 
occasional  excerpt  from  time  to  time, 
starting  this  month. 

Many  of  the  operations  involved  in 
compiler  writing,  such  as  creating 
state-machine  tables  from  regular  ex¬ 
pressions,  involve  operations  on  sets, 
and  C,  unlike  Pascal,  doesn’t  have  a 
built-in  set  capability.  Fortunately,  it’s 
not  too  hard  to  implement  sets  in  C  by 
means  of  bit  maps — as  several  people 
pointed  out  to  me  when  bit-map  rou¬ 
tines  were  first  published  in  this  col¬ 
umn  (DDJ,  June  1985).  In  fact,  the  Pas¬ 
cal  implementations  I've  seen  actually 
use  bit  maps  to  implement  their  sets. 
The  bit-map  routines  that  were  print¬ 
ed  last  year  aren’t  quite  general-pur¬ 
pose  enough  for  real  set  applications, 
so  I've  expanded  them  into  the  rou¬ 
tines  presented  this  month. 

To  use  the  set  routines,  you  have  to 
# include  set.h  (Listing  One,  page  58)  at 
the  head  of  your  program.  Most  of  the 
set  functions  are  macros  that  evaluate 
to  workhorse-function  calls.  The  mac¬ 
ros  and  subroutines  are  shown  in  Ta¬ 
bles  1  and  2,  page  20. 

All  the  elements  in  the  set  must 
have  numeric  values,  though  in  many 
instances  any  arbitrary  number  will 
do.  Enumerated  types  are  almost  ide- 

by  Allen  Holub 


al  for  this  purpose,  though  ^defines 
can  be  used  too.  For  example: 

typedef  enum 

{ 

JAN,  FEB,  MAR, 

APR,  MAY,  JUN, 

JUL,  AUG,  SEP, 


OCT,  NOV,  DEC 

} 

MONTHS; 

creates  12  potential  elements  of  a  set. 
You  can  now  create  two  sets  called 
winter  and  spring  by  using  the  set  op¬ 
erations: 

^include  <set.h> 

SET  “winter,  “spring; 

winter  =  newsetl ); 
spring  =  newsetl ); 

add(  JAN,  winter  ); 
add(  FEB,  winter ); 
add(  MAR,  winter ); 
add(  APR,  spring ); 
add(  MAY,  spring ); 
add(  JUN,  spring  ); 

Set  operations  can  now  be  performed 
using  the  other  macros  in  set.h.  For 
example,  disjoint ( winter,  spring )  eval¬ 
uates  to  true  because  the  sets  have  no 
elements  in  common;  equivalent ( win¬ 
ter,  spring)  evaluates  to  false  for  the 
same  reason.  A  third  set  that  contains 
the  union  of  spring  and  winter  can  be 
created  with: 

half-year  =  newsetl ); 

union!  half-year,  winter,  spring  ); 

Intersection (  half-year,  winter, 
spring);  creates  a  null  set  because 
there  are  no  common  elements.  The 
test (  )  and  main (  )  routines  in  set.c 
(lines  261  —  332  of  Listing  Two,  page 
62)  contain  additional  examples. 

Complemented  sets  present  a  par¬ 
ticular  problem.  You'll  notice  that  the 


eventual  size  of  the  set  doesn’t  have 
to  be  known  when  the  set  is  created. 
The  set  size  is  just  expanded  as  ele¬ 
ments  are  added  to  it.  This  can  cause 
problems  when  you  complement  a 
set  because  the  complemented  set 
should  contain  all  possible  elements 
except  those  that  are  in  the  equiva¬ 
lent,  uncomplemented  set.  For  exam¬ 
ple,  if  you’re  working  with  a  "lan¬ 
guage”  that’s  composed  of  the  set  of 
symbols  (A,  B,  C,  D,  E,  F,  G}  and  you 
create  a  second  set  {A,C,E,G}  from  ele¬ 
ments  of  the  language,  the  comple¬ 
ment  of  this  second  set  should  be 
(B,D,F).  That  is,  the  complement 
should  be  all  the  symbols  in  the  lan¬ 
guage  except  those  that  are  in  the 
original,  uncomplemented,  set. 

All  sets  are  represented  as  bit 
maps,  and  these  maps  are  of  finite 
size.  Moreover,  the  actual  size  of  the 
map  grows  as  elements  are  added  to 
the  set.  You  can  complement  a  set  by 
inverting  the  sense  of  all  the  bits  in 
the  bit  map,  but  now  you  can’t  ex¬ 
pand  the  set’s  size  dynamically  any 
more  (at  least  not  without  a  lot  of 
work).  To  guarantee  that  a  comple¬ 
mented  set  contains  all  the  potential 
elements,  you  have  to  first  expand 
the  set  size  by  adding  an  element 
that’s  one  larger  than  any  possible  le¬ 
gitimate  element  and  then  comple¬ 
ment  the  expanded  set.  A  second 
problem  has  to  do  with  extra  ele¬ 
ments.  The  bit-map  size  will  usually 
be  a  little  larger  than  the  number  of 
potential  elements  in  the  set.  If  you 
just  complement  bits,  you  will  effec¬ 
tively  add  members  to  the  set.  On  the 
plus  side,  set  operations  (union,  inter¬ 
section,  and  so  on)  are  much  easier  if 
you  physically  complement  the  bits 
in  a  map. 

An  alternate  method  of  comple¬ 
menting  the  set  is  to  have  negative- 
true  sets  and  positive-true  sets.  Here 
you  can  just  mark  a  set  as  negative  or 
positive  by  setting  a  bit  in  a  header. 
You  don’t  have  to  modify  the  bit  map 
at  all.  When  you  test  for  member- 
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ship,  if  a  set  is  marked  negative-true, 
you  can  just  reverse  the  sense  of  the 
test  (evaluate  to  true  if  the  requested 
bit  is  not  set).  Though  this  takes  care 
of  all  the  size  problems,  operations 
on  negative-true  sets  are  much  hard¬ 
er  to  perform. 

Because  the  two  representations 
are  both  useful  but  in  different  appli¬ 
cations,  I  decided  to  implement  both 
methods.  The  invert(d,sl)  macro  per¬ 
forms  a  one's-complement  on  all  bits 


currently  in  the  set's  bit  map.  Note 
that  if  new  elements  are  added,  the 
new  bits  won’t  be  complemented. 
You  should  always  expand  a  set  out 
to  the  maximum  number  of  elements 
(by  adding  and  then  removing  the 
largest  element)  before  inverting  it. 
The  complement(d)  macro  imple¬ 
ments  the  second  method  discussed 
earlier.  It  doesn't  modify  the  bit  map 
at  all;  rather  it  sets  a  bit  in  a  header  to 
mark  a  set  as  negative-true. 

Because  there  are  two  different 
classes  of  sets  (those  that  are  comple¬ 
mented  and  those  that  are  inverted), 


there  are  also  two  different  macros 
for  testing  membership.  Ismem- 
ber(y,s)  evaluates  to  1  only  if  the  bit 
corresponding  to  the  requested  ele¬ 
ment  is  actually  set  to  1.  Ismem- 
ber(y,s)  can't  be  used  reliably  on 
complemented  sets.  The  test(/c,s) 
macro  can  be  used  with  comple¬ 
mented  sets.  If  a  set  is  complemented, 
the  sense  of  the  individual  bits  is  re¬ 
versed  as  part  of  the  testing  process. 
If  the  set  isn't  complemented,  test(  ) 
works  just  like  ismember(  )  does 
(though  it's  a  little  larger  and  takes  a 
little  longer  to  evaluate). 

Note  that  the  various  set  operations 
(union,  intersection,  and  so  on)  are  val¬ 
id  only  on  inverted  sets.  The  set—op(  ) 
routine  ignores  the  complement  bit 
in  the  SET  header,  treating  all  oper¬ 
ands  as  if  they  were  positive-true 
sets.  Use  invertf )  if  you're  going  to 
perform  subsequent  operations  on 
the  inverted  set. 

Implementation 

Sets  are  represented  as  SET  struc¬ 
tures,  defined  on  lines  9—17  of  List¬ 
ing  One  as: 

typedef  struct 

{ 

unsigned 

unsigned 

int 

unsigned  char 

unsigned  char 

} 

SET; 

The  set  itself  is  represented  as  a  bit 
map,  pointed  to  by  the  map  field  of 
the  structure.  Initially  map  points  at 
the  defmap  array.  If  more  elements 
are  added  to  the  set  than  can  fit  into 
defmap,  a  larger  bit  map  is  allocated 
automatically  and  map  is  made  to 
point  at  the  larger  bit  map.  This  way 
you  don’t  have  to  worry  in  advance 
about  the  maximum  size  of  a  set.  The 
bit-map  size  is  automatically  in¬ 
creased  as  the  set  grows  larger.  The 
bit  map  is  not  made  smaller  if  ele¬ 
ments  are  removed,  however. 
Nbytes  and  nbits  keep  track  of  the 
number  of  bits  and  bytes  in  the  map. 
Nbits  is  always  nbytes  *  8.  The  compl 
field  is  used  to  mark  a  set  as  negative- 
true  (it’s  1  for  negative- true  sets,  0  for 
positive-true  sets). 

The  add,  remove,  ismember,  and 
test  macros  all  access  the  bit  map  di- 


nbytes  :  13 ; 
compl  :  1 ; 
nbits; 

"map; 

defmaptDEFBYTES]; 
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rectly.  They  are  all  passed  a  bit  num¬ 
ber  and  a  pointer  to  a  SET.  Most  of  the 
work  is  done  in  the  GBIT  macro  (on 
line  46),  which  is  passed  a  set  pointer, 
bit  number,  and  an  operator.  The 
((s)—>map)[(ic)  >>  3]  part  of  the 
macro  selects  the  proper  byte  of  the 
bit  map.  The  right  shift  is  a  divide-by- 
eight.  Note  that  the  right  shift  would 
have  caused  problems  if  I  hadn't  de¬ 
fined  the  bit  map  as  unsigned  char. 
There  would  have  been  sign  exten¬ 
sion  if  the  high  bit  happened  to  be  set. 
The  second  part  of  the  macro,  1  << 
(Oc)  &  0^07),  creates  a  mask  that  cor¬ 
responds  to  the  requested  bit  by  shift¬ 
ing  the  number  1  x  %  8  bits  to  the  left 
by  (the  MOD  is  done  with  a  bitwise 
AND  operation  here).  Note  that  it's  the 


Table  1  :  Set  subroutines 


number  1  that's  being  shifted,  not  the 
contents  of  the  bit  map.  The  actual 
operation  is  then  performed  by  ap¬ 
plying  a  specific  operator  to  the 
mask.  If  the  operator  is  /  =,  a  bit  is  set 
in  the  map.  If  the  operator  is  &,  a  bit  is 
tested  for  true.  If  the  two  operators 
&=  and  ~  are  passed,  then  a  bit  is 
cleared. 

The  three  macros  that  use  GBIT  test 
to  see  if  a  bit  is  legal  (if  the  bit  number 
is  too  large,  0  is  returned).  If  the  num¬ 
ber  is  in  range,  they  invoke  the  GBIT 
macro,  passing  it  the  correct  opera¬ 
tor.  Add  is  an  exception.  If  the  re¬ 
quested  bit  number  is  too  large,  it 
evaluates  to  a  call  to  the  subroutine 
addseti ),  which  increases  the  size  of 
the  set  and  then  invokes  the  GBIT 
macro  to  set  the  proper  bit  in  the 
newly  expanded  bit  map  (addset  is 
on  lines  84—94  of  Listing  Two).  Note 


that  test  just  evaluates  to  an  ismember 
invocation,  inverting  or  not  inverting 
the  result  depending  on  whether 
(s)—  >compI  is  true.  Also  note  that 
had  I  said: 

(s) —  >compl  ?  !  ismember(x,s) 

:  ismember(x,s) 

the  macro  would  expand  to  almost 
twice  as  much  code  as  it  does  in  its 
current  form. 

The  assignment  operations  all  eval¬ 
uate  to  set^opf )  calls,  and  the  test  op¬ 
erations  all  evaluate  to  set—cmp( ) 
calls.  Set^opf  )  is  on  lines  181—229  of 
Listing  Two.  It  goes  through  the  bit 
map,  one  byte  at  a  time,  performing 
various  bitwise  operations  as  needed. 
A  bitwise  AND  does  an  intersection 
operation,  OR  does  a  union,  and  so 
on.  Note  that  symmetric  difference  is 
an  exclusive-OR  (y  is  an  element  of 
sett  and  is  not  an  element  of  setZ ). 
Set—op( )  normalizes  the  set  sizes  be¬ 
fore  the  operations  are  performed. 
That  is,  all  three  sets  will  be  made  as 
large  as  the  largest  of  the  three.  This 
normalization  can  cause  problems  if 
you  use  the  invert  operation  because 
invert  just  reverses  the  sense  of  all 
bits  in  the  map.  This  means  that  ele¬ 
ments  are  effectively  added  to  the  set 
if  its  size  has  been  increased  and 
these  elements  will  all  have  a  zero 
value. 

The  set—cmp(  )  routine  (Listing 
Two,  lines  121  —  152)  is  a  little  trickier 
than  set-op( ).  It  also  normalizes  the 
set  sizes  and  goes  through  the  bit 
maps  one  byte  at  a  time.  If  the  while 
loop  on  line  140  terminates  with  disj 
still  set  to  0,  then  the  sets  are  exactly 
equivalent  (the  test  on  line  142  will 
fail  for  all  bytes  in  the  map).  The  ex- 
clusive-OR  operation  on  line  144  is  be¬ 
ing  used  as  a  bitwise  not-equals  oper¬ 
ator.  The  test  evaluates  to  0  only  if  no 
two  bits  in  the  same  position  in  both 
bytes  are  set. 

The  Microsoft  C  Compiler, 
Version  4.0 

First  the  good  news.  I’ve  finally  re¬ 
ceived  my  copy  of  Microsoft  C,  Ver¬ 
sion  4.0,  and  am  quite  pleased  with  it. 
It's  a  significantly  better  product 
than  is  Version  3.0;  in  fact,  all  the 
problems  I  had  with  Version  3.0  have 
been  addressed  in  4.0.  All  the  bugs 
that  I  know  about  (including  ones 
that  various  readers  mentioned  to 


void 

SET 

delset  (s) 

*S; 

Deletes  a  set  created  with  a  previous  newsetf) 
command. 

SET 

’newset  ( ) 

Creates  a  new  set  and  returns  either  a  pointer  to  the 
set  or  NULL  if  there  wasn’t  enough  memory. 

int 

SET 

num__ele  (s) 

*s; 

Returns  the  number  of  elements  in  the  set — 0  if  the 
set  is  empty. 

int 

SET 

set_cmp  (si ,  s2) 

*s1,  *s2; 

The  workhorse  function  used  by  the  equivalent )  and 
disjoint )  macros.  Compares  two  sets;  returns  0  if 
they’re  equivalent,  1  if  they're  disjoint,  2  if  they 
intersect  but  aren’t  equivalent. 

void 

int 

SET 

set_op(op,  d,  si ,  s2) 
op; 

*d,  *s1,*s2; 

Another  workhorse  function,  used  by  the  various 
other  macros  defined  in  Table  2.  You  should  use 
these  macros  rather  than  calling  this  function  directly. 

int 

SET 

subset  (si ,  s2); 

*s1,  *s2; 

Returns  true  if  s  1  is  a  subset  of  s2.  Always  returns 
true  when  si  is  empty. 

assign(d.sl) 

Copies  si  into  d. 

dear(d) 

Clears  all  elements  of  d  yielding  the  empty  set.  . 

complement(d) 

Complements  set  d  (see  text). 

difference^, si  ,s2) 

d  =  si  ~  s2  (symmetric  difference). 

disjoint(s1  ,s2) 

Evaluates  to  1  if  si  and  s2  are  disjoint  (have  no  elements  in 
common) . 

equivalents  ,s2) 

Returns  1 ,  if  the  two  sets  are  equivalent. 

invert(d.sl) 

Does  a  one’s  complement  of  all  bits  in  bit  map. 

fill(d) 

Sets  all  elements  of  dto  1 . 

intersection^, si  ,s2) 

d  =  the  intersection  of  si  and  s2. 

union(d,s1  ,s2) 

d  =  the  union  of  si  and  s2. 

The  following  four  macros  have  side  effects.  Don't  use  +  +, - ,  or  subroutine  or  macro 

invocations  and  so  on  as  either  argument. 

add(x,s) 

Adds  a  member,  x,  to  set  s. 

remove(x.s) 

Removes  element  x  from  set  s. 

ismember(x,s) 

Evaluates  to  true  ifx  is  a  member  of  set  s. 

test(x,s) 

Like  ismember(  )  but  works  on  both  complemented  and  non- 
complemented  sets  (see  text). 

Table  2:  Set  macros 
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dramatically  (it's  now  among  the  best 
I’ve  seen),  and  the  error  messages  are 
more  informative.  The  User's  Guide 
has  been  improved  too.  Some  of  the 
excess  verbiage  has  been  removed, 
and  it  now  includes  a  very  adequate 
explanation  of  how  to  use  the  near 
and  far  keywords. 

Because  the  start-up  module 
sources  are  now  included,  you  can 
make  ROMable  code  if  you  want.  Mi¬ 
crosoft  says  it  will  provide  absolutely 
no  support  to  aid  you  in  this  endeav¬ 
or,  however,  so  you’re  probably  still 
best  off  using  the  Aztec  C  compiler  if 
ROMability  is  an  issue.  The  same  goes 
if  you're  planning  to  port  to  another 
environment.  None  of  the  library 
source  code  is  available  from  Micro- 

soft. 

The  compiler  comes  with  the  usual 
utilities  (lib,  link,  and  so  on),  and  a 
version  of  make  is  now  included  as 
well.  The  make  is  not  a  full  imple¬ 
mentation  of  the  Unix  make,  but  it’s 
adequate  (it  supports  generic  depen¬ 
dencies  [.c.obj]  and  the  $*  and  $@ 
macros — the  version  that  shipped 
with  MASM  didn't). 

The  most  important  addition  to  the 
package  is  the  CodeView  debugger.  In 
the  past,  I’ve  shied  away  from  debug¬ 
gers  when  I've  written  high-level-lan¬ 
guage  programs.  They're  just  too 
much  work;  adding  a  few  printfi  ) 
statements  takes  less  time  and  is  more 
informative  than  messing  with  de¬ 
buggers.  Even  "symbolic”  debuggers 

me)  have  been  fixed.  Spawnt )  now 
works  as  it's  supposed  to,  "Z  doesn't 
cause  problems  with  the  input  func¬ 
tions  or  fseekt ),  and  the  correct  code 
is  generated  in  mixed-model  pro¬ 
grams.  Many  of  the  inexplicable  and 
hard-to-duplicate  bugs  in  the  shell 
have  magically  disappeared.  I  recom¬ 
piled  the  shell  and  utilities  with  no 
difficulties.  In  fact,  the  shell  became 
about  2K  smaller  and  noticeably  fast¬ 
er  in  places.  Because  I  could  dispense 
with  the  spawnt  )  work-around, 
batch  file  execution  sped  up  by  about 
25  percent. 

The  error  recovery  has  improved 

F 

Starting  this  month  I'm  adding  a  new 
feature  to  C  Chest,  a  sort  of  Holub’s 
helpful  hints  for  C  programmers.  Ev¬ 
ery  month  (hopefully)  there  will  be  a 
short  inset  article  that  discusses  some 
part  of  the  language  that’s  liable  to  be 
useful  to  both  beginning  and  ad¬ 
vanced  C  programmers.  If  you've  a 
helpful  (and  short)  hint  of  your  own, 
send  it  in.  This  month  I'm  going  to 
look  at  the  problem  of  nested  com¬ 
ments  and  at  how  to  get  rid  of  all 
those  unsightly  #ifdef  DEBUGS  that 
clutter  up  your  code. 

Comments  don't  nest  in  C.  Conse¬ 
quently,  a  fragment  such  as: 

/* 

code( );  /*  comment  */ 
more( ); 

7 

won’t  perform  as  expected.  The  */ 
on  the  second  line  will  terminate  the 
/*  on  the  first  line.  The  moret );  sub¬ 
routine  will  be  compiled,  and  the  * / 
on  line  4  will  generate  a  "missing 
open  comment"  error  message.  This 
problem  is  usually  circumvented  us¬ 
ing  the  mechanism: 

#ifdef  NEVER 

code! );  /*  comment  */ 
more( ); 

#endif 

Here,  provided  that  NEVER  is  not  * de¬ 
fined  anywhere,  the  code  be- 

lotsam  and  Jetsam 

tween  the  #ifdef  and  #endif  won't  be 
compiled.  Just  "never  say  NEVER"  to 
quote  Romeo  Void.  The  same  mecha¬ 
nism  is  used  to  disable  debugging  di¬ 
agnostics,  as  in: 

#ifdef  DEBUG 

printfC'Debug  diagnostic”); 

#endif 

I  always  seem  to  delete  a  diagnostic 
message  five  minutes  before  I  need  to 
use  it  again.  An  #  ifdef  lets  me  get  rid 
of  it  without  actually  deleting  it. 

A  problem  here  is  code  readability. 
For  portability  reasons  the  #  must  be 
in  the  leftmost  column  and  there  can 
be  no  space  between  the  *  and  the 
ifdef.  Consequently,  the  #ifdefs  mess 
up  all  your  careful  indenting.  More¬ 
over,  three  lines  are  now  required 
for  every  debugging  diagnostic. 
These  problems  can  be  solved  by  us¬ 
ing  the  macro  mechanism  more  in¬ 
telligently.  Consider  the  following: 

» ifdef  DEBUG 
^define  D(x)  x 
#else 

^define  D(x) 

#endif 

If  DEBUG  is  #  defined,  then  the  D( ) 
macro  expands  to  its  own  argument. 

If  DEBUG  is  not  #  defined,  then  the  D(  ) 
macro  expands  to  a  null  string,  to 
nothing.  That  is,  the  entire  D(arg) 
macro  invocation,  along  with  the  ar- 

gument,  is  ignored.  The  argument 
can  be  any  legitimate  C  operation. 
For  example,  D(  printfi  "hi”);  )  ex¬ 
pands  to  printfThi”);  when  DEBUG  is 
# defined.  The  whole  statement,  in¬ 
cluding  the  printfi  )  call,  is  discarded 
when  DEBUG  isn’t  # defined .  Because 
D(  )  is  a  macro  expansion,  as  com¬ 
pared  to  a  definition,  none  of  the 
pound-sign-must-be-in-the-left-col- 
umn  restrictions  apply.  The  D  can  be 
at  any  indent  level.  An  example  of 
the  D( )  macro  is  in  this  month's  List¬ 
ing  Two  on  line  65. 

There  are  three  caveats.  First,  don't 
put  a  semicolon  after  the  )  in  the  mac¬ 
ro  invocation.  A  semicolon  by  itself  is 
a  legitimate  statement  in  C  (it  doesn’t 
do  anything  but  it's  legal).  If  there’s  a 
semicolon  following  the  j,  it  will  still 
be  around  even  if  the  macro  expands 
to  a  null  string,  and  it  can  cause  prob¬ 
lems  with  if /else  statements  binding 
incorrectly.  Second,  be  careful  of  the 
comma  operator.  This  is  not  much  of 
a  problem  because  the  comma  opera¬ 
tor  isn’t  used  very  often,  but  the  C  pre¬ 
processor  can’t  distinguish  between  a 
comma  operator  and  the  comma  that 
separates  macro  arguments.  You'll 
probably  get  an  error  message  if  you 
use  a  comma  operator  inside  a  D( )  in¬ 
vocation.  Finally,  many  compilers 
won’t  accept  macro  invocations  that 
are  longer  than  one  line,  so  the  entire 
macro  should  be  on  a  single  line. 
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aren’t  that  useful  because  they  don’t 
give  you  access  to  local  variables. 

CodeView  is  a  whole  other  ball  | 
game.  It’s  wonderful.  First  of  all,  it's  a 
true  source-code  debugger.  The 
source  code  is  right  there  in  front  of 
you  on  the  screen.  You  can  set  break¬ 
points  in  the  source  code,  page 
around  in  the  code  with  either  a 
mouse  or  the  cursor  keys,  even  go 
look  at  other  files  if  you  like.  If  control 
passes  to  a  subroutine  in  another  file, 
the  second  file  is  read  automatically 
so  the  correct  source  is  still  displayed. 
You  can  do  things  such  as  position  the 
cursor  at  a  line  in  the  source  code  and 
then  execute  up  to  that  line  with  the 
push  of  a  button.  If  you  want  to  see 
the  assembly  language,  push  F3  and 
it's  right  there  in  front  of  you  (with 
the  source  code  interspersed  as  com¬ 
ments,  no  less).  Push  F2,  and  a  regis¬ 
ters  window  appears  (which  remains 
active  while  the  code  is  running  so 
you  can  actually  see  the  registers 
change).  The  line  being  executed  is 
highlighted  in  reverse  video  so  the 
control  flow  is  visible  in  front  of  your 
very  eyes.  In  slow  execution  mode, 
you  can  actually  watch  a  for  state¬ 
ment  loop  and  you  can  watch  control 
skip  over  an  else  clause. 

Among  the  nicest  features  of  Code¬ 
View  are  the  "watch”  functions.  A 
watch  window  can  be  opened  in 
which  contents  of  variables  (even  lo¬ 
cal  variables)  are  displayed.  You  can 
watch  the  values  change  as  the  pro¬ 
gram  executes.  You  can  set  a  "watch 
point,”  a  breakpoint  that  stops  execu¬ 
tion  when  an  expression  evaluates  to 
false  (the  expression  uses  the  normal 
C  operators  and  can  include  any  of 
the  local  or  global  variables).  You  can  j 
also  set  a  "tracepoint,”  a  breakpoint  j 
that  stops  execution  when  a  specific 
memory  location  or  range  of  memo¬ 
ry  locations  is  modified  (unfortunate¬ 
ly  there's  a  128-byte  limit  on  ranges 
so  you  can’t  say  "break  if  any  of  my 
code  space  is  modified”;  you  can’t 
have  everything).  You  can  even  do  all 
this  simultaneously — variables 
changing,  registers  flipping,  control 
flowing  all  at  once — it's  like  a  Christ¬ 
mas  tree. 

There's  also  a  variable-evaluation 
feature  that's  quite  nice,  again  letting 
you  use  C  syntax.  For  example,  if  s  is  a 
structure  that  contains  a  pointer  (p)  to 
another  structure  that  contains  an  ar¬ 
ray  (c),  you  can  ask  CodeView  to 


show  you  (s.p)—>c[3]  and  it  does  it. 
You  can  say  p  to  see  the  contents  of  a 
pointer,  and  you  can  say  *p  to  see  the 
object  pointed  to.  You  can  also  use 
printf- like  format  specifiers.  For  ex¬ 
ample,  a  number  can  be  displayed  in 
hex  by  putting, y  after  the  name.  The 
contents  of  a  string  pointer  can  be  dis¬ 
played  as  a  number,  or  you  can  actu¬ 
ally  see  the  string  (by  putting  a, s  after 
the  name).  You  can  also  modify  vari¬ 
ables  easily  using  the  C  operators: 
a  +  +  and  a  =  10  work  as  expected. 

The  subroutine-calling  stack  is 
available  in  symbolic  form.  You  can 
see  the  entire  subroutine  calling  se¬ 
quence,  with  both  the  calling  subrou¬ 
tine’s  names  and  the  values  of  all  the 
subroutine's  arguments  as  part  of  the 
display.  It  even  works  with  recursive 
subroutines. 

This  is  a  great  debugger. 

Now  for  the  bad  news.  The  compil¬ 
er’s  price  has  gone  up  to  $450,  an 
amount  at  which  the  anarchist  pro¬ 
grammer  in  me  rebels.  You  do  get  a 
lot  for  your  money,  but  that's  still  a 
lot  of  money.  More  important,  the 
cost  of  an  update  ($150)  is,  I  think,  un¬ 
reasonably  high  considering  the 
number  of  bugs  in  Version  3.0.  On  the 
other  hand,  CodeView  may  well  be 
worth  the  $150  all  by  itself. 

I  found  three  bugs  in  the  package:  a 
serious  one  in  CodeView  and  a  cou¬ 
ple  of  trivial  ones  in  the  compiler  it¬ 
self.  When  I  first  starting  using  the 
debugger,  it  had  an  annoying  tenden¬ 
cy  to  go  off  into  outer  space  occasion¬ 
ally.  The  mouse  cursor  disappeared, 
and  the  keyboard  wouldn't  respond 
to  anything.  I  had  to  press  Ctrl-Alt-Del 
to  get  out.  I  suspect,  because  this  er¬ 
ror  stopped  happening  once  I 
learned  how  to  use  the  debugger, 
that  it's  incorrect  handling  of  a  com¬ 
mand  syntax  error  that’s  at  fault. 

Another  problem  seems  to  be  with 
the  mouse  itself.  I'm  using  a  Microsoft 
mouse  (the  older  version  of  the  hard¬ 
ware  but  with  the  new  driver).  My 
friend  Bill,  who  uses  the  Logitech 
mouse,  reports  that  CodeView  crash¬ 
es  when  he  tries  to  use  his  mouse. 


I 


Though  Microsoft  assures  me  that,  if 
a  mouse  driver  is  Microsoft  compati¬ 
ble,  it  should  work,  the  compiler 
package  does  come  with  a  new  ver-  | 
sion  of  the  driver  and  this  driver  may  I 
have  new  or  undocumented  fea-  ! 
tures.  There’s  no  documentation  pro¬ 
vided  for  the  mouse  driver.  As  the  Lo¬ 
gitech  mouse  works  fine  with 
Microsoft  Windows,  I  can’t  help  but 
think  that  it’s  CodeView  that’s  at 
fault,  not  the  driver.  Though  a  mouse 
isn't  required  to  use  the  debugger, 
this  is  one  application  in  which  the 
mouse  is  actually  pretty  nice.  It’s  a 
real  indication  of  CodeView’s 
strengths  that  both  Bill  and  I  continue 
to  like  it  in  spite  of  these  problems. 

I  found  two  bugs  in  the  compiler  j 
itself,  both  trivial.  The  code: 

"define  isquote(c)  ( (c)  =  =  '  "  '  !  ! 

<c)=  =  ’\”) 

incorrectly  generates  the  warning 
"warning  74:  non  standard  extension 
used  -  'macro  formals  in  strings.’  ” 
This  message  is  somewhat  obtuse, 
and  it’s  not  explained  at  all  in  the  er¬ 
ror-messages  appendix.  Because  the 
appendix  stops  with  warning  72, 1  as¬ 
sume  there's  also  a  warning  73  that 
isn’t  explained  either.  I  think  the 
compiler  is  complaining  about  a  mac¬ 
ro  such  as: 

"define  printnum(n,t)  printf("%t”,  n); 

In  this  example,  the  call  print- 
num(10,}i)  should  expand  to 
printf("%\”,  10).  This  situation 
doesn’t  apply  to  the  actual  code, 
however;  the  compiler  is  probably 
confused  by  the  double  quote.  A 
work-around  is: 

"define  isquote(c)  ( (c)=  =  ’\”  ’  !  ! 

(c)  =  =  ’\”) 

The  second  bug  has  to  do  with  the 
new,  and  nonstandard,  cdecl 
keyword.  A  function  that's  declared 
cdecl  will  be  compiled  with  C  param¬ 
eter-passing  conventions  even  if  the 
compiler  command-line  switch  that 
forces  Pascal  or  FORTRAN  parameter- 
passing  conventions  is  used.  It  should 
be  a  no-op  if  this  command-line 
switch  (/Gc)  isn’t  specified.  If  LINT _ 
ARCS  is  " defined  at  the  head  of  your 
file,  the  following  definition  is  in¬ 
cluded  in  signal. h: 
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int  cdecl  (’signalling  int  (*)( )))( ); 

If,  later  on  in  the  same  file,  you  in¬ 
clude  the  line: 

extern  int  (  *signal(int,  int  (*)( )))( ); 

then  the  error  "error  86:  ‘signal’  :  re¬ 
definition"  is  generated.  It  seems  as  if 
the  cdecl  keyword  is  not  really  a  no- 
op  if  /Gc  isn’t  given.  As  I  often  explic¬ 
itly  declare  all  external  subroutines 
at  the  head  of  a  file,  this  is  forcing  me 
either  to  use  a  nonstandard  keyword 
or  always  to  compile  with  the  /Za 
command-line  switch.  This  second 
alternative  also  disables  the  near  and 
far  keywords,  however.  I’d  prefer 
the  cdecl  keyword  to  actually  be  ig¬ 
nored  if  /Gc  isn’t  used  on  the  com¬ 
mand  line. 

The  situation  is  made  worse  by  an 
omission  in  the  User's  Guide  index. 
There’s  only  one  entry  for  cdecl, 
pointing  at  page  193.  Cdecl  is  men¬ 
tioned  on  this  page,  but  there's  no  de¬ 
scription  there  of  what  it  does.  A  ref¬ 
erence  to  page  204,  where  the 
keyword  is  actually  explained, 
should  be  added  to  the  index. 

In  summary,  I  like  the  compiler 
and  I  really  like  CodeView.  If  Micro¬ 
soft  would  only  publish  a  regular 
newsletter  telling  us  about  known 
bugs  in  the  compiler  as  they’re  dis¬ 
covered,  provide  better  support  (for 
start-up  module  modifications  for  ex¬ 
ample),  and  provide  the  library 
sources  if  you  need  them  .... 

Erratum:  A  Bug  in  Sort 

There’s  a  bug  in  the  sort  program 
printed  in  this  column  in  June  1986. 
The  program  isn’t  closing  input  files 
when  it’s  finished  with  them,  so  the 
number  of  simultaneously  open 
merge  files  is  unnecessarily  limited. 
To  fix  the  problem,  insert  an 
fclose(fp);  statement  just  above  the  if 
statement  on  line  385  of  Listing  One 
(sort.c).  You’ll  have  to  put  curly  brac¬ 
es  around  the  body  of  the  while  be¬ 
cause  it  now  has  two  statements  in  it. 

A  reader,  David  Schuler,  also 
caught  an  error  in  the  sort  article. 
The  example  on  page  22: 

2 

1 

20 

10 


won’t  sort  as  explained  because  of 
the  leading  white  space.  The  exam¬ 
ple  should  be  written: 

2 

1 

20 

10 

Availability 

The  code  from  this  month's  column 
is  available  on  CompuServe,  and  an 
IBM  PC-compatible  disk  is  available 
for  $25  from  Software  Engineering 


Consultants,  P.O.  Box  5679,  Berkeley, 
CA  94705.  The  newly  compiled  ver¬ 
sion  of  the  shell  (2.01)  is  available 
from  DDJ  (see  advertisement,  page 
108).  This  version  also  corrects  the 
ESC  environment  and  shell-variable 
modifier  bugs  found  in  Version  2.00. 
Updates  from  earlier  versions  are 
available  from  DDJ  for  a  $6  media 
charge. 

DDJ 
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ARTICLES 


New  Issues  in 
PC  Graphics 

■■■■■■I 


isplay 
hoards  in¬ 
corporating 
third-g  eneration 
graphics  controllers 
have  provided  soft¬ 
ware  developers 
with  a  highly  sophis¬ 
ticated  set  of  capabili¬ 
ties.  Along  with  those  capabilities  comes  a  level  of  com¬ 
plexity  previously  unknown  in  the  PC  graphics  industry; 
in  order  to  use  these  new  hardware  tools  effectively,  pro¬ 
grammers  need  to  become  familiar  with  the  new  issues 
they  raise  and  with  the  new  techniques  associated  with 
those  issues. 

The  chief  features  of  these  new  controllers,  which  in¬ 
clude  the  Intel  82786  and  the  Texas  Instruments  34010, 
include  hardware  graphics  primitives,  which  give  them 
the  ability  to  draw  circles,  lines,  and  bit-mapped  text  at 
high  speed.  The  controllers  also  have  true  microproces¬ 
sor  architectures  that  allow  the  development  and  execu¬ 
tion  of  complex  graphic  algorithms  in  parallel  with  the 
host  CPU's  execution;  the  ability  to  address  large  amounts 
of  memory  (up  to  512  megabytes)  in  support  of  multiple 
pages  of  screen  memory  and  large  amounts  of  off-screen 
graphics  storage  memory;  and  hardware  windowing  ca¬ 
pabilities  that,  for  the  first  time,  completely  separate  the 
physical  layout  of  graphics  memory  from  the  data  dis¬ 
played  on  the  screen. 

Two  Examples 

Although  they  are  both  graphics  coprocessors,  the  Intel 
82786  and  the  TI  34010  are  not  head-to-head  competitors 
in  the  graphics  market.  The  82786  is  able  to  address  4 
megabytes  of  memory  and  display  that  memory  in  hard¬ 
ware  windows  at  a  resolution  of  up  to  640X480  pixels. 


Ed  McNierney,  Number  Nine  Computer  Corp.,  723  Concord  Ave., 
Cambridge,  MA  02138 


Internally,  the  82786 
is  structured  as  three 
distinct  processors:  a 
graphics  processor 
that  performs  draw¬ 
ing,  a  display  proces¬ 
sor  that  extracts  bit¬ 
map  data  from 
memory  and  gener¬ 
ates  a  display  from  it,  and  an  interface  unit  that  mediates 
requests  for  access  to  display  memory.  The  graphics  pro¬ 
cessor  is  capable  of  executing  a  simple  command  list 
stored  in  graphics  memory.  Although  the  command  set 
supports  subroutine  call  and  jump  instructions,  there  are 
no  conditional  branch  opcodes.  The  command  list,  there¬ 
fore,  cannot  be  executed  intelligently  and  must  be  con¬ 
structed  and  managed  by  an  external  intelligent  proces¬ 
sor — usually  the  host  CPU.  These  features  combine  to 
make  the  Intel  82786  an  excellent  choice  for  general-pur¬ 
pose,  high-resolution  graphics  systems,  such  as  might  be 
used  in  business  graphics,  graphic  user  interfaces,  and 
desktop  publishing  systems. 

The  architects  of  the  TI  34010  have  taken  a  slightly  dif¬ 
ferent  approach.  The  82786  is  capable  of  only  simple  (but 
very  fast)  drawing  and  complex  display  manipulation, 
whereas  the  34010  is  the  reverse.  It  provides  no  hardware 
windowing,  and  it  is  only  capable  of  generating  a  display 
that  shows  different  portions  of  graphics  memory  by 
splitting  the  screen  into  horizontal  strips.  It  does  not  have 
as  high  a  clock  speed  as  does  the  82786,  but  it  is  capable  of 
executing  extremely  complex  graphic  algorithms.  Its 
strength  lies  in  drawing  rather  than  in  display  genera¬ 
tion. 

Algorithms  for  drawing  complex  figures  can  be  coded 
and  executed  directly  by  the  34010,  which  operates  as  a 
32-bit  processor  capable  of  addressing  512  megabytes  of 
memory.  It  is  therefore  suited  to  high-resolution,  draw¬ 
ing-intensive  applications  such  as  computer-aided  design, 
drafting,  and  high-end  publishing  and  page  composition. 


by  Ed  McNierney 


The  new  graphics  chips  are  true 
microprocessors  that  run  in 
parallel  with  the  host  CPU. 
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Optimized  for  Graphics 

The  execution  of  graphics  primitives  by  either  of  these 
graphics  processors  provides  two  direct  benefits:  Unlike 
the  host  CPU,  the  graphics  processor  is  designed  to  draw 
efficiently  and  quickly,  and  the  presence  of  a  coprocessor 
frees  up  the  host  to  perform  other  tasks  while  the  draw¬ 
ing  is  being  performed.  Current  host  CPU  instruction  sets 
are  optimized  toward  the  manipulation  of  numeric  and 
string  objects,  not  graphics;  they  allow  instructions  that 
update  pointers  to  move  through  linear  blocks  of  memo¬ 
ry  (such  as  strings  or  buffers)  rather  than  through  rectan¬ 
gular  areas  suitable  for  graphic  applications.  CPUs  are  be¬ 
ing  forced  into  a  service  they  were  never  designed  to 
perform,  whereas  graphic  processors  address  memory 
properly  and  also  contain  silicon  implementations  of 
drawing  algorithms.  Both  features  greatly  reduce  the 
amount  of  code  required  to  execute  a  figure.  Listing  One, 
page  66,  for  example,  contains  three  versions  of  a  routine 
that  draws  a  10X10  rectangle — one  on  a  CGA  in  an  8086 
system,  one  in  an  82786  system,  and  the  last  in  a  34010 
system.  Note  that  in  the  second  two  cases,  the  host  proces¬ 
sor  is  not  executing  the  algorithm  but  is  instead  free  to 
prepare  for  the  next  graphic  output  sequence.  A  system 
incorporating  a  graphics  processor  can  have  its  software 
tuned  to  achieve  real-time  performance  increases  of  50  to 
100  times  compared  to  a  host  CPU/display  buffer  system. 

For  cases  in  which  the  graphics  primitives  are  insuffi¬ 
cient  for  the  task  at  hand,  the  TI  34010  provides  a  true 
microprocessor  instruction  set,  with  arithmetic  instruc¬ 
tions,  conditional  test  and  branch  instructions,  and  soft¬ 
ware  and  hardware  interrupt  control.  Not  only  does  this 
provide  the  developer  with  a  general-purpose  coproces¬ 
sor  but  it  also  permits  the  34010  to  be  used  as  the  only 
processor  in  the  system.  Intelligent  terminals  or  printers 
can  be  driven  by  only  one  CPU,  reducing  hardware  cost 
and  simplifying  software  development.  Although  the  TI 
processor  is  slower  in  terms  of  clock  speed  and  in  the 
types  of  memory  accesses  it  can  perform  than  the  Intel 
82786,  its  programmability  can  allow  a  greater  synergy 


between  it  and  the  host  CPU,  resulting  in  greater  applica¬ 
tion  throughput.  A  graphic  processor  is  not  a  panacea 
that  will  cure  a  sluggish  graphic  implementation,  howev¬ 
er,  because  the  task  of  creating  a  system  in  which  both 
processors  are  used  optimally  is  an  extraordinarily  diffi¬ 
cult  one.  The  complexity  of  such  coprocessor  systems  is 
suggested  in  Figure  1,  page  32,  in  which  sample  34010  and 
sample  82786  system  memory  layouts  are  compared. 

Both  the  TI  and  Intel  processors  are  capable  of  address¬ 
ing  large  amounts  of  graphics  memory.  Although  more 
memory  is  required  simply  to  support  high-resolution  and 
high-color  displays,  these  processors  require  access  to  ad¬ 
ditional  objects  in  their  memory — graphic  software  (both 
in  ROM  and  in  RAM),  memory-mapped  register  sets,  control 
areas,  and  graphics  source  data  all  reside  in  the  processor's 
address  space.  One  of  the  more  difficult  issues  facing  de¬ 
velopers  is  the  management  of  all  this  memory  because 
neither  the  Intel  nor  the  TI  processors  supports  explicit 
memory  management  other  than  reserving  certain  por¬ 
tions  of  their  address  spaces  for  some  specific  uses. 

Graphics  memory  also  has  to  accommodate  many  new 
types  of  objects  whose  presence  springs  directly  from  the 
fact  that  they  support  off-screen  graphics  data.  No  appli¬ 
cation  developers  really  want  to  store  fonts,  icons,  cur¬ 
sors,  and  temporarily  hidden  portions  of  the  display  in 
system  memory;  they  have,  however,  been  forced  to  do 
so  because  there  has  been  no  other  place  to  put  them.  All 
the  housekeeping  efforts  that  currently  have  to  be  exert¬ 
ed  in  the  host  address  space  in  order  to  keep  track  of  these 
objects  must  now  be  transferred  to  the  graphics  proces¬ 
sor.  The  host  is  equipped  with  the  operating  system's  nor¬ 
mal  memory  allocation,  deallocation,  and  management 
functions,  all  of  which  need  to  be  duplicated  and  execut¬ 
ed  by  the  graphics  coprocessor  to  manage  its  own  memo¬ 
ry.  Although  display  memory  grows  in  complexity,  it  is  at 
least  performing  a  task  for  which  it  is  intended,  freeing 
system  memory  for  the  execution  of  host  CPU  code  and 
the  storage  of  host  CPU  data. 

The  management  of  graphics  memory  becomes  espe- 
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cially  complex  in  the  case  of  the  82786  because  it  has  full 
hardware  windowing  support.  As  graphics-based  user 
interfaces  become  more  common,  the  82786  will  prove  a 
great  benefit  to  application  developers  and  to  the  under¬ 
lying  windowing  systems  that  support  them.  An  82786- 
based  system  is  entirely  freed  from  any  association  be¬ 
tween  physical  memory  addresses  and  screen  displays — 
any  graphics  data  residing  anywhere  in  its  address  space 
can  be  displayed  at  any  point  on  the  screen  by  creating  a 
window,  positioning  it  on  the  screen,  and  defining  the 
bit-map  address  from  which  that  window  should  take  its 
data.  This  system  provides  greater  flexibility  for  the  ap¬ 
plication  as  well  as  increased  performance  in  windowing 
environments.  On  an  IBM  Enhanced  Graphics  Adapter, 
for  example,  moving  a  400  X  300-pixel  rectangle  in  16-col¬ 
or  mode  to  another  position  on  the  screen  requires  mov¬ 
ing  60,000  bytes  of  data — and  then  moving  up  to  60,000 
bytes  more  to  fill  the  hole  uncovered  by  the  moved  rect¬ 
angle.  In  an  82786  environment,  however,  the  same  oper¬ 
ation  requires  updating  only  about  a  dozen  bytes,  per¬ 
forming  the  same  task  up  to  10,000  times  faster! 

The  fundamental  benefit  derived  from  a  hardware- 
based  windowing  system  is  that  the  covering  of  one  win¬ 
dow  by  another  does  not  destroy  any  display  information 


but  simply  hides  it.  Moving  the  covering  window  then 
reveals  that  graphic  data  again,  without  the  application 
having  to  store  a  temporary  copy  of  it  and  replace  it — 
panning,  smooth  scrolling,  and  the  repositioning  of  win¬ 
dows  all  become  much  faster  and  much  more  practical  to 
implement  in  graphical  user  interfaces.  Not  only  do  these 
windows  save  graphics  memory  by  obviating  the  need 
for  maintaining  duplicate  copies  of  display  data  but  they 
also  save  memory  by  allowing  data  in  different  windows 
to  be  displayed  at  different  pixel  depths. 

In  a  high-color  paint  package  using  an  8-bit-per-pixel 
display,  there  is  no  need  for  a  pop-up  window  containing 
a  list  of  picture  file  names  to  be  displayed  in  anything  but 
black  and  white.  By  creating  a  new  1-bit-per-pixel  win¬ 
dow  in  which  to  display  the  text,  the  application  reduces 
both  the  memory  required  for  the  display  and  the  time 
required  to  print  the  text  in  the  window  by  a  factor  of  8. 
This  greater  flexibility  means  that  display  memory  re¬ 
sources  can  be  used  more  prudently  and  in  a  manner 
more  appropriate  to  the  particular  display  application  at 
hand. 

New  Expertise  Is  Needed 

All  these  wonderful  advantages  are  not  without  their 
price.  As  with  any  new  hardware  or  software  technolo¬ 
gy,  a  whole  new  area  of  expertise  has  to  be  developed. 
The  examples  set  by  the  Apple  Macintosh  and  the  IBM 
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Figure  1:  Comparison  of  sample  34010  and  82786  system  memory  layouts 
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EGA  are  good  parallels  to  the  graphic  coprocessor  envi¬ 
ronment.  Both  of  these  technologies  represented  signifi¬ 
cant  advances  over  what  was  previously  available  in  the 
market,  and  they  both  ran  into  dificulties  because  of  the 
long  lead  time  required  for  software  development  to  take 
place.  The  new  graphic  coprocessor  systems  are  com¬ 
plex,  and  it  will  take  a  while  before  sufficient  expertise  is 
acquired  to  use  them  well  or  at  all. 

Although  software  development  efforts  are  simplified 
at  the  microscopic  level  in  that  a  developer  is  spared  one 
more  implementation  of  Bresenham’s  circle  algorithm, 
the  overall  environment  is  more  demanding  and  more 
detailed,  and  the  development  overhead  required  may 
prevent  smaller  software  firms  from  undertaking  any 
development  until  a  significant  market  leader  has  be¬ 
come  apparent.  The  ability  to  take  an  intelligent  graphics 
board  and  use  it  to  run  existing  applications  faster  will 
help  break  the  hardware/software  development  dead¬ 
lock  in  which  software  developers  won’t  port  to  new 
boards  until  they  sell  and  hardware  developers  can't  sell 
boards  until  the  software  support  is  there.  As  a  result  of 
this  complexity,  the  first  coprocessor  systems  will  proba¬ 
bly  do  nothing  more  than  execute  current  software  pack¬ 
ages  more  quickly.  There  will  be  a  definite  development 
lag  before  the  coprocessors  are  used  fully  and  effectively 
for  new,  innovative  applications. 

Hindering  the  ability  of  developers  to  work  with  these 
products  is  the  current  state  of  graphic  software  stan¬ 
dards.  In  different  respects  they  provide  too  much  and 
too  little.  The  graphic  software  world  has  too  many 
"primitive”  standards,  and  a  developer  often  has  to  make 
a  difficult  choice  between  VDIs,  CGIs,  GKS,  and  PHIGS  sys¬ 
tems,  not  to  mention  new  systems  being  proposed.  A  stan¬ 
dard  just  isn’t  a  standard  when  a  developer  has  to  support 
six  of  them  to  cover  50  percent  of  the  market!  On  the  short 
side,  none  of  the  present  standards  addresses  the  issue  of 
windowing,  although  an  ANSI  committee  is  working  on  a 
windowing  proposal.  Unfortunately,  it  will  almost  cer¬ 
tainly  take  a  while  for  standards  committees  to  propagate 


new  proposals  for  these  new  processors,  and  by  that  time 
several  independent  interfaces  will  exist  and  the  stan¬ 
dards  will  occupy  the  same  role  they  do  now. 

Communication  and  Synchronization 

On  the  more  practical  side,  some  implementation  prob¬ 
lems  need  to  be  addressed  by  any  application  that  at¬ 
tempts  to  use  a  graphic  processor  well.  Because  each  pro¬ 
cessor  has  its  own  instruction  set  and  opcode  syntax, 
commands  need  to  be  translated  from  the  format  in 
which  the  application  program  generates  them  to  a  for¬ 
mat  intelligible  by  the  graphic  processor.  A  well-thought- 
out  communication  syntax  is  necessary  in  order  to  mini¬ 
mize  the  overhead  required  to  send  the  desired 
command  to  the  graphic  processor,  or  the  application 
may  end  up  taking  longer  to  perform  the  drawing  than  if 
the  host  CPU  had  executed  the  graphic  algorithm  itself. 
Going  hand  in  hand  with  an  efficient  communications 
protocol  is  a  careful  synchronization  of  the  tasks  being 
performed  by  the  host  and  graphic  processors.  Because  a 
PC  with  an  82786  or  34010  is  a  true  multiprocessor  system, 
the  architecture  of  the  graphics  board  may  require  full 
status  information  to  be  provided  to  the  host  CPU.  If  a 
command  is  sent  to  the  graphics  processor  to  draw  a  cir¬ 
cle,  and  then  the  host  CPU  wishes  to  read  the  value  of  a 
pixel  along  the  circumference  of  that  circle,  the  host 
needs  to  be  able  to  tell  whether  the  circle  has  been  com¬ 
pleted,  lest  the  incorrect  value  be  read. 

An  extreme  approach  to  synchronization  is  to  wait  for 
any  command  or  program  sent  to  the  graphic  processor  to 
complete  before  returning  control  to  the  host  application. 
Although  "lockstepping”  will  work  and  will  execute  faster 
than  a  host  CPU  without  the  processor,  the  capabilities  of 
the  processor  are  largely  ignored  in  this  case.  Synchroniza¬ 
tion  schemes  can  include  mutually  interruptible  systems 
in  which  each  processor  signals  the  other  when  it  is  ready 
for  new  material,  critical  flags  that  tell  one  processor  that 
the  other  is  in  a  possibly  unstable  state,  and  polling  mecha¬ 
nisms  in  which  each  processor  registers  a  request  to  the 
other  and  then  polls  for  a  status  flag  to  be  set  indicating 
that  the  request  can  be  honored.  Figure  2,  below,  illus¬ 
trates  these  schemes. 
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Figure  2:  Synchronization  of  dual  processors  through  a  mutual  interrupt  system 
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Black  Boxes 

Additional  issues  are  brought  up  by  the  blurring  of  certain 
traditional  boundaries  in  PC  environments.  There  is  less 
and  less  of  a  distinction  between  "graphic”  and  "system” 
memory;  packages  such  as  Microsoft  Windows  require 
that  a  display  driver  be  able  to  perform  drawing  in  pre¬ 
cisely  the  same  manner  on  a  given  block  of  graphic  data, 
no  matter  where  it  resides  in  the  system.  Drawing  may  be 
performed  in  traditional  system  memory,  in  bank-selected 
expanded  memory,  or  in  on-board  graphic  memory. 

The  difficulty  here  comes  from  what  in  other  cases  is  a 
benefit — the  graphic  algorithms  embodied  in  the  graphic 
processor  are  "black  boxes,”  opaque  to  the  user.  If  the 
graphic  processor  is  not  capable  of  performing  drawing 
in  system  memory  because  of  limitations  of  software  or 
hardware  design,  then  the  application  must  provide  an 
algorithm  that  duplicates  the  one  contained  in  the  black 
box  in  every  respect.  If  the  algorithm  cannot  be  duplicat¬ 
ed  precisely,  the  graphic  processor  becomes  useless  in 
that  system — unfortunately,  the  IBM  PC's  architecture 
prevents  a  graphics  board  residing  in  an  expansion  slot 
from  modifying  system  memory  in  any  way.  This  restric¬ 
tion  has  been  lifted  in  the  PC/AT,  but  it  still  presents  an 
obstacle  blocking  access  to  a  large  installed  base  of  ma¬ 
chines.  In  addition,  because  the  graphics  board  may  con¬ 
tain  far  more  memory  than  the  host  CPU  system  does,  that 
memory  may  be  made  available  for  nongraphics  use  by 
other  applications  such  as  RAM  disks,  disk  caches,  and 
expanded  memory  drivers.  Developers  need  to  avoid 
painting  themselves  into  corners  by  clinging  to  old  as¬ 
sumptions  that  were  valid  on  IBM  Color  Graphic  Adapters 
but  that  are  no  longer  appropriate. 

Dealing  with  Text 

Aiding  the  battle  against  rapidly  multiplying  display 
modes  but  clouding  the  implementation  battle  is  the 
growing  awareness  and  appreciation  of  the  fact  that  text 
in  any  form  is  nothing  more  than  a  special  type  of  graph¬ 
ic  data.  Text  can  be  zoomed,  scaled,  colored,  italicized,  or 
displayed  in  many  different  fonts  all  on  the  screen  at 
once,  and  that  same  text  must  be  able  to  be  read  back 
from  the  screen.  Character  recognition  on  a  mono¬ 
chrome  screen  is  straightforward,  but  the  extraction  of 
ASCII  data  from  a  highly  complex  graphical  bit  map  is  a 
very  challenging  task. 

The  further  hardware  and  software  manufacturers 
can  go  in  removing  constraints  on  the  use  and  appear¬ 
ance  of  text,  the  closer  they  will  come  to  an  ideal  user 
interface.  The  application  of  multiple  scaled  fonts  to 
WYSIWYG  word  processing  is  obvious,  and  the  growing 
desktop  publishing  market  will  certainly  benefit  from 
these  new  processor  technologies.  Average  users  are  be¬ 
coming  more  sophisticated  and  more  demanding  about 
the  text  they  see  every  time  they  turn  on  the  PC.  High- 
quality  text  must  be  provided  without  an  excessive  speed 
penalty  on  the  part  of  users;  no  matter  how  pretty  it 
looks,  if  it’s  not  fast  it  won’t  be  liked. 

Both  the  TI  and  Intel  processors  provide  sophisticated 


text  support,  allowing  for  color  bit-mapped  text  to  be  gen¬ 
erated  at  speeds  approaching  those  of  hardware  charac¬ 
ter  generators.  Fonts  can  be  stored  in  graphic  memory, 
freeing  precious  system  memory  from  the  task,  and  spe¬ 
cial  attributes  such  as  underlining  and  boldfacing  can  be 
synthesized  on  the  fly,  obviating  the  need  for  storing  mul¬ 
tiple  copies  of  the  same  font.  Fonts  are  not  tiny  objects, 
and  extremely  large  amounts  of  memory  may  be  re¬ 
quired  to  store  and  format  them.  The  effective  use  of  font 
storage  may  be  the  most  critical  issue  in  the  apparent 
performance  of  a  graphics  application  because  poorly 
managed  font  memory  translates  into  slow  text  perfor¬ 
mance  and  text  performance  is  the  one  area  in  which 
users  are  most  sensitive  and  critical.  Judgment  and  clever 
implementation  here  can  certainly  make  the  difference 
between  a  popular  package  and  a  failure. 

Fortunately,  as  the  silicon  available  becomes  more  com¬ 
plex,  the  tools  available  become  more  powerful.  Already 
function  libraries  that  perform  three-dimensional  graph¬ 
ics,  floating-point  arithmetic,  text  generation  and  scaling, 
and  object  filling  and  shading  are  being  provided,  both  by 
chip  manufacturers  and  by  third  parties.  In  addition,  TI 
even  offers  a  C  compiler  for  the  34010,  allowing  the  direct 
conversion  of  algorithms  developed  on  earlier  systems. 
These  libraries  and  compilers  are  no  longer  the  conve¬ 
nient  graphics  toolkits  offered  for  existing  graphic  display 
boards  but  are  essential  steps  to  application  development. 

Virtual  Displays 

Because  it  provides  hardware  windowing  directly,  the 
82786  can  create  a  virtual-display  environment  that  direct¬ 
ly  parallels  the  80386 's  Virtual  86  execution  mode — each 
Virtual  86  task  can  think  it  is  running  on  an  IBM  Color 
Graphics  Adapter,  while  each  virtual  CGA  is  being  dis¬ 
played  in  a  distinct  hardware  window.  This  chip  compan¬ 
ionship  not  only  allows  existing  applications  to  run  un¬ 
modified  on  an  80386  but  also  allows  them  to  execute 
unmodified  in  a  windowing  environment  (see  Figure  3, 
page  38). 

Along  with  the  essential  ability  to  execute  current  ap¬ 
plications,  the  82786  introduces  the  concepts  of  visual  hi¬ 
erarchy  and  privilege  in  direct  parallel  to  the  software 
execution  controls  provided  by  the  80386.  A  truly  inte¬ 
grated  multitasking  system  must  be  able  to  treat  graphic 
and  visual  information  with  the  same  protection  and  con¬ 
trol  as  it  treats  any  other  portion  of  its  execution  environ¬ 
ment.  Imagine  an  82786  graphic  application  running  in  a 
multitasking  environment.  When  the  application  starts 
up,  it  wants  to  display  itself  in  the  top  window,  centered 
on  the  screen  and  occupying  three-quarters  of  the  visible 
area  of  the  screen.  Although  it  is  quite  reasonable  to  ex¬ 
pect  that  the  application  considers  itself  important 
enough  to  merit  all  that  room,  the  operating  system 
knows  that  there  are  several  other  applications  active 
that  may  require  attention.  By  making  the  window  posi¬ 
tioning  and  sizing  commands  privileged  system  calls,  the 
operating  system  can  act  as  an  intermediary  between 
what  the  application  wants  and  what  resources  it  consid¬ 
ers  appropriate  to  supply.  The  request  can  be  examined, 
modified  to  fit  the  state  of  the  system  at  the  moment,  and 
the  application  notified  of  the  modifications  required  to 
fulfill  the  request.  Alternatively,  the  application  could  be 
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allowed  to  test  the  manner  in  which  a  specific  request 
would  be  fulfilled  and  modify  or  cancel  the  request  en¬ 
tirely  depending  upon  the  results. 

The  concept  of  visual  hierarchy  and  privilege  can  be 
the  beginning  of  another  step  forward  in  user-interface 
design.  By  providing  the  means  to  manipulate  shared  bit¬ 
mapped  displays  in  a  multitasking  system,  a  graphics  pro¬ 
cessor  frees  application  designers  from  one  more  level  of 
hardware  constraint — instead  of  designing  to  be  coopera¬ 
tive  with  other  applications  sharing  the  same  screen,  de¬ 
signers  can  work  with  a  true  virtual  system  in  which  they 
appear  to  own  not  only  all  of  memory  (and  then  some) 
but  also  to  own  an  entire  dedicated  display.  This  freedom, 
combined  with  the  ability  to  produce  higher-color  and 
higher-resolution  displays  and  the  freedom  gained  by  off¬ 
loading  the  host  CPU  from  graphics  work,  will  allow  re¬ 
markable  growth  in  the  sophistication  and  ease  of  use  of 
software;  the  tools  are  finally  becoming  available  to  catch 
up  with  the  dreams  of  software  designers. 

The  IV ext  Generation 

Where  will  the  first  fruits  of  graphic  processor  technology 
appear?  Right  away  systems  will  incorporate  them  into 
high-speed  versions  of  current  products.  The  chief  prob¬ 
lem  with  graphical  operating  environments  (Windows, 
GEM,  and  the  like)  is  that  they  incur  vast  overhead  in  main¬ 
taining  the  screen.  Ports  of  these  environments  (and  simi¬ 
lar  graphics-intensive  applications,  such  as  CAD  packages) 
to  faster,  graphics-processor-based  systems  will  become 
available  almost  immediately — some  may  even  have  been 
introduced  by  the  time  this  article  is  printed.  Graphics  tool¬ 
kits  and  libraries,  especially  the  popular  ones  such  as 
MetaWiNDOW  and  HALO,  will  follow  soon  after.  Some  of 
the  more  foresighted  of  these  libraries  have  been  emulat¬ 
ing  the  capabilities  of  graphic  processors  in  software  for 
quite  a  while;  applications  that  have  taken  advantage  of 


those  emulations  will  benefit  most  greatly.  In  parallel  with 
the  porting  of  graphic  operating  environments  will  come 
the  development  of  enhancements  to  those  environments, 
especially  in  the  field  of  font  and  text  development.  The 
ability  to  generate  text  at  high  resolutions  with  acceptable 
speed  will  spur  consumer  demand  for  more  powerful  text 
systems  and  displays  that  begin  to  approach  the  flexibility 
and  resolution  available  in  their  laser  printers.  Operating 
system  and  memory  management  products  will,  lag  be¬ 
hind.  When  available,  however,  they  will  be  the  sources  of 
the  largest  direct  benefit  to  users. 

Conclusion 

Intel  and  TI  have  produced  two  very  different  but  re¬ 
markable  processors.  The  software  industry  will  reap 
many  benefits  from  them  both,  in  part  because  each  com¬ 
pany  has  been  very  responsive  to  the  concerns  and  needs 
of  developers.  The  Number  Nine  Pepper  Series  of  graph¬ 
ics  boards  includes  products  that  use  both  the  TI  and  Intel 
coprocessors.  In  addition  to  providing  powerful  hard¬ 
ware,  the  Pepper  Series  addresses  the  software  issues 
raised  here  through  the  Number  Nine  Intelligent  Operat¬ 
ing  System  (NNIOS). 

As  the  technology  of  visual  displays  is  brought  to  a  price 
and  performance  level  that  can  make  it  available  to  the 
mass  market,  the  opportunity  for  software  of  high  per¬ 
ceived  value  increases.  Public  awareness  of  the  quality 
and  craftsmanship  inherent  in  excellent  software  will 
certainly  increase,  and  developers  who  make  the  neces¬ 
sary  investments  in  time  and  effort  to  use  these  new 
graphic  systems  effectively  will  become  a  prominent 
part  of  that  awareness. 

DDJ 


Figure  3:  82786  managing  multitasking  display 
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A  Mandelbrot  Prograi 

the  Macintosh 


for 


K.  Dewdney's  Computer 
Recreations  column  in 
0  Scientific  American  often 
provides  inspiration  for  program¬ 
mers  looking  for  dew  projects.  Dewd- 
ney  frequently  discusses  interesting 
and  offbeat  algorithms  and  other  pro¬ 
gramming  matters.  His  column  of  Au¬ 
gust  1985  in  particular  seems  to  have 
touched  off  something  like  a  feeding 
frenzy  among  hackers  looking  for 
new  algorithmic  adventures.  In  that 
column,  Dewdney  discussed  the  Man¬ 
delbrot  set,  a  mathematical  object 
named  in  honor  of  the  French  math¬ 
ematician  Benoit  Mandelbrot,  of  frac¬ 
tal  fame.  Dewdney  also  provided  sev¬ 
eral  computer-generated  images  of 
the  set,  which  he  called  “the  most 
complex  object  in  mathematics,”  that 
are  strikingly  beautiful.  Interested 
readers  might  refer  to  Mandelbrot’s 
classic  volume,  The  Fractal  Geometry 
of  Nature  (New  York:  W.  H.  Freeman 
&  Co.,  1982),  for  other  fractal 
creations. 

This  article  describes  a  68000  pro¬ 
gram,  written  using  Apple's  MDS  as¬ 
sembly-language  development  sys¬ 
tem,  that  produces  screen  images  of 
the  Mandelbrot  set  on  a  Macintosh. 
The  final  application  is  just  over  4,000 
bytes  long.  The  source  code,  in  two 
sections,  is  in  Listings  One  and  Two, 
pages  72  and  84.  Listing  One,  at  just 
over  700  lines,  contains  the  main 
body  of  the  program.  Listing  Two  is 
the  assembler  source  for  a  string-to- 
fixed-point  number  conversion  rou¬ 
tine  that  is  assembled  separately  and 
then  linked  with  the  REL  file  pro¬ 
duced  by  Listing  One. 

The  algorithm  described  by  Dewd¬ 
ney  is  surprisingly  simple.  Of  the 
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This  program 
explores  the  most 
complex  object  in 
mathematics. 


more  than  1,200  lines  of  code  in  the 
program,  fewer  than  40  lines  are  ded¬ 
icated  to  the  actual  calculations  in¬ 
volved  in  the  algorithm.  The  rest  of 
the  program  is  devoted  to  dealing 
with  the  well-known  Macintosh  user 
interface — windows,  dialog  boxes, 
and  the  like — and  to  handling  the 
conversion  and  storage  of  the  user-in- 
put  parameters  that  dictate  which 
area  of  the  set  to  display  and  at  what 
magnification. 

The  algorithm  discussed  by  Dewd¬ 
ney  involves  the  use  of  complex 
numbers.  I’ll  provide  a  brief  over¬ 
view  of  the  algorithm,  but  I  refer  in¬ 
terested  readers  to  Dewdney’s  excel¬ 
lent  discussion  of  the  subject.  Suffice 
it  to  say  that  the  Mandelbrot  set  is  the 
result  of  applying  an  extremely  sim¬ 
ple  iterative  function  to  each  point  of 
interest  in  the  complex  plane,  where 
the  starting  value  that  seeds  the  func¬ 
tion  is  the  position  of  the  number  in 
the  plane.  The  result  of  each  iteration 
is  a  new  complex  number.  If  the  size 
of  the  number — its  distance  from  the 
(0,  0)  origin  of  the  plane — exceeds  2  at 
any  point  before  the  iteration  runs  a 
predetermined  maximum  number 
of  times,  then  the  point  lies  outside 
the  set.  If  the  iteration  runs  its  full 
course  and  the  size  of  the  complex 
number  remains  less  than  or  equal  to 
2,  then  the  point  lies  within  the  Man¬ 
delbrot  set.  The  actual  iterative  func¬ 
tion  involves  nothing  more  than 


starting  with  a  value  of  0,  adding  the 
complex  value  of  the  point,  and 
squaring.  Each  successive  result  is 
then  fed  back  into  the  iterative  func¬ 
tion.  Note  that  the  terms  within  and 
without  are  relative:  A  true  rendition 
of  the  set  would  require  an  infinite 
number  of  iterations;  happily,  you 
can  obtain  pleasing  results  with  as 
few  as  30  or  40  iterations  per  point. 

Objectives 

I  had  two  major  objectives  in  mind 
when  I  wrote  this  program:  The  first 
was  to  produce  attractive  and  inter¬ 
esting  images;  the  second  was  to  pro¬ 
duce  them  as  quickly  as  possible.  Al¬ 
though  the  algorithm  is  quite  simple, 
it  is  also  extremely  computation  in¬ 
tensive.  I  wanted  to  explore  as  much 
of  the  set  as  possible  but  did  not  want 
to  sit  around  for  any  great  length  of 
time  before  being  able  to  see  the  re¬ 
sults  of  a  session. 

One  final  objective  was  to  build  up 
a  library  of  interesting  Mandelbrot 
vistas  using  the  screen-dump  facility 
of  the  Macintosh.  In  addition  to  stor¬ 
ing  the  actual  graphics  image,  I  also 
wanted  to  be  able  to  save  all  the  rele¬ 
vant  parameters  so  that  I  could  repro¬ 
duce  the  session  at  my  leisure. 

In  terms  of  an  attractive  screen  dis¬ 
play,  the  fact  that  the  program  runs 
on  a  Macintosh  immediately  places  it 
at  somewhat  of  a  disadvantage  in 
comparison  to  programs  written  for 
other  machines.  All  the  MandelZoom 
programs  (so  named  by  Dewdney)  I 
have  seen  to  date  use  color  and  pro¬ 
duce  strikingly  beautiful  screen  im¬ 
ages.  The  Macintosh,  of  course,  is  a 
black-and-white  machine.  What  the 
Mac  does  have  is  an  exceedingly 
crisp  and  clean  display,  at  a  reason¬ 
able  342  X  512-pixel  resolution.  It 
also  has  the  ability  to  draw  using  a 
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variable-size  pen  and  with  a  user-se¬ 
lected  pen  pattern.  Patterns  take  the 
place  of  colors  in  this  implementa¬ 
tion;  I  think  the  results  shown  in  the 
accompanying  screen  dumps  are 
quite  pleasing.  The  real  beauty  of  the 
Mandelbrot  images  lies  not  simply  in 
the  graphic  image  of  the  Mandelbrot 
set  itself — the  strange,  beetlelike  ob¬ 
ject  seen  in  Figure  1,  page  45 — but  in 
allowing  the  regions  adjacent  to  the 
boundary  of  the  set  to  be  set  off  in 
different  colors,  or  patterns  if  you 
will,  depending  on  the  number  of  it¬ 
erations  reached  before  the  size  of 
the  complex  number  calculated  for 
each  point  exceeds  2.  Half  the  fun  of 
running  this  program  comes  from 
varying  the  count  "breakpoints”  that 
determine  the  size  of  each  region. 

Fixed-Point  Numbers 

The  problem  of  getting  the  program 
to  run  as  quickly  as  possible  was  an 
interesting  one.  Derivation  of  the 
[  Mandelbrot  set  requires  the  use  of 
real  numbers  because  the  complex 
values  used  in  the  computations  have 
fractional  as  well  as  integer  compo¬ 
nents.  Most  implementations  use 
floating-point  numbers  for  this  pur¬ 
pose.  On  the  Mac,  floating-point  sup¬ 
port  is  normally  provided  by  a  disk- 
based  package  known  as  SANE,  for 
Standard  Apple  Numeric  Environ¬ 
ment  (now  provided  in  ROM  on  the 
Mac  Plus).  SANE,  however,  seemed  a 
bit  slow  for  my  purposes. 

I  found  documentation  for  three 
routines  in  ROM  that  supported  an¬ 
other  variety  of  real-number  repre¬ 
sentation  known  as  fixed  point.  In 
fixed-point  arithmetic,  the  integer 
portion  of  a  number  is  stored  as  a  16- 
bit  quantity  in  the  high-order  word 
of  a  4-byte  long  word  and  the  frac¬ 
tional  portion  is  stored  in  the  low-or¬ 
der  word.  A  bit  of  informal  bench¬ 
marking  convinced  me  that  fixed- 
point  calculations  would  run 
roughly  an  order  of  magnitude  faster 
than  would  floating-point  opera¬ 
tions,  at  the  cost  of  some  precision; 
the  trade-off  seemed  reasonable.  I 
didn't  discard  the  SANE  package  en¬ 
tirely — I  used  its  conversion  routines 
for  converting  the  three  user-input 
parameters  from  string  to  SANE  float¬ 
ing-point  format,  and  then  I  convert¬ 
ed  from  the  single-precision  floating¬ 
point  format  back  to  fixed-point 
representation.  See  Listing  Two  for 


the  tedious  details. 

ROM  Conventions 

The  program  makes  use  of  several  of 
!  the  500-odd  routines  that  are  built 
i  into  the  Macintosh  ROM.  It's  beyond 
the  scope  of  this  article  to  discuss  all 
the  details  of  how  they  are  used — 
Caroline  Rose  et  al.'s  Inside  Macintosh 
(Reading,  Mass.:  Addison-Wesley, 

|  1985)  documentation  devotes  more 
i  than  1,000  pages  to  that  task — but  a 
quick  overview  might  be  useful  for 
readers  unfamiliar  with  the  Macin¬ 
tosh. 

Most  of  these  routines,  or  "traps,” 
are  dedicated  to  implementing  the 
Mac  user  interface.  Traps  can  be 
identified  in  the  source  code  as  iden- 
|  tifiers  preceded  by  an  underscore, 
such  as  _ GetNextEvent  or  _ PenPat . 
The  file  MacTraps.D,  which  is  includ¬ 
ed  at  the  top  of  the  main  listing,  is 
simply  a  long  list  of  equates  in  which 
each  trap  name  is  equated  to  a 
unique,  2-byte  hexadecimal  value 
that  starts  with  a  hex  $A.  This  makes 
[  use  of  the  68000  "line  1010  trap”  fea- 
|  ture  (  a  hexadecimal  SA  is  1010  in  bi¬ 
nary),  in  which  execution  of  any  in¬ 
struction  whose  first  nibble  is  a  hex 
$A  forces  the  processor  to  suspend  its 
current  operations  and  vector 
through  an  address  in  low  memory 
to  a  trap  dispatch  table,  where  the 
following  three  nibbles  of  the  in¬ 
struction  are  decoded  to  determine 
which  particular  trap  routine  to  exe¬ 
cute.  Simple,  right? 

Parameter  passing  for  the  ROM  rou¬ 
tines  follows  Pascal  conventions,  in 
which  the  parameters  are  pushed 
onto  the  stack  in  the  order  document¬ 
ed  in  Inside  Macintosh.  If  a  parameter 
is  longer  than  4  bytes,  a  pointer  to  its 
address  is  passed  instead  of  the  actual 
data.  And  if  the  routine  is  a  function 
(and  therefore  returns  a  value),  space 
must  be  cleared  on  the  stack  for  the 
function  result  before  the  parame¬ 
ters  are  pushed  and  the  result 
popped  from  the  stack  once  the  rou¬ 
tine  returns.  Most  of  the  operating 
system  routines  found  in  ROM  do  not 
use  the  above  stack-passing  conven¬ 


tion;  a  register-based  parameter-pass¬ 
ing  convention  is  used  instead.  Final¬ 
ly,  you  should  note  that  many  of  the 
operands  referenced  in  the  program 
have  (A5)  suffixed  to  their  names. 
This  indicates  that  the  operand  in 
question  was  defined  using  the  DS 
(define  storage)  assembler  directive  at 
the  end  of  the  source  listing.  All  vari¬ 
ables  so  created  are  referenced  in 
code  as  an  offset  off  register  A5. 

Program  Description 

The  program  uses  two  dialog  boxes 
and  one  window.  Windows  and  dia¬ 
logs  are  two  examples  of  user-inter- 
face  objects  that  are  supported  by 
several  routines  in  the  Macintosh 
ROM.  Although  windows  and  dialogs 
can  be  defined  in  code,  it  is  generally 
much  simpler,  and  provides  better 
documentation,  for  programmers  to 
define  them  using  Apple’s  RMaker 
(or  resource  maker)  program.  The 
concept  of  resources  is,  as  far  as  I 
know,  unique  to  the  Macintosh,  and 
it  would  take  a  much  longer  article  } 
than  this  to  do  them  justice.  RMaker 
is  generally  run  last  in  the  develop¬ 
ment  sequence,  following  linking. 
Listing  Three,  page  87,  is  the  source 
file  that  is  input  to  RMaker  for  the 
MandelZoom  program. 

The  first  Parameters  dialog  allows  j 
users  to  select  the  x  and  y  coordinates 
of  the  region  to  be  plotted;  the  size  of  j 
the  region;  and  the  count  break¬ 
points,  which  determine  what  pat-  j 
terns  are  associated  with  what  count  | 
ranges.  The  x  and  y  coordinates  refer 
to  the  lower  left-hand  corner  of  the 
drawing  window,  which  comes  up 
once  the  dialog  is  dismissed  by  click¬ 
ing  the  Plot  button.  The  Side  parame¬ 
ter  refers  to  the  y  coordinate  of  the 
window;  the  length  of  the  image 
along  the  x  axis  is  scaled  according  to 
the  ratio  of  the  window's  width  to  its 
length.  You  can  cycle  through  the  in¬ 
put  fields  using  the  Tab  key. 

The  first  (top)  count  on  the  right 
side  of  the  dialog  box  is  the  maximum 
number  of  iterations  that  will  be  per¬ 
formed  for  each  point.  If  the  pro-  j 
gram  is  able  to  iterate  this  number  of 
times,  the  point  will  be  drawn  in  a 
solid  black  pattern.  If  the  size  of  the 
complex  number  produced  by  the  it¬ 
eration  exceeds  2  at  any  point,  then  a 
lighter  pattern  will  be  used.  Suitable 
selection  of  these  four  breakpoint 
count  values  allows  users  to  turn  one 
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or  more  of  the  patterns  on  or  off  or  to 
vary  the  thickness  of  the  various 
count  “regions.”  Figure  1,  right,  for 
example,  shows  a  count  selection 
that  disables  all  patterns  except  black 
and  white  for  a  crisp  representation 
of  the  Mandelbrot  set  itself. 

Finally,  the  dialog  allows  users  to 
choose  one  of  three  pen  sizes  using 
the  Radio  buttons  in  the  lower-left 
corner  of  the  box.  The  default  selec¬ 
tion  is  for  a  2  X  2  pen.  In  general,  I 
use  the  4X4  pen  when  exploring  a 
new  region  for  the  first  time.  This 
provides  a  quick,  though  "chunky” 
plot.  If  the  image  looks  suitably  inter¬ 
esting,  I  continue  my  explorations  us¬ 
ing  the  finer  2X2  pen.  The  1X1 
pen  is  most  suitable  for  producing 
high-quality  images  of  the  boundary 
of  the  Mandelbrot  set,  as  in  Figure  1. 

Once  the  user  clicks  the  OK  button 
at  the  bottom  of  the  dialog  box,  the 
Mandelbrot  window  appears  and 
drawing  begins.  If  at  any  time  you 
aren’t  satisfied  with  the  image  being 
generated,  you  can  either  click  on 
New  Plot  to  return  to  the  Parameters 
dialog  or  on  Quit  to  exit  from  the 
program. 

The  central  core  of  any  Macintosh 
application  is  the  event  loop.  In  most 
Macintosh  programs,  the  trap  _Gef- 
Ne?dEvent  is  polled  continually  to  de¬ 
termine  if  the  user  has  pressed  a  key 
on  the  keyboard  or  clicked  the  mouse 
(among  other  possible  user-initiated 
events).  In  this  program,  the  event 
loop  is  executed  at  the  end  of  each 
Mandelbrot  scan  line  to  determine  if 
the  user  has  clicked  either  of  the 
above  buttons. 

I  should  note  one  final  feature  of 
the  program.  In  the  original  version 
of  the  program,  the  pen  pattern  was 
set  and  each  point  plotted  using 
QuickDraw's  _ Line  command  as  soon 
as  the  iteration  for  each  point  was 
completed.  I  found,  however,  that 
plotting  ran  about  20  percent  quicker 
if  I  deferred  the  actual  drawing  until 
forced  to  by  a  change  in  the  pen  pat¬ 
tern.  You  can  force  the  program  to 
plot  each  point  as  it’s  calculated  by 
holding  down  the  mouse  when  the 
program  first  launches. 

DDJ 


Figure  1:  Full  Mandelbrot  at  1  X  1  resolution 


2  H  2 :  151  seconds 


Figure  2:  Full  Mandelbrot  at  2X2  resolution 


2  H  2 :  244  seconds 


Nem  Plot 


Figure  3:  Flames  under  an  alien  sun 
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A  Digital  Dissolve 
for  Bit-  Mapped 
Graphics  Screens 


As  high-resolution,  bit-map¬ 
ped  displays  become  more 
popular,  computer  screens 
are  beginning  to  look  like  movie 
screens.  Using  fast  bit-transfer  sub¬ 
routines,  programs  can  pan,  zoom, 
cut  between  images  in  the  blink  of  an 
eye,  and  even  animate  in  real  time. 
All  these  effects  use  raw  processor 
power  to  copy  bit  images  as  quickly 
as  possible.  But  how  about  another 
standard  film  technique:  dissolve 
shots?  How  can  a  program  fade  from 
one  bit-mapped  image  to  another? 
This  article  describes  a  way  to  do  this 
very  rapidly. 

In  the  analog  video  world,  fading 
from  one  image  to  another  is  easy: 
You  just  mix  two  images,  bringing  the 
new  image's  intensity  up  while  de¬ 
creasing  the  other’s.  In  the  more  dis¬ 
crete  software  world,  color  or  gray¬ 
scale  displays  can  be  dissolved  by 
computing  a  weighted  average  of  the 
old  and  new  values  for  each  pixel, 
then  varying  the  weighting  over  time, 
much  like  with  analog  video. 

Dissolving  monochrome  bit¬ 
mapped  images  is  a  different  prob¬ 
lem.  You  can’t  sum  x  percent  of  one 
pixel’s  bit  and  (100— x)percent  of  an¬ 
other’s.  There's  too  little  variation 
per  pixel  to  make  a  smooth  transition 
from  one  image's  pixel  to  another's. 
Although  some  displays  have  more 
than  one  bit  of  information  per  ele¬ 
ment,  they  still  can’t  be  faded  by 
weighted  averaging.  For  instance,  a 


Mike  Morton,  c/o  Lotus  Development 
Corp.,  161  First  St.,  Cambridge,  MA  02142 


by  Mike  Morton 


How  can  one  bit¬ 
mapped  image  fade  to 
another? 


24  X  80-character  display  has  values 
that  can’t  be  averaged  in  the  same 
way  as  color  values  or  gray-scale  lev¬ 
els  can.  (Can  you  imagine  a  screen 
that  faded  a  0  into  a  9  by  displaying 
all  the  digits  in  between  in  sequence?) 

If  monochrome  bit  maps  (and  some 
other  displays)  can’t  be  averaged, 
how  can  they  be  dissolved?  One  solu¬ 
tion  is  to  copy  pixels  (or  characters  or 
whatever)  to  the  screen  in  a  more-or- 
less  random  order.  This  is  easier  said 
than  done:  unlike  most  problems  in¬ 
volving  random  numbers,  this  one 
requires  a  random  generator  that 
produces  each  desired  value  exactly 
once. 

Instead  of  producing  a  random  se¬ 
quence  of  coordinate  pairs  in  an  ar¬ 
ray  of  pixels,  you  can  simplify  the 
problem  to  a  one-dimensional  task  by 
numbering  each  pixel  starting  with 
zero.  If  you  can  produce  the  pixel 
numbers  in  a  random  order,  you  can 
use  that  to  copy  the  corresponding 
pixels  to  a  screen  in  a  random  order 
and  create  a  dissolve  effect. 

An  analogous  problem  is  a  pro¬ 
gram  to  deal  a  deck  of  cards.  If  suits 
are  numbered  0  to  3  and  cards  from  0 
to  12  then,  much  like  the  pixel-num¬ 


bering  idea,  you  want  to  produce  52 
unique  coordinate  pairs  from  (0,0)  to 
(3,12).  If  you  can  produce  a  random 
sequence  of  integers  from  0  to  51, 
then  for  each  sequence  element  E, 
you  can  compute 

suit  =  E/13 
card  =  E  mod  13 

A  common  method  for  scrambling 
a  set,  such  as  the  numbers  0  to  51,  is  to 
put  the  elements  in  an  array  and 
scramble  the  array  by  picking  two 
random  elements  repeatedly  and 
swapping  them.  This  method  has 
limits,  though:  How  can  you  shuffle  a 
million  cards?  To  dissolve  a 
1, 024  X  1,024-pixel  monochrome  bit 
map,  you  need  the  1,048,576  pixel 
numbers  scrambled.  The  storage  de¬ 
mands  of  the  array  method  are  too 
much  for  many  situations. 

A  Software  Sequence 
Generator 

The  software  magic  that  avoids  using 
giant  arrays  is  based  on  a  simple  hard¬ 
ware  circuit.  Figure  1,  page  49,  shows 
an  8-bit  shift  register.  At  each  cycle, 
selected  bits  are  sent  through  an  N- 
way  exclusive-OR  gate,  the  entire  con¬ 
tents  of  the  register  are  shifted  left  by 
one  bit,  and  the  result  of  the  exclusive- 
OR  feeds  in  as  the  new  rightmost  bit. 
If  the  correct  bit  posit  ions  are  fed  into 
the  exclusive-OR,  the  register  will 
cycle  through  all  possible  nonzero 
combinations.  If  you  interpret  the 
register  contents  as  a  number,  the  se¬ 
quence  produces  each  of  the  num- 
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bers  from  1  to  255  in  a  fairly  random 
sequence.  (How  random  is  it?  Not 
very,  actually.  It  fails  many  statistical 
tests  for  randomness.  But  the  circuit 
has  a  software  analog  that  is  easy  to 
code  and  runs  so  fast  that  the  imper¬ 
fection  can  be  overlooked.)  For  any 
size  of  register,  you  can  exclusive-OR 
certain  bit  positions  to  make  the  regis¬ 
ter  cycle  through  all  nonzero  combi¬ 
nations.  A  given  size  of  register  may 
have  several  correct  patterns  of  bit 
positions;  Table  1,  page  50,  shows  one 
pattern  for  each  register  size  from  2  to 
32.  (Also  see  inset  article  "Those  Magic 
Constants”  on  page  55.) 

An  N-bit  register  produces  the 
numbers  from  1  through  2N— 1.  My 
original  goal  was  to  produce  the 
numbers  from  0  through  the  size  of 
the  pixel  array  to  be  copied.  I’ll  ex¬ 
plain  how  to  reconcile  this  differ¬ 
ence  as  soon  as  I’ve  turned  this  hard¬ 
ware  sequence  into  software. 

You  could  code  a  routine  to  mimic 
the  circuit  exactly,  but  there's  a 
slightly  different  algorithm  that  is 
much  faster.  It  uses  a  "mask”  that 
corresponds  to  the  bits  selected  in  the 
circuit.  For  an  8-bit  “register” — pro¬ 
ducing  values  from  1  to  255 — one  pos¬ 
sible  mask  is  10111000,  or  $B8.  Each 
sequence  element  is  derived  from 
the  previous  one  with  this  method: 
Shift  the  original  value  right  (not  left) 
by  one  bit;  if  a  ”1”  bit  falls  off  the  edge 
because  of  the  shift,  exclusive-OR  the 
mask  into  the  value.  In  assembly  lan¬ 
guage,  this  can  be  done  very  easily. 
The  following  68000  code  takes  a  se¬ 
quence  element  in  DO  and  produces 
the  next  one  in  DO  using  the  mask 
previously  put  in  D7. 


LSR  n,  DO 
BCC.S  noXOR 


EOR  D7,D0 


noXOR: 


;  shift  this  sequence 
element  right  1  bit 
;  if  no  bit  falls  into 
Carry,  skip  the 
XOR . . . 

; . .  .  else  XOR  the 
mask  into  the  new 
value 

;  (now  process  the 
new  element  in  DO) 


In  C,  it’s  not  as  easy  to  express  the 
idea  of  a  bit  falling  off  the  edge  dur¬ 
ing  a  shift,  so  the  code  is  more  long- 
winded: 


if  (X&l)  /*  is  the  low  bit  set?  * / 

X  =  (X>>l)mask; 


/*  yes:  shift  value  and  XOR  in  the 
mask  */ 

else  X  =  (X>  >  1); 

/*  no:  just  shift  the  value  */ 

A  First  Attempt 

Now,  with  a  software  sequence  gen¬ 
erator  and  a  way  to  map  that  se¬ 
quence  onto  an  array  of  pixels  (or 
whatever),  you  can  write  a  first  cut  at 
the  dissolve  algorithm.  The  idea  is  to 
find  a  "register  width”  for  a  se¬ 
quence  generator  that  generates  at 


least  as  many  numbers  as  there  are 
pixels.  (The  highest-numbered  se¬ 
quence  elements  don’t  map  to  pixels 
in  the  array — that’s  OK,  they'll  be  dis¬ 
carded.)  Figure  2,  below,  illustrates 
this  approach. 

As  the  main  loop  generates  each  se¬ 
quence  element,  the  element  is 
mapped  to  a  pair  of  coordinates,  just 
as  in  the  card-dealing  program.  Coor¬ 
dinates  outside  the  array  are  ignored, 
whereas  those  in  bounds  are  copied. 
The  loop  ends  when  the  sequence  re- 


Figure  1:  On  8-bit  hardware  sequence  generator.  The  mask  is  10111000 
(base  2). 
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(0  is  a  special  case, 
not  produced 
by  the  sequence) 

-► 

1 
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(pixel  numbers  1 8 
through  31  are  ignored) 
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7 
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13 
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16 

17 

Figure  2:  Mapping  sequence  elements  into  a  pixel  array  using  the 
formulas  row  =  N/width  and  column  =  N  mod  width.  Values  of  row  >  = 
height  are  ignored. 


Five-bit  sequence  element 


case,  not  produced 
by  the  sequence) 


N=14,  for  example,  maps 
to  row=2,  column=6.  This 
sequence  element  is  ignored 
because  the  column  number 
is  >  =  width. 


Figure  3:  Mapping  sequence  elements  into  a  pixel  array  using  the 
formulas  row  =  N>>rowshift  (rowshift  =  3)  and  column  —  N&colmask 
(colmask  =  00111  base  2).  Values  of  row  >  =  height  and  values  of  column 
>  =  width  are  ignored. 
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turns  to  the  original  element.  The 
function  is  shown  in  Table  2,  page  52. 
This  function  finds  the  total  number 
of  pixels  to  copy  and  then  the  num¬ 
ber  of  the  highest  pixel. 

The  correct  width  of  sequence  gen¬ 
erator  is  found  with  a  function  called 
bitwidthf  ).  Given  a  number,  this 
function  just  tells  you  how  wide  a 
register  must  be  to  hold  the  number. 
In  other  words:  What  width  of  gener¬ 
ator  is  needed  to  produce  at  least  as 
many  pixel  numbers  as  needed?  The 
function  bitwidth  is  shown  in  Table  3, 
page  54. 

Once  the  width  of  the  register  has 
been  found,  the  randmasks[  ]  array  is 
used  to  find  the  magic  value  used  to 
generate  the  sequence.  The  sequence 
length  can  be  nearly  twice  as  long  as 


the  number  of  pixels  to  copy  because 
the  length  must  be  a  power  of  2.  The 
10]  and  [1]  elements  of  the  array 
aren't  defined — the  smallest  genera¬ 
tor  is  2  bits  wide. 

I  haven’t  specified  the  copyf  )  rou¬ 
tine — the  routine  that  copies  a  pixel 
from  one  pixel  array  to  another.  It 
will  depend  on  which  computer 
you’re  using;  I’ll  talk  more  about  this 
later.  Remember  that  copy( )  doesn't 
need  to  copy  a  pixel  to  the  screen;  it 
can  copy  a  character  or  any  array 
element. 

Because  the  sequence  never  pro¬ 
duces  a  zero  value,  the  program  has 
to  do  the  (0,0) th  element  explicitly. 
Eagle-eyed  users  will  notice  that  the 
top-left  pixel  is  always  the  first  or  last 
to  dissolve  in. 

This  method  works,  but  it’s  not  fast 
enough  for  many  purposes.  What 
makes  it  so  slow  is  the  division  and 


Width 

Mask  (hex) 

Produces  from  1  to 

2 

3 

3 

3 

6 

7 

4 

C 

15 

5 

14 

31 

6 

30 

63 

7 

60 

127 

8 

B8 

255 

9 

110 

511 

10 

240 

1023 

11 

500 

2047 

12 

CA0 

4095 

13 

1B00 

8191 

14 

3500 

16383 

15 

6000 

32767 

16 

B400 

65535 

17 

12000 

131071 

18 

20400 

262143 

19 

72000 

524287 

20 

90000 

1048575 

21 

140000 

2097151 

22 

300000 

4194303 

23 

420000 

8388607 

24 

D80000 

16777215 

25 

1200000 

33554431 

26 

3880000 

67108863 

27 

7200000 

134217727 

28 

9000000 

268435455 

29 

14000000 

53687091 1 

30 

32800000 

1073741823 

31 

48000000 

2147483647 

32 

A3000000 

4294967295 

For  any  given  width  (w),  there  is  usually  more  than  one  mask  that  produces  all  values 
from  1  to  2*— 1 .  These  particular  masks  are  chosen  because  they  can  all  be  packed 
into  a  byte.  See  Listing  One  for  an  example  of  how  to  pack  and  unpack  them. 


Table  1:  Masks  to  produce  pseudorandom  sequences  for  registers  from  2 
to  32  bits  wide 


modulo  computations: 

row  =  element  /  width; 
column  =  element  %  width; 

In  assembly  language,  you  can  often 
do  both  of  these  with  one  instruction, 
but  it’s  still  awfully  slow.  A  divide  in¬ 
struction  on  an  8-MHz  68000  takes 
about  17  microseconds.  Is  there  a  bet¬ 
ter  way?  (Of  course,  or  I  wouldn't 
have  brought  up  the  problem.) 

A  Faster  Method 

To  make  it  faster,  you  can  use  a  po¬ 
tentially  longer  sequence  but  use  a 
mapping  that  is  faster  than  the  di- 
vide-and-modulo  computation.  Fig¬ 
ure  3,  page  49,  illustrates  this  method. 
Both  the  height  and  width  of  the  ar¬ 
ray  are  rounded  up  to  the  next 
power  of  2.  A  sequence  element  is 
then  broken  up  into  row  and  column 
numbers  by  bit  operations,  which 
are  much  faster  than  divide  and 
modulo.  With  this  method,  the  num¬ 
ber  of  sequence  elements  generated 
can  be  almost  four  times  the  number 
of  pixels — twice  as  bad  as  the  worst 
case  for  the  simpler  algorithm.  But 
generating  elements  is  so  much  fast¬ 
er  than  division  that  the  new  method 
is  still  faster.  This  algorithm  is  shown 
in  Table  4,  page  54.  It  is  really  a  lot  like 
the  original  routine.  The  difference  is 
that  the  mapping  is  faster  and  the  se¬ 
quence  may  be  longer  because  the 
mapping  discards  more  elements  of 
the  sequence. 

At  one  level,  that's  all  there  is  to  it. 
You  just  have  to  write  a  copyi  )  rou¬ 
tine  to  copy  a  single  pixel  (or  whatev¬ 
er)  and  optimize  the  code  so  the  dis¬ 
solve  effect  happens  quickly.  These 
tasks  may  not  be  simple  for  some  ma¬ 
chines,  especially  if  you’re  trying  to 
quickly  copy  tens  of  thousands  or 
perhaps  a  million  pixels  on  a  high- 
resolution  screen. 

Every  machine  will  probably  need 
a  slightly  different  copyi )  routine  to 
handle  the  quirks  of  your  graphics 
hardware  or  software.  In  the  Macin¬ 
tosh,  for  example,  a  bit  map  (such  as 
the  image  to  display  or  the  screen  to 
copy  it  to)  is  an  array  of  pixels  laid  out 
in  rows  in  memory.  Indexing  into  it  is 
done  in  just  the  same  way  as  any  lin¬ 
ear  array  being  treated  as  a  two-di¬ 
mensional  array.  Although  most  ma¬ 
chines  treat  bit  indexing  differently 
from  byte  indexing,  it  may  be  helpful 


50 

754 


Dr.  Dobb's  Journal,  November  1986 


dissolvel  (height,  width) 

/*  first  version  of  the  dissolve  algorithm  7 

int  height,  width; 

/ 

/*  number  of  rows,  columns  7 

i 

int  pixels,  lastnum; 

/*  number  of  pixels;  last  pixel’s  number  7 

int  reg  width; 

/*  “width"  of  sequence  generator  7 

register  long  mask; 

/*  mask  to  XOR  with  to  create  sequence  7 

register  unsigned  long  element; 

/*  one  element  of  random  sequence  7 

register  int  row,  column; 

/*  row  and  column  numbers  for  a  pixel  7 

/*  Find  smallest  register  that  produces  enough  pixel  numbers  7 

pixels  =  height  *  width; 

/*  compute  number  of  pixels  to  dissolve  7 

lastnum  =  pixels- 1; 

/*  find  last  element  (they  go  0  . .  lastnum)  7 

regwidth  =  bitwidth  (lastnum); 

/*  how  wide  must  the  register  be?  7 

mask  =  randmasks  [regwidth]; 

/’Which  mask  is  for  that  width?  7 

/*  Now  cycle  through  all  sequence  elements.  7 

element  =  1 ; 
do{ 

row  =  element  /  width; 

/*  1st  element  (could  be  any  nonzero)  7 

/*  how  many  rows  down  is  this  pixel?  7 

column  =  element  %  width; 

/*  and  how  many  columns  across?  7 

if  (row  <  height) 

/*  does  this  seq  element  fall  in  the  array?  7 

copy  (row,  column); 

/*  yes:  copy  the  (r,c)th  pixel  7 

/*  Compute  the  next  sequence  element  7 

if  (element  &  1 ) 

/*  is  the  low  bit  set?  7 

element  =  (element  > >1 )  mask;  /*  yes:  shift  value,  XOR  in  mask  7 

else  element  =  (element  >>1); 

/*  no:  just  shift  the  value  7 

}  while  (element !  =  1); 

/*  loop  until  we  return  to  original  element  7 

copy  (0, 0); 

/*  kludge:  the  loop  doesn’t  produce  (0,0)  7 

} 

/*  end  of  dissolve^ )  7 

Table  2:  First  attempt  at  dissolve  algorithm 

DIGITAL  DISSOLVE 


to  keep  all  offsets  as  bits  and  convert 
to  bytes  only  when  necessary.  Thus, 
on  the  Mac,  if  DO  contains  the  bit  off¬ 
set  of  the  first  bit  of  the  array  in  mem¬ 
ory,  and  D1  and  DZ  have  the  row  and 
column  numbers,  you  can  set  the 
(. Dl,D2)th  bit  with  the  code  fragment 
shown  in  Table  S,  page  54. 

All  the  arithmetic  in  Table  5  is  in 
terms  of  bits  until  the  LSR  extracts  the 
address,  which  then  has  to  be  moved 
to  an  address  register  to  be  useful.  Bit 
numbering  in  the  Mac  screen  isn’t 
like  byte  numbering  (byte  numbers 
increase  as  you  move  to  the  right 
across  the  screen;  bit  numbers  de¬ 
crease  within  each  byte),  so  the  bit 
number  in  D3  has  to  be  converted 
with  the  NOT.  Finally,  the  BSET  sets 
the  bit  in  the  correct  byte.  This  idea  of 
mapping  a  row  and  column  in  the 
array  to  an  address  in  memory  is  the 
heart  of  any  copy( )  routine  for  a  bit 
map.  You  use  it  to  test  the  bit  in  the  bit 
map  being  dissolved  in  and  to  set  or 
clear  the  corresponding  bit  in  the 
screen  memory.  For  a  24X80-charac- 
ter  display,  it's  similar:  the  mapping 
takes  the  row  and  column  and  index¬ 
es  into  a  character  array  in  memory 
to  get  the  character  to  copy  to  the 
screen. 

The  Macintosh  Dissolve 
Routine 

Listing  One,  page  88,  is  a  dissolve  rou¬ 
tine  for  the  Mac.  Because  its  calling 
interface  resembles  that  of  the  stan¬ 
dard  Mac  bit-transfer  routine  called 
CopyBits,  it's  called  DissBits.  It  copies 
the  contents  of  one  rectangle  in  a  bit 
map  to  another  rectangle  in  another 
bit  map.  In  the  Mac's  graphics  subsys¬ 
tem,  a  bit  map  is  a  data  structure  that 
specifies  the  base  address  of  a  chunk 
of  graphical  data  and  imposes  a  coor¬ 
dinate  system  on  that  chunk.  For 
more  information,  see  the  chapter  on 
QuickDraw  in  Inside  Macintosh  by 
Caroline  Rose  et  al. 

DissBits  is  not  intended  to  present  a 
clear  example  of  the  algorithm;  in¬ 
stead,  the  main  loop  contains  the 
copy (  )  code  in-line  for  maximum 
speed.  DissBits  actually  has  three  dif¬ 
ferent  loops  and  automatically  uses 
the  fastest  one  it  can.  The  first  loop  is 
the  general  case;  with  some  coding 
tricks,  it  can  dissolve  at  the  rate  of 
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int  bitwidth  (N)  /*  find  “bit-width”  needed  to  represent  N  7 

unsigned  int  N;  /*  number  to  compute  the  width  of  7 


int  width  =  0; 

while  (N  I  =  0)  { 

N  >>=  1; 

width +4-; 

} 

return  (width); 

} 


/*  initially,  no  bits  needed  to  represent  N  7 

/*  loop  'til  N  has  been  whittled  down  to  0  7 
/*  shift  N  right  1  bit  (N.B.:  N  is  unsigned)  7 
/*  and  remember  how  wide  N  is  7 
/*  end  of  loop  shrinking  N  down  to  nothing  7 

/*  return  bit  positions  counted  7 
/*  end  of  bitwidth( )  7 


Table  3:  The  function  bitwidth 

dissolve2  (height,  width) 

/*  fast  version  of  the  dissolve  algorithm  7 

int  height,  width; 

/ 

/*  number  of  rows,  columns  7 

\ 

int  rwidth,  cwidth; 

/*  bit  width  for  rows,  for  columns  7 

int  regwidth; 

/*  “width”  of  sequence  generator  7 

register  long  mask; 

/*  mask  to  XOR  with  to  create  sequence  */ 

register  int  rowshift; 

/*  shift  distance  to  get  row  from  element  7 

register  intcolmask; 

/*  mask  to  extract  column  from  element  7 

register  unsigned  long  element; 

/*  one  element  of  random  sequence  7 

register  int  row,  column; 

/*  row  and  column  for  one  pixel  7 

/*  Find  the  mask  to  produce  all  rows  and  columns.  */ 

rwidth  =  bitwidth  (height); 

/*  how  many  bits  needed  for  height?  7 

cwidth  =  bitwidth  (width); 

/*  how  many  bits  needed  for  width?  7 

regwidth  =  rwidth  +  cwidth; 

/*  how  wide  must  the  register  be?  7 

mask  =  randmasks  [regwidth]; 

/*  which  mask  is  for  that  width?  7 

/*  Find  values  to  extract  row  and  col  numbers  from  each  element.  7 

rowshift  =  cwidth; 

/*  find  dist  to  shift  to  get  top  bits  (row)  7 

colmask  =  (1  <<cwidth)— 1 ; 

/*  find  mask  to  extract  bottom  bits  (col)  7 

/*  Now  cycle  through  all  sequence  elements.  7 

element  =  1 ; 
do  { 

/*  1st  element  (could  be  any  nonzero)  7 

row  =  element  >>  rowshift; 

/*  find  row  number  for  this  pixel  7 

column  =  element  &  colmask; 

/*  and  how  many  columns  across?  7 

if  ((row  <  height) 

/*  does  element  fall  in  the  array?  7 

&&  (column  <  width)) 

/* . . .  must  check  row  AND  column  7 

copy  (row,  column); 

/*  in  bounds:  copy  the  (r,c)th  pixel  7 

/*  Compute  the  next  sequence 

element  7 

if  (element  &  1) 

/*  is  the  low  bit  set?  7 

element  =  (element  >>1)  mask 

/*  yes:  shift  value,  XOR  in  mask  7 

else  element  =  (element  >>1); 

/*  no:  just  shift  the  value  7 

}  while  (element !  =  1); 

/*  loop  until  we  return  to  original  element  7 

copy  (0,  0); 

/*  kludge:  element  never  comes  up  zero  7 

} 

/*  end  of  dissolve2( )  7 

Table  4:  A  faster  dissolve  algorithm 


MULU 

<WIDTH>,D1 

convert  row  number  to  bit  offset  of  row 

ADD.L 

D1,D0 

compute  bit  offset  of  first  bit  of  the  row 

ADD.L 

D2,D0 

index  into  the  row  to  get  the  bit  offset 

MOVE.L 

D0,D3 

set  aside  the  final  bit  offset . . . 

LSR.L 

#3,  DO 

. . .  and  find  the  byte  address  from  it 

MOVE.L 

DO, A0 

copy  that  to  an  address  register 

NOT.B 

D3 

convert  the  bit  index  to  68000-style 

BSET 

D3,(A0) 

set  the  D3th  bit  of  AO’s  byte 

Table  S:  Code  fragment  to  set  (D1,D2  )th  bit  on  the  Mac 


about  49  microseconds  per  pixel. 
When  both  the  bit  maps  have  a  width 
that  is  a  power  of  2,  then  the  MULU 
instruction  in  Table  5  can  be  done 
with  a  shift  instead.  In  this  case,  the 
algorithm  uses  a  different  loop  that  is 
about  20  percent  faster.  As  a  third  and 
final  optimization,  the  loop-choosing 
code  notices  when  the  pixel  array  be¬ 
ing  copied  is  exactly  the  width  of  the 
bit  map  it's  contained  in.  (This  case  is 
common  because  it  includes  doing  a 
full-screen  dissolve.)  In  this  case,  the 
check  for  the  column  being  in  bounds 
can  be  removed  and  some  other  tricks 
can  be  done.  In  this  "high  gear,”  the 
code  runs  at  19  microseconds  per  pix¬ 
el;  it  can  fade  the  whole  Mac  screen  in 
about  3.4  seconds. 

Suggestions 

Those  of  you  writing  for  other  ma¬ 
chines  may  not  want  to  wade 
through  the  details  of  the  Macintosh 
code.  Besides  the  optimizations 
above,  here  are  some  things  you  may 
want  to  try: 

•  All  my  code  uses  32-bit  long  words; 
this  slows  it  down  considerably  but  is 
needed  for  cases  in  which  there  are 
more  then  216  bits  to  dissolve.  If  your 
machine  has  fewer  than  64K  pixels, 
you  can  always  use  16-bit  integers.  Or 
you  can  code  two  loops  and  have  the 
routine  choose  the  right  one. 

•  You  can  optimize  when  either  the 
width  or  the  height  of  the  array  is  a 
power  of  2.  In  this  case,  you  know  the 
column  or  row  (respectively)  extract¬ 
ed  from  the  sequence  element  is  al¬ 
ways  in  bounds. 

•  You  can  test  the  upper  bits  (the  row, 
as  I’ve  split  things  up)  of  the  sequence 
element  without  extracting  them 
first.  Just  compare  it  to  1  plus  the 
maximum  allowed  value,  shifted 
into  position. 

•  In  assembly  language,  it's  easy  to  de¬ 
tect  when  the  loop  has  finished  if  the 
last  time  through  the  loop  the  se¬ 
quence  element  is  1.  When  you  shift 
the  1  right,  you’ll  get  a  carry  and  the 
result  will  be  0.  This  carry-and-zero 
occurs  only  if  the  element  was  1.  (On 
some  machines,  a  single  instruction 
will  detect  when  both  of  these  condi¬ 
tions  are  true — for  instance,  the 
68000’s  BLS  (branch  less  than) 
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flip:  A  function  to  return  a  random  boolean  value  in  DO.b. 

D7  is  used  to  keep  the  current  state  of  the  “shift  register”. 

The  register  is  1 6  bits,  so  the  pattern  of  bits  repeats  after  64K  calls. 


flip: 

LSR.W 

#1,  D7 

;  shift  D7  right  one  bit 

SCS 

DO 

;  set  DO  to  flag  whether  a  bit  carried 

BCC.S 

end 

;  if  no  bit  carried,  D7  is  new  element:  done 

EORI.W 

#$B400,D7 

;  else  XOR  in  magic  value  for  new  one 

end: 

RTS 

;  return  with  DO.b  =  random  boolean 

Table  6:  Sequence  generator  for  coin-flip  subroutine 


Random  Bits  vs.  Random  Bytes 


instruction.) 

•  When  there’s  no  carry,  the  mask 
isn't  XORed  into  the  next  sequence  el¬ 
ement,  and  the  topmost  bit  of  the 
new  element  is  0.  This  means  that  the 
row  (in  my  version)  is  guaranteed  to 
be  in  bounds.  Your  branch-on-no-car- 
ry  can  take  you  to  the  start  of  the  loop 
as  usual  but  bypass  the  check  for  the 
row  being  in  bounds. 

•  Because  both  the  row  and  column 
must  be  checked  to  see  if  they’re  in 
bounds,  extract  and  check  one  before 
taking  the  time  to  extract  the  other. 

•  The  row  number  is  extracted  by 
shifting  the  sequence  element  to  the 
right,  but  this  result  is  soon  multiplied 
by  the  width  of  the  bit  map  when 
finding  the  bit.  If  the  width  is  a  multi¬ 
ple  of  a  power  of  2,  part  of  the  multi¬ 
ply  is  just  undoing  some  of  the  effect 
of  the  shift.  Because  longer  shifts  take 
more  time  on  some  processors,  you 
can  reduce  both  the  shift  and  the 
amount  to  multiply  by — if  you  are 
willing  to  mask  the  value,  too. 

There  are  some  nagging,  real- 
world  problems.  A  few  I  had  trouble 
with  were: 

•Don’t  forget  the  (0,0) th  element  of 
the  array.  Because  the  sequence  nev¬ 
er  produces  the  value  0,  this  won't 
get  done  by  the  loop.  You  have  to 
make  it  a  special  case  outside  the 
loop. 

•  The  algorithm  breaks  down  for  tiny 
bit  maps  because  the  sequence  gener¬ 
ator  doesn’t  work  for  small  widths  of 
registers.  If  you  can  find  a  way  to  gen¬ 
eralize  it,  I’d  like  to  hear  about  it.  (My 
solution  was  to  detect  this  case  and 
hand  it  off  to  the  CopyBits  routine.) 

•  Your  machine’s  graphics  software 
will  probably  not  be  able  to  copy 
thousands  of  pixels  quickly  one  at  a 
time,  and  your  copy(  )  routine  will 
have  to  be  in  assembly  language  and 
directly  alter  screen  memory.  Be 
careful  to  check  exactly  how  this  in¬ 
terferes  with  the  graphics  software. 
For  instance,  DissBits  must  hide  the 
Mac  cursor  during  the  time  it’s  direct¬ 
ly  accessing  screen  memory. 

There  are  a  lot  of  variations  I 
haven’t  tried  yet;  I'd  be  interested  to 
hear  from  anyone  who  experiments 
with  these  ideas: 

•  My  copy(  )  routine  for  bit  maps  tests 


The  shift-and-XOR  method  the  dis¬ 
solve  uses  to  generate  pseudorandom 
numbers  isn't  very  random.  If  you 
watch  some  sizes  of  rectangles  being 
dissolved,  you'll  see  ephemeral  pat¬ 
terns.  Surprisingly,  though,  the  pat¬ 
tern  of  bits  shifted  off  the  end  of  the 
register  is  random.  In  The  Art  of  Com¬ 
puter  Programming,  Knuth  discusses 
the  difference  between  random  bits 
and  numbers  composed  of  the  bits. 

Many  programmers  writing  games 
or  other  programs  wind  up  flipping  a 
coin  with  something  like  the  BASIC 


When  the  sequence  generator  shifts 
a  1  bit  out  of  the  register,  it  exclusive- 
ORs  a  magic  constant  into  the  run¬ 
ning  value  of  the  register.  Different 
register  widths  require  different  con¬ 
stants;  Table  1  gives  a  list  of  some  con¬ 
stants  that  work.  How  do  you  find 
these  values? 

The  basis  for  the  generator  is  rooted 
in  the  theory  of  prime  polynomials. 
Those  of  you  who  remember  your  ab¬ 
stract  algebra  course  may  be  interest¬ 
ed  in  pages  209—213  of  Numerical 
Recipes:  The  Art  of  Scientific  Comput¬ 
ing  by  William  H.  Press  et  al.  and 
pages  29—31  of  The  Art  of  Computer 
Programming  by  Donald  E.  Knuth. 

If  you  prefer  direct  evidence,  it’s 
not  hard  to  write  a  program  to  search 


statement  IF  RND  <  0.5  THEN.  .  .  . 
This  is  a  lot  of  effort  to  produce  a  ran¬ 
dom  bit.  You  can  write  a  short,  fast 
coin-flip  subroutine  using  the  se¬ 
quence  generator  in  Table  6,  above. 
Remember  to  initialize  D7  to  any 
nonzero  value.  Zero  traps  the  sub¬ 
routine  in  a  demon  state,  producing 
nothing  but  zero  bits. 

Here’s  a  puzzle:  Change  the  func¬ 
tion  so  it  doesn’t  need  D7  initialized. 
You  can  write  a  "self-starting”  ver¬ 
sion  that  is  no  slower  and  no  longer 
than  the  original. 


for  the  constants.  I  set  a  microcom¬ 
puter  to  work  on  the  problem,  using 
the  slower  method  of  directly  simu¬ 
lating  the  type  of  circuit  shown  in 
Figure  1  (I  didn’t  know  about  the  soft¬ 
ware  version  at  that  point).  It  took 
about  two  CPU-weeks. 

Assuming  I  haven’t  made  tran¬ 
scription  errors  in  Table  1,  you 
shouldn't  have  much  reason  to 
search  for  the  constants  yourself. 
(Perhaps  some  constants  are  more 
random  than  others?)  The  table 
should  give  you  plenty  of  informa¬ 
tion — at  least  until  someone  pro¬ 
duces  billion-pixel  displays.  But  just 
in  case,  Press  et  al.  give  constants  for 
registers  up  to  100  bits  wide. 


Those  Magic  Constants 
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DIGITAL  DISSOLVE 


a  bit  in  the  source  and  then  branches 
to  either  set  or  clear  a  bit  in  the  desti¬ 
nation.  If,  before  the  dissolve,  the  des¬ 
tination  is  exclusive-ORed  into  the 
source,  the  source  becomes  a  bit  map 
of  the  bits  that  differ  between  the 
two  images.  Then  the  copy(  )  routine 
still  has  to  test  the  source  but  toggles 
the  destination  bit  only  when  the 
source  bit  is  1 — this  means  the  ad¬ 
dress  calculation  for  the  destination’s 
bit  can  often  be  skipped.  If  your 
graphics  subsystem  supports  logical 
operations  (such  as  exclusive-OR)  on 
block  copies,  the  first  XOR  pass  can  be 
very  fast.  Finally,  if  you  do  a  third 
block-XOR  from  the  destination  back 
to  the  source,  the  net  effect  of  the 
three  XORs  is  to  swap  the  two  images, 
so  your  destination  is  preserved  in 
the  source  and  can  be  restored  easily. 
•  Because  the  loop's  state  is  controlled 
by  one  variable  (the  sequence  ele¬ 
ment),  it  should  be  easy  to  write  a  par¬ 
tial  dissolve  by  changing  the  starting 
or  ending  elements  of  the  sequence. 


This  would  allow  you  to  "blend”  im¬ 
ages,  create  effects  like  the  Star  Trek 
transporter,  and  so  forth. 

•  Because  all  this  came  from  a  hard¬ 
ware  circuit,  how  about  hardware 
support  for  the  dissolve?  Many  ma¬ 
chines  have  custom  hardware  to  sup¬ 
port  raster  operations;  why  not  sup¬ 
port  this  one? 

•  Instead  of  copying  graphical  data, 
variations  on  the  dissolve  theme 
could  perform  standard  Boolean  op¬ 
erations  with  two  or  more  images,  in¬ 
vert  an  image,  and  so  on. 

Finally,  don’t  let  your  imagination 
be  limited  to  dissolve  subroutines. 
The  random  engine  used  in  the  dis¬ 
solve  has  other  uses.  You  can  do 
much  more  than  shuffle  a  deck  of  a 
million  cards.  For  instance,  a  pro¬ 
gram  slowly  drawing  the  Mandel¬ 
brot  set  could  draw  pixels  randomly 
so  that  the  basic  image  becomes  ap¬ 
parent  sooner,  without  having  to 
wait  for  the  entire  drawing.  In 
browsing  through  an  image  database 
with  a  slow  modem,  you  can  cancel 
an  image  without  waiting  for  it  to  be 


completely  drawn  (I  believe  this  idea 
is  Ted  Nelson’s).  As  described  in  the 
inset  article  "Random  Bits  vs.  Ran¬ 
dom  Bytes”  on  page  55,  you  can  write 
a  coin-flip  subroutine.  The  unusual 
property  of  generating  unique  values 
in  pseudorandom  order  makes  the 
sequence  generator  a  useful  tool  for 
many  applications. 
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Listing  One  (Text  begins  on  page  14.) 


Listing  1  —  set.h 

Header  to  use  the  set  manipulation  routiness  in  set.c 


1  /*  SET.H:  Header  to  use  the  set  : 

2  * 

3  *  Copyright  (c)  1986,  Allen  I.  Holub. 


All  rights  reserved 


6  #define  DEFBYTES 

7  idefine  DEFBITS 

8 

9  typedef  struct 


10 

{ 

11 

unsigned 

nbytes 

:  13; 

12 

unsigned 

compl 

:  1; 

13 

int 

nbits; 

14 

unsigned  char 

*map; 

15 

unsigned  char 

defmap [DEFBYTES] 

; 

16 

} 

17 

SET; 

18 

19 

extern 

void 

set_op 

(  int. 

SET*,  SET* 

20 

extern 

int 

set  cmp 

(  SET*, 

SET* 

); 

21 

extern 

int 

subset 

(  SET*, 

SET* 

); 

22 

extern 

int 

num  ele 

(  SET* 

); 

23 

extern 

void 

del set 

(  SET* 

); 

24 

extern 

SET 

*newset 

( 

); 

25 

26 

#define 

UNION 

0 

/*  x  is 

in 

27 

#define 

INTERSECT 

1 

/*  x  is 

in 

28 

#define 

DIFFERENCE 

2 

/*  x  is 

in 

29 

#define 

INVERT 

3 

/*  ones 

cor 

30 

#define  ASSIGN 

4 

/*  si  = 

s2 

31 

idefine 

CLEAR 

5 

/*  d  =  all 

32 

#define 

FILL 

6 

/*  d  =  all 

/*  bytes  in  def  set  (>=  1) 
/*  bits  in  default  set 


/*  Number  of  bytes  in  map 
/*  This  is  a  negative  true  set 
/*  Number  of  bits  in  map 
/*  Pointer  to  the  map 


SET*,  SET*);  /*  Routines  in  set.c 


34  #define  union (d, si, s2)  set_op(  UNION, 

35  idefine  intersection (d, si, s2)  set_op(  INTERSECT, 

36  #define  difference (d, si, s2)  set_op(  DIFFERENCE, 

37  #define  assign (d, si)  set_op(  ASSIGN, 

38  #define  invert (d, si)  set_op(  INVERT, 

39  idefine  clear (d)  set_op(  CLEAR, 

40  idefine  fill(d)  set_op(  FILL, 

41  #def ine  complement (d)  (  (d) ->compl  =  - (d) 

42 

43  #define  equivalent (si, s2)  (  set_cmp(s 

44  idefine  disjoint (si, s2)  (  set_cmp(s 

45 

46  #define  GBIT(x,s,op)  (  ( (s)->map)  [  (x)  »  3 

47 

48  #define  remove (x,s)  (  ( (x)  >=  (s)->nbits) 

49  idefine  add(x,s)  (  ( (x)  >=  (s)->nbits) 

50  idefine  ismember (x, s)  (  ( (x)  >=  (s)->nbits) 

51 

52  idefine  test (x, s)  (  (  ismember (x, s)  )  ? 


(d)->compl) 


(  set_cmp (si, s2)  ==  0  ) 
(  set_cmp(sl, s2)  ==  1  ) 


(  ( (s)->map)  [  (x)  »  3] 


(1  «  ((x)  &  0x07)) 


(  ( (x)  >=  (s)->nbits)  ?  0 
(  ( (x)  >=  (s)->nbits)  ?  addset  (x,  s) 


GBIT  (x,s  ,&= 
GBIT  (x,  s,  |  = 
GBIT  (x,  s,  & 


(  (  ismember  (x,  s)  ) 


!(  (s)->compl  )  :  (s)->compl 


End  Listing  One 
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Listing  Two 

Listing  2  —  set.c 


1  # include  <stdio.h> 

2  # include  <ctype.h> 

3  #include  <set.h> 

4 

5  extern  char  *calloc  (  int,  int  ) ; 

6 

7  /* - */ 

8 

9  #ifdef  DIAG 

10  #  define  D(x)  x 

11  #else 

12  #  define  D (x) 

13  #endif 

14 

15  #define  max(a,b)  ((a)  >  (b)  ?  (a)  :  (b) ) 

16 

17  /* - */ 

18 

19  SET  *newset() 

20  { 

21  SET  *p; 

22 

23  if  (  !  (p=  (SET  *)  calloc  (sizeof  (SET) ,  1) )  ) 

24  { 

25  fprintf (stderr, "Can't  get  memory  for  set\n") ; 

26  return  NULL; 

27  } 

28  else 

29  { 

30  p->map  =  p->defmap; 

31  p->nbytes  =  DEFBYTES; 

32  p->nbits  =  DEFBITS; 

33  } 

34  return  p; 

35  } 

36 

37  /* - */ 

38 

39  void  del set  (  set  ) 

40  SET  *set; 

41  { 

42  /*  Delete  a  set  created  with  a  previous  newset 

43  V 

44 

45  if (  set->map  !=  set->defmap  ) 

46  free (  set->map  ); 

47 

48  free (  set  ) ; 

49  } 

50 

51  /* - */ 

52 

53  static  void  enlarge (  need,  set  ) 

54  SET  *set; 

55  { 

56  /*  Enlarge  the  set  to  "need"  bytes,  filling  in  the  extra 

57  *  bytes  with  zeros. 


59 
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Listing  Two 


(Listing  continued,  text  begins  on  page  14.) 


59 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 

103 

104 

105 

106 

107 

108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 
•  119 
120 
121 
122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 


*/ 

register  char  *new; 

if(  !set  ||  need  <=  set->nbytes  ) 
return; 

D (  print f ("enlarging  %d  byte  map  to  %d  bytes\n",  set ->nbytes# need) ;) 

if (  ! (new  =  calloc(need/  1>)  ) 

fprintf (stderr, "Can't  get  memory  to  expand  set\n"); 

else 

{ 

memcpy (  new,  set->map,  set->nbytes  ) ; 

if(  set->map  !=  set->defmap  ) 
free (  set->map  ) ; 

set->map  =  new; 
set->nbytes  =  need; 
set->nbits  =  need  *  8; 

} 

} 

/* - */ 

int  addset (  bit,  set  ) 

SET  *set; 

{ 

/*  Addset  is  called  by  the  add()  macro  when  the  set  isn't 

*  big  enough.  It  expands  the  set  to  the  necessary  size 

*  and  sets  the  indicated  bit. 

*/ 

enlarge (  (bit  »  3)  +1,  set  ); 

GBIT  (  bit,  set,  |=  ); 

} 

/* - */ 

int  num_ele(  set  ) 

SET  *set; 

{ 

/*  Return  the  number  of  elements  (set  bits)  in  the  set. 

*  This  routine  depends  on  zero  fill  when  an 

*  unsigned  quantity  is  shifted  to  the  right. 

*/ 

register  unsigned  j; 
register  unsigned  count  =  0; 
unsigned  char  *p; 
int  i; 

p  =  set->map; 

for(  i  =  set->nbytes;  — i  >=  0  ;  p++) 
for  (  j  =  *p;  j  ;  j  »=  1  ) 
count  +=  j  &  0x1; 

return  count; 

} 


/* - */ 

set_cmp(  setl,  set2  ) 

SET  *setl,  *set2; 

{ 

/*  Compares  two  sets.  Returns  zero  if  they're  equivalent,  one  if 

*  they're  disjoint,  2  if  they  intersect  but  aren't  equivalent, 

*  -1  is  returned  if  the  two  sets  are  different  sizes. 

*/ 

register  char  *pl,  *p2; 

register  int  i,  disj  =  0  ; 

i  =  max (  setl->nbytes,  set2->nbytes) ; 

enlarge (  i,  setl  );  /*  Make  the  sets  the  same  size  */ 

enlarge (  i,  set2  ); 

pi  =  setl->map; 
p2  =  set2->map; 

for(;  — i  >=  0;  pl++,  p2++  ) 

( 

if (  *pl  !=  *p2  ) 

{ 

if(  *pl  A  ~*p2  ) 
return  2; 

else 
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Listing  Two  (Listing  continued;  text  begins  on  page  14.) 


150 

151 

152  } 

153 

154  /*  - 

155 

156  int 

157  SET 

158  { 

159 

160 
161 
162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179  /*  — 

180 

181  void 

182  int 

183  SET 

184  { 

185 

186 

187 

188 

189 

190 

191 

192 


return  disj; 


/*  They're  equivalent 


} 


201 

202 

203 

204 

205 

206 

207 

208 

209 

210 
211 
212 

213 

214 


subset (  a,  b  ) 
*a,  *b; 


Return  1  if  A  is  a  subset  of  B.  Set  A  must  be  either  smaller 
than  or  the  same  size  as  B.  0  is  returned  if  A  is  not  a 
subset  or  if  A  is  larger  than  B. 


register  int  i; 

register  char  *ap. 


*bp; 


if (  (i  =  a->nbytes)  >  b->nbytes  ) 
return  0; 

ap  =  a->map; 
bp  =  b->map; 

for(;  — i  >=  0;  ap++,  bp++  ) 

if(  (*ap  &  *bp)  !=  *ap  > 
return  0; 

return  1; 


set_op(  op,  dest,  setl,  set2  ) 
op; 

*setl,  *set2,  *dest; 

/*  Performs  either  the  union  or  intersection  of  two  sets 

*  (depending  on  the  value  of  "union").  Dest  is  the  result. 

*  The  two  source  sets  (setl  and  set 2)  must  be  different, 

*  however  either  of  the  sources  may  be  used  as  a  destination 

*  if  you  like.  If  the  sets  are  different  sizes,  the  smaller 

*  set  is  made  larger.  Unused  arguments  should  be  set  to  NULL. 


193 

register  char 

*d; 

/* 

Pointer  to  destiniation  map 

*/ 

194 

register  char 

*ml; 

/* 

Pointer  to  map  in  setl 

*/ 

195 

register  char 

*m2; 

/* 

Pointer  to  map  in  set2 

*/ 

196 

register  int 

i; 

/* 

Number  of  bytes  in  map 

*/ 

197 

198 

199 

i  =  dest->nbytes 

; 

200 

if (  setl  ) 

i  =  max(  i,  setl->nbytes  ); 
if(  set2  ) 

i  =  max(  i,  set2->nbytes  ); 


enlarge (  i,  setl  ); 
enlarge (  i,  set2  ); 
enlarge (  i,  dest  ) ; 

d  =  dest->map; 
ml  =  setl->map; 
m2  =  set2->map; 

while (  — i  >=  0  ) 

{ 


/*  Make  all  three  sets  the  same  size  */ 
/*  if  necessary.  Enlarge  ()  does  nothing  */ 
/*  if  they're  already  the  correct  size.  */ 


215 

D  (  print f  ("set_op: 

working 

[  on  bit 

%d\n",  i  ) ; 

) 

216 

217 

switch (  op  ) 

218 

{ 

219 

case  UNION: 

*d++ 

= 

*ml++  | 

*m2++ 

;  break, 

220 

case  INTERSECT: 

*d++ 

= 

*ml++  & 

*m2++ 

;  break, 

221 

case  DIFFERENCE: 

*d++ 

= 

*ml++  A 

*m2++ 

;  break, 

222 

case  ASSIGN: 

*d++ 

= 

*ml++ 

;  break, 

223 

case  INVERT: 

*d++ 

= 

~*ml++ 

;  break, 

224 

case  CLEAR: 

*d++ 

= 

0 

;  break, 

225 

case  FILL: 

*d++ 

=  ~ 

0 

;  break, 

226  } 

227  } 

228  } 

229 

230  /*  - 

231  #ifdef  DEBUG 

232 

233  pset (  str,  set  ) 


234  char 

235  SET 

236  { 

237 

238 

239 

240 

241 


*str; 

*set; 


int 


i; 


print f ("+ - 

printf("|  %s\n",  str  ); 

printf("|  Set  at  0x%04x:  %d  bits,  %d  bytes,  map  (0x%04x) 


~\n") ; 
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C  CHEST 


Listing  Two  (Listing  continued,  text  begins  on  page  14.) 

242  set,  set->nbits,  set->nbytes,  set->map) ; 

243 

244  printf("%s  TRUE\n",  set->compl  ?  "NEGATIVE"  :  "POSITIVE"  ); 

245  printf (" |  map  =  ") ; 

246 

247  for(  i  =  0;  i  <  set->nbytes;  i++  ) 

248  printf ("0x%02x, ",  (set->map) [i]  ),- 

249 

250  printf ("\n|  bits=  ") ; 

251 

252  for(  i  =  0;  i  <  set->nbits;  i++  ) 

253  printf (  test(i,  set)  ?  "%d, "  :  ""  ,  i  ); 

254 

255  printf  ("\n|  %d  elements\n",  num_ele(set)  ); 


printf ("+- 


test_stuff(  a,  b,  d  ) 


union 

intersectio 

difference 

assign 

complement 

complement 

invert 


a  )  ; 

b  )  ; 

(d,  a,b)  ; 

pset  ("a  union  b". 

d 

(d,a,b) ; 

pset  ("a  intersect  b". 

d 

(d,a,b) ; 

pset  ("a  difference  b". 

d 

(d,  a)  ; 

pset  ("d  assign  a". 

d 

(d); 

pset ("complement  a". 

d 

(d); 

(d,a) ; 

pset ("invert  a". 

d 

printf ("a  %s  equivalent  to  b\n",  equivalent (a, b)  ?  "IS" 
printf ("a  %s  disjoint  from  b\n",  disjoint (a, b)  ?  "IS" 
printf ("b  %s  a  subset  of  a\n",  subset (b,  a)  ?  "IS" 
printf ("a  %s  a  subset  of  b\n",  subset (a,  b)  ?  "IS" 


"ISN'T"  ) ; 
"ISN'T"  ) ; 
"ISN'T"  ) ; 
"ISN'T"  ) ; 


printf ("- 


SET  *a,  *b,  *d; 

char  buf[80],  *p; 

int  num; 

a  =  newset();  pset  (  "initial  a",  a  ); 

b  =  newset  () ;  pset  (  "initial  b",  b  ); 

d  =  newset () ;  pset  (  "initial  d",  d  ); 

add  (0,  a)  ; 
add  (1,  a)  ; 
add  (3,  a) ; 
add(0,b) ; 
add  (3,  b) ; 

test_stuff(  a,  b,  d  ); 

remove  ( 0 ,  a ) ;  remove  ( 1 ,  a ) ;  remove  (3 ,  a ) ;  remove  (0 ,  b) ;  remove  (3 ,  b) ; 
add(0,  a);  add  (2,  a);  add  (2,  b) ;  add  (3,  b)  ; 

test_stuf f (a,  b,  d  ) ; 

clear  (  a  );  clear  (  b  );  test_stuf f (  a,  b,  d  ); 

clear (  a  );  fill  (  b  );  test_stuff(  a,  b,  d  ); 

delset  (  b  ) ; 
delset (  d  ) ; 
delset  (  a  ) ; 
a  =  newset  ()  ; 

printf ("enter  <bitnum><s |c>: ") ; 

while (  gets (buf )  ) 

{ 

num  =  atoi  (buf) ; 

for(  p  =  buf;  isdigit(*p)  ;  p++  ) 


if (  *P  ==  's'  ) 

add (num  , a) ; 

else 

remove  (num,  a) ; 
pset (  a  ); 

printf  ("enter  cbitnumxs  |  c>: ") ; 


End  Listings 
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NEW  GRAPHICS  ISSUES 


Listing  One  (Text  begins  on  page  30.) 


Draw  a  rectangle  with  an  8086  on  CGA. 


Draw  a  rectangle  in  the  upper 
left  corner  of  a  CGA  display 
in  high-resolution  mode.  The  code 
is  hardwired  to  a  10x10  rectangle. 


Set  up  segment  and  offset  registers 
to  point  to  display  memory. 

mov  AX,  0B800H 

mov  ES,  AX 

mov  BX,  0 

Draw  the  top  line  by  stuffing  one  byte 

and  the  first  two  bits  of  the  next  byte. 

mov  byte  ptr  [BX] ,  OFFH 

mov  byte  ptr  [BX+1],  0C0H 

Draw  the  bottom  line  the  same  way. 

mov  byte  ptr  [BX+800],  OFFH 

mov  byte  ptr  [BX+801],  OCOH 


loop 

EOLoop 

cmp 

SI,  2000H 

jg 

EODone 

mov 

SI,  2050H 

mov 

CX,  4 

jmp 

EOLoop 

EODone 

label 

byte 

Rectangle  is  finished. 


Same  rectangle  drawn  by  34010 


Draw  a  line  from  0,0  to  0,10.  The  start 
point  is  in  register  B2  and  the  end  point 
(delta  X  and  delta  Y)  is  in  register  B7. 

The  >  sign  precedes  a  32-bit  hex  constant . 

MOVI  >0,  B2 

MOVI  >00100000, B7 

LINE  0 

Repeat  the  process  for  the  other  sides. 


;  Finished! 

****************************************** 

Same  rectangle  drawn  by  82786 

;  Move  to  the  upper  left  corner  and 
;draw  a  10x10  rectangle. 

ABS_MOVE  0,0 
RECT  10,10 

;  All  finished! 


End  Listing 


;  Draw  the  first  and  last  pixels  on  the 

MOVI 

>00100000, B2 

;  next  4 

even 

scan  lines,  then  do  the  same 

MOVI 

>00000010, B7 

;  on  the 

odd 

scan  lines. 

LINE 

0 

; 

MOVI 

>0,  B2 

mov 

SI,  50H 

MOVI 

>00000010, B7 

mov 

CX,  4 

LINE 

0 

EOLoop: 

mov 

byte  ptr  [BX+SI],  80H 

MOVI 

>00000010, B2 

mov 

byte  ptr  [BX+SI+1],  40H 

MOVI 

>00100000, B7 

add 

SI,  80 

LINE 

0 
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MANDELBROT  PROGRAM 


These  Softstrips  by  Cauzirt  Systems 
contain  the  listings  and  object  code  for 
Howard  Katz's  Mandelbrot  program. 
Strips  1  through  10  on  this  page  and  on 
page  71d  contain  the  source  code,  in 
ASCII  te?ct  format.  Strips  1  and  2  on 
page  71d  contain  the  actual 
application. 
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MANDELBROT  PROGRAM 


MANDELBROT  PROGRAM 


Listing  One  (Text  begins  on  page  42.) 


Listing  One 


;  <  MandelZoom.ASM  > 

Sat 

30  Nov  '85  h.  katz 

; 

Sun 

4  May  *86 

INCLUDE  MacTraps.D 

String_Format 

3 

;  pre-length  DC.B  and  PEA  Strings 

XREF  Convert_2 

_Fixed_ 

Point 

;  Procedure  defined  in  <  Str2FP.ASM  > 

MACRO  Fix  Squared 

Rn 

“  ;  a  Mac-style  macro 

clr.l 

~(sp) 

;  (  Mac-Mac  ?  ) 

move.l 

{Rn}, 

-(sp) 

move.l 

{Rn}, 

-(sp) 

_FixMul 

move.l 

(sp)  +, 

(Rn)  | 

MouseDown  EQU 

1 

;  for  GetNextEvent 

numToString 

EQU 

0 

;  for  _Pack7  conversions 

stringToNum 

EQU 

1 

Gray 

EQU 

-24 

;  offset  from  QDVars  Ptr 

White 

EQU 

-8 

port  Re  ct 

EQU 

16 

;  offset  from  start  of  Window  Record 

pnPat 

EQU 

58 

;  offset  from  start  of  Window  Record 

X_Screen_Offset 

equ 

4 

Y_Screen  Offset 

equ 

4 

Row_Pixers 

equ 

256 

Col_Pixels 

equ 

256 

PenSize 

equ 

2 

HiLitejDff 

equ 

0 

HiLite_On  equ 

1 

Radio_Item_l 

equ 

9 

Radio_Item_2 

equ 

10 

Radio_Item_3 

equ 

11 

X_Org_Item 

equ 

12 

;  Item  Numbers  in  Params  DITL 

Y  Org_Item 

equ 

13 

sTde_Length  Item 

equ 

14 

Count_Item_T 

equ 

15 

Org_S pacing 

equ. 

24 

;  Space  tween  X,  Y,  and  S 

Max_Count_Digits 

equ 

4 

;  Num  Digits  in  'Count'  Item  Strings 

Count_Str_X 

equ 

5 

;  X_coord  of  Counts 

Count_Str_Y 

equ 

114 

;  Y_coord  of  1st  (  Max  )  Count 

Count  Str_Size 

equ 

10 

;  Bytes  wide 

Legend_P lot_It em 

equ  1 

Legend_Quit_Item 

equ  2 

Pattern  Spacing 

equ  30 

;  Delta-Y  for  both  Counts  &  Patts 

Pattern_X  equ 

62  ;  Left  for  Patts  in  Legend  DLOG 

Pattern_Y  equ 

86  ;  Top  for 

1st  Patt  in  Legend  DIOG* 

Pattern_Size 

equ  8 

;  Bytes 

X  Org  Scr  X 

equ  10 

X_Org_Scr_Y 

equ  24 

Time  Scr  X 

equ  10 

Time_Scr_Y 

equ  16 

St 

First  Entry (A5) 

sf 

Radio^l_State  (A5) 

St 

Radio  2  State  (A5) 

;  default  Pen  is  2  X  2 

sf 

Radio_3_State (A5) 

BSR 

InitManagers 

BSR 

Save_Mouse_State 

BSR 

Draw_Menu_Ti t 1 e 

MainLine 

BSR 

Ope  n_P  a  rams_DLOG 

tst.b 

First_Entry  (A5) 

BNE.s 

@Set_Radios 

BSR 

Reload_DITL 

;  2nd  time  around  - 

;  get  old  Parameters 

@Set_Radios 

sf 

First_Entry (A5) 

BSR 

Set_Radio_Buttons 

BSR 

Get_Param_I terns 

;  Get  User  Choice  /  if  OK,  Toggle  Radio 

;  Buttons,  Convert  &  Save  Counts 

bMI 

Exit_To_Shell 

BSR 

Save_Param_Items  ; 

Save  Str  Counts  /  Convert  3  Fix-Pt  Nums 

pea 

pa  ramsDLOGSto rage 

_CloseDlalog 

BSR 

Draw_Mandel_Window 

BSR 

Open_Legend_DLOG 

BSR 

Draw_Pattems 

BSR 

Draw_Org_St  rings 
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MANDELBROT  PROGRAM 

LiStinQ  OH©  (Listing  continued,  text  begins  on  page  42.) 

BSR 

Timer  On 

01 

clr.b 

-(sp) 

pea 

Event Re cord 

BSR 

Do  Mandelbrot 

pea 

theDialog 

pea 

ItemHit 

tMI 

Exit  To  Shell 

These  2  in  case  we've  Interrupted 

Dialog Select 

bHI 

Do  Another 

plotting  in  the  middle 

tst.b 

(sp)  + 

bNE.s 

Get  Legend  DLOG  Item 

BSR 

Timer  Off 

BSR 

Write  Time 

clr.b 

-(sp) 

pea 

Event Re cord 

Wait  4  Ccmnand 

pea 

ParamsDLOGStorage 

pea 

ItemHit 

BSR 

Get  Next  Event 

Dialog Select 

bEQ 

Wait  4  Command 

No  Event 

tst.b 

(sp)  + 

BSR 

Was  Dialog  Event 

move 

#0,  DO 

bEQ 

Wait  4  Command 

0  ->  Hang  Around  a  Bit 

RTS 

tMI 

Exit  To  Shell 

-  ->  Quit 

+  ->  do  another 

Do  Another 

Get_Legend_DLOG_Item 

pea 

MandelWindStorage 

move 

ItemHit,  DO 

CloseWindow 

cmp 

•Legend  Plot  Item,  DO 

pea 

LegendDLOGStorage 

bEQ 

@ Ret urn  Plus 

CloseDialog 

cmp 

•Legend  Quit  Item,  DO 

bEQ 

@ Ret urn  Minus 

BRA 

Mainline 

move 

RTS 

*0,  DO 

Exit  To  Shell 

0 Ret urn  Minus 

;  -  Quitting 

ExitToShell 

move 

RTS 

•-1,  DO 

Save  Mouse  State 

;  if  the  Mouse  is  Down  on  Launch,  we'll 

;  _SetPat 

and  _Line  for  EVERY  Point 

0Return_Plus 

;  -  Do  Another  Mandelbrot 

sf 

Mouse  Down (A5) 

move 

*1,  DO 

clr 

-(sp) 

RTS 

Button 

tst 

(sp)  + 

beq 

0rts 

Timer  On 

St 

Mouse  Down (A5) 

@rts  RTS 

clr.l 

-(sp) 

TickCount 

move.l 

(sp)+.  Start  Time  (A5) 

Draw_Menu_Title 

RTS 

move.l 

IS000F0010,  -(sp) 

MoveTo 

Timer  Off 

pea 

MBarTitle 

Drawstring 

PenNormal 

RTS 

move 

•4,  -(sp)  ;  Wake  the 

Poor  User 

SysBeep 

Reload  DITL 

clr.l 

-(sp) 

lea 

TempStr,  A2 

TickCount 

move 

•0,  D3 

move.l 

(sp)+,  D3 

sub.l 

Start  Time (A5) ,  D3  ; 

(  Stop  -  Start  )  in  Ticks 

move 

IX  Org  Item,  D4 

divu 

•60,  D3 

;  Num  Seconds  (in  Low  Word) 

BSR 

Get  Item  Text 

move.l 

ItemHandle,  - (sp) 

MenuRect 

0,  10,  19,  200 

pea 

X  Org  Str 

_SetIText 

move 

BSR 

move.l 

pea 

Get_Item_Text 
ItemHandle,  - (sp) 

¥  Org  Str 

pea  MandelWindStorage 

pea  TempSTR 

move 

BSR 

f  S  ideJLe  ngt  h_I  tern, 

D4 

lea 

TempSTR,  a2 

;  save  start  addr 
;  clear  out  old  junk 

Length  Byte 

move.l 

pea 

ItemHandle,  -  (sp) 
Side_Length 

clr.l 

move.b 

d5 

(a2)  +,  d5 

adda.l 

d5,  a2 

;  point  past  last  Char  in  Str 

lea 

lea 

move 

move 

TempStr,  A2 

Count  Strings,  A3 

io,  dJ 

•Count_Item_l,  D4 

lea 

clr.l 

move.b 

add.b 

•  :  ',  aO 

dl 

(aO)  +,  dl 
dl,  d5 

;  addr  of  length  byte 

save  new  length 

@Reset_Counts 

move.b 

sub 

d5,  (a3) 

#1,  dl 

put  back  new  length  byte 

BSR 

Get_Item_Text 

@Loop  1 

move.l 

ItemHandle,  -  (sp) 

move.b 

(aO)  +,  (a2)  + 

;  add  new  string  to  end 

move.l 

A3,  -(sp)  ;  Addr  of 

Current  Count  String 

dbra 

dl,  @Loop  1 

SetIText 

move.b 

-  (a2) ,  d4 

save  last  char 

add.l 

ICount  Str  Size,  A3 

add 

#1,  D4 

;  next  Item  Number  in  DDDG 

ext .  1 

D3 

;  Elapsed  Time  in  seconds 

add 

#1,  D3 

;  increment  loop  counter 

move.l 

D3,  DO 

cmp 

#4,  D3 

;  done  all  4  ? 

move.l 

a2,  aO 

EMI 

@Reset_Counts 

;  no 

move 

•NumToString,  - (sp) 

Pack7 

RTS 

clr.l 

dl 

Get_Next_Event 

move.b 

(a2) ,  dl 

save  New  Length  Byte 

move.b 

d4,  (a2) 

restore  last  Char  of  1st  String 

clr 

-(sp) 

add.b 

dl,  d5 

;  new  length 

move 

1-1,  -(sp) 

move.b 

d5,  (a3) 

and  put  back  in  Length  Byte 

pea 

Event Re cord 

adda.l 

dl,  a2 

;  point  to  end  of  string 

GetNextEvent 

adda.l 

*1,  a2 

;  points  1  past  end 

tst.b 

RTS 

(sp)  + 

lea 

'  seconds ' ,  al 

move.b 

(al)  +,  dl 

save  new  Length  Byte 

ext  .w 

dl 

Was  Dialog  Event 

add.b 

dl,  d5 

;  new  total  Length  of  Strings 

move.b 

d5,  (a3) 

put  it  back  in  Length  Byte 

clr.b 

-(sp) 

pea 

Event Record 

@Loop  2 

IsDialogEvent 

move.b 

(al) +,  (a2)  + 

;  append  ‘Seconds'  to  end 

tst.b 

(sp)  + 

;  EQ  -  No  Event 

sub 

•  1,  dl 

bNE.s 

81 

;  NE  -  Was  DLOG  Event 

bhi 

@Loop  2 

RTS 

(continued  on  page  76) 

74 

768 


Dr.  Dobb's  Journal,  November  1986 


MANDELBROT  PROGRAM 

LiStinQ  One  (Listing  continued,  text  begins  on  page  42.) 

pea 

MandelWindStorage 

sub 

d3,  d4 

;  move  up  1  PenSize  from  Bott 

pea 

TempSTR 

move 

d4,  Y  Start (a5) 

SetWTitle 

sub 

dO,  d4 

;  adjust  for  frame  at  Top 

move 

d4,  Num  Rows(a5) 

RTS 

move 

portRect+6(aO) ,  d4  ; 

Window. Right 

move 

IX  Screen  Offset,  dO 

Do  Mandelbrot 

asl 

11,  dO 

;  frame  at  Left  6  Right 

sub 

dO,  d4 

pea 

MandelWindStorage 

sub 

d3,  d4 

;  allow  for  penWidth 

move. 1 

(sp),  -(sp) 

;  copy  WPtr  for  SetWTitle  trap 

move 

d4,  Num  Cols  (a5) 

_SetPort 

;  draw  in  this  Window 

@Get  C  Increment 

tst.b 

Radio  1  State  (A5) 

beq.s 

01 

move.l 

Y  side (A5) ,  DO 

pea 

'1  X  1* 

move 

Num  Rows (A5) ,  D5 

bra 

@SetTitle 

ext.l 

d5 

divu 

Pix  Per  Pt (A5) ,  D5  ; 

-  f  of  Plottable  Pts  on  Y-Axis 

@1  tst.b 

Radio  2  State (A5) 

BSR 

Get  Del  Factor 

;  Del  Y  returned  as  Fixed  Pt 

beq.s 

02 

move.l 

D4,  Del  C  imag (A5)  ; 

in  D4 

pea 

•2  X  2' 

bra.s 

@SetTitle 

clr.l 

-(sp) 

move 

Num  Cols  (a5) ,  -  (sp)  ; 

numerator 

@2  pea 

'4  X  4' 

move 

Num  Rows  (a5) ,  -  (sp)  ; 

denominator 

FixRatio 

; 

Fixed-Pt  Ratio  on  stack 

@SetTitle 

move.l 

(sp)  +,  dO  ; 

tenp  save  it 

SetWTitle 

clr.l 

-(sp) 

move.l 

dO,  -(sp) 

Num  Cols/Num  Rows 

@Set  Pen  Size 

move.l 

Y  Side  (a5) ,  -  (sp) 

;  x  Y  Side 

move 

•PenSize,  D3 

FixMul 

; - 

tst.b 

Radio  2  State  (A5) 

;  Draw  with  2X2  Pen  ? 

move.l 

(sp) +,  X  Side(a5) 

;  -  X  Side 

BNE 

@Set  Pen 

;  yes 

move.l 

X  Side  (A5)  ,  DO 

add 

D3,  D3 

;  Pen  =  4  X  4 

move 

Num  Cols  (A5) ,  D5 

Radio  3  State  (A5) 

ext.l 

d5 

BNE 

@Set  Pen 

;  yes 

divu 

Pix  Per  Pt (A5) ,  D5  ; 

-  f  of  Plottable  Pts  on  X-Axis 

#1,  D3 

;  Draw  with  1X1 

BSR 

Get  Del  Factor 

@Set  Pen 

move.l 

D4,  Del_C_Real (A5) 

D3,  Pix  Per  Pt (A5) 

Continue 

move 

D3,  -(sp) 

BRA 

move 

(sp),  -(sp) 

_PenSize 

Get  Del  Factor 

@Set_Plot_Size 

move.l 

DO,  D3 

save  the  fractional  part 

lea 

MandelWindStorage, 

aO 

swap 

clr.l 

move 

DO 

and  get  the  whole  part 

move 

move 

portRect+4 (aO) ,  d4 
#Y  Screen  Offset, 

;  Window. Bottom 
dO 

DO,  -(sp)  ;  side  (  integer  part  ) 

sub 

dO,  d4 

;  frame  at  Bott 
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MANDELBROT  PROGRAM 

UStinQ  On©  (Listing  continued,  text  begins  on  page  42.) 

move 

D5,  -(sp)  ;  pts  per  side 

add.l 

C  Real (A5) ,  D5 

FixRatio 

;  -  length 

(  integer  )  /  point 

add.l 

C  Imag (A5) ,  D6 

move.l 

(sp) +,  D4  ;  save  the 

(  int  )  fraction 

BRA.s 

Iterate 

sf 

D6 

positive  fraction 

tst 

D3 

0PlOt 

bpl 

01 

BSR 

Get  Pattern 

A4  -  Ptr  to  New  Pattern 

St 

D6 

negative  fraction 

lsr 

#1,  D3 

zero  the  hi  bit  so  FixRatio  doesn't 

tst.b 

First  Pt  (A5) 

IF  NOT  1st  Point 

01  clr.l 

think  the  number  is  Negative 

BEQ 

0Test  Mouse 

Test  Mouse  (  see  if  batching  } 

-(sp) 

sf 

First  Pt (A5) 

;  ELSE 

move 

D3,  -(sp)  ;  side  (  fract  part  ) 

1st  Point  -  FALSE; 

move 

D5,  -(sp)  ;  pts  per  side 

move.l 

A4,  A2 

Old  Pat  New  Pat; 

FixRatio 

;  -  length 

(  fract  )  /  point 

BRA 

0Set  Pattern 

— 

move.l 

(sp)+,  D3 

@Test  Mouse 

swap 

D3 

move  the  'integer'  part  of  the ' fraction' 

tst.b 

D6 

back  into  the  fractional  lo  word 

tst.b 

Mouse  Down (A5) 

IF  NOT  Batch  Plot 

bpl 

02 

BNE.s 

0Draw  Line 

Draw  Line  (  Old  Pat  ) 

lsl 

11,  D3 

restore  the  'negative*  hi  bit 

anp.  1 

A2,  M 

ELSE 

BNE 

@Draw  Line 

IF  NOT  (  New  Pat  -  Old  Pat  ) 

02  and.l 

ISFFFF,  D3 

Draw  Line  (  Old  Pat  ) 

add.l 

D3,  D4 

ELSE 

RTS 

Init  Line  Amount; 

add 

Pix  Per  Pt (A5) ,  A3; 

Do  Next  Pt; 

BRA 

@SkTp  Draw 

Continue 

@Draw  Line 

clr 

Row  Count (A5) 

move.l 

Y  Origin (A5),  C  Imag (A5) 

move 

A3,  -(sp) 

move 

Y  Start  (a5) ,  Y  Current  (A5) 

move 

#0,  -(sp) 

Do_Next_Row 

_Line 

Draw_Line  (  01d_Pat  ) 

clr 

Col_Count (A5) 

@Set_Pattern 

move 

IX  Screen  Offset,  - (sp)  ;  For  next  row 

move.l 

A4,  -(sp)  ;  set  the 

New  Pattern 

move 

Y_Current (A5) ,  - (sp) 

;  move  absolute  to  start 

MoveTo 

move.l 

A4 ,  A 2 

Old  Pat  New  Pat 

St 

First_Pt  (A5) 

;  lst_Point  TRUE; 

move 

Pix_Per_Pt(A5),  A3 

move.l 

X_Origin (AS) ,  C_Real (A5)  ;  for  start  of  new  row 

@Skip_Draw 

BSR 

move 

Col  Count (A5) ,  DO 

add 

Pix  Per  Pt (A5) ,  DO 

move 

Row  Count (A5) ,  DO 

move 

DO,  Col  Count (A5) 

add 

Pix  Per  Pt (A5) ,  DO 

move 

DO,  Row  Count (AS) 

anp 

Nun  Cols  (A5) ,  DO 

anp 

Num_Rows (A5) ,  DO 

BMI.s 

@Update_Z_Real 

fcMI 

©CheckDLOG 

;  we've  finished 

the  Line  -  if  we  need 

to  draw  to  finish  up 

move 

#0,  dO 

;  do  it  here 

BRA 

@Return  To  Mainline 

anp 

Pix  Per  Pt (A5) ,  A3 

@CheckDLOG 

BEQ 

@rts 

;  we've  just  drawn 

BSR 

Get  Next  Event 

move 

A3,  -(sp) 

else  draw  what  we  didn't 

bEQ.s 

0 Setup  Next  Row 

move 

10,  -(sp) 

BSR 

Was  Dialog  Event 

_Line 

bEQ.s 

0 Setup  Next  Row 

0rts  RTS 

0 Ret urn_To_Ma i n 1 i ne 

RTS 

0Update  Z  Real 

move.l 

C  Real  (A5)  ,  DO 

0 Set up  Next  Row 

add.l 

Del  C  Real (A5) ,  DO 

move.l 

DO,  C  Real (A5) 

move 

Pix  Per  Pt (A5) ,  DO 

BRA 

sub 

DO,  Y_Current (A5) 

Do_Points 

move.l 

C  imag  (A5) ,  DO 

;  set  up  Y  for  next  row 

Get_Pattem 

add.l 

Del  C  Imag (A5) ,  DO 

;  Point  to  a  New  PenPat,  according  to  which 

move.l 

DO,  C_Imag(A5) 

;  Range  the  Iter_Count  (  DO  )  falls  in 

BRA.s 

Do  Next  Row 

anp 

0+Counts  (A5) ,  DO 

>=  Black 

BPL.s 

00 

Do  Points 

add 

#8,  A4 

anp 

2+Counts (A5) ,  DO 

>=  DarkGray 

move.l 

C  Real (A5) ,  D5 

;  Initialize  Z  -  C  for  new  point 

BPL.s 

00 

move.l 

C  Imag (A5) ,  D6 

add 

18,  A4 

move 

11,  Iter  Count (A5)  ; 

Do  up  to  Counts (A5)  times  per  Point 

anp 

4+Counts (A5) ,  DO 

>-  LtGray 

lea 

Patterns,  A4 

BPL.s 

@0 

add 

#8,  A4 

Iterate 

anp 

6+Counts (A5) ,  DO 

>"  White 

BPL.s 

00 

move.l 

D5,  D3 

;  Save  Current  Z  Real 

add 

18,  A4 

<  Gray 

move.l 

D6,  D4 

;  Save  Current  Z  Imag 

00  RTS 

Fix  Squared  D3 

;  Z  RealA2 

Fix  Squared  D4 

;  Z  Imag A 2 

move.l 

D4,  D7 

add.l 

D3,  D7 

;  SlzeA2  -  Z_RealA2  +  Z_Imag/'2 

Open_Params_DLOG 

0Test  Size 

clr.l 

“  (sp) 

space  for  funct  result 

move 

Iter  Count (A5) ,  DO 

move 

#100,  -  (sp) 

cmp.  1 

lS40i500,  D7 

;  Size7^  >  4  means  TIME  TO  PLOT 

pea 

Pa  ramsDLOGStorage 

BHI.s 

0PlOt 

move.l 

#-l,  -  (sp) 

in  front  of  everything 

@Test  Count 

_GetNewDla log 
move.l  (sp)+,  dO 

add 

#1,  DO 

RTS 

move 

DO,  Iter  Count (A5) 

anp 

Counts  (A?) ,  DO 

BPL.s 

@Plot 

Set_Radi o_But  tons 

@Get  New  Z 

move 

IHILite  On,  D3 

sub.l 

D4,  D3 

;  Z  Real  -  Z  RealA2  -  Z  ImagA2 

tst.b 

Radio  1  State (A5) 

clr.l 

-(sp) 

BPL 

02 

move.l 

D5,  -(sp) 

move 

•Radio  Item  1,  D4 

move.l 

D6,  -(sp) 

_FixMul 

move.l 

(sp)  +,  D6 

Z  Real  *  Z  Imag 

add.l 

D6,  D6 

(continued  on  page  80) 

move.l 

D3,  D5 

;  Z_Real 
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Listing  One  (Listing  continued,  text  begins  on  page  42.) 


HiLite_Control 

Radio_2_State (A5) 
03 

#Radio_Item_2,  D4 
HiLite_Control 

#Radio_Item_3,  D4 
HiLite  Control 


Set_Exit_Flag 


I  Rad  io_I tem_3 ,  DO 

ModalDLOG  ;  no  -  wait  for  'OK*  or  'Quit' 

Toggle_Radlo_Buttons  ;  yes 

ModalDLOG  ;  and  wait  for  'OK'  or  'Quit' 


HiLite  Control 


pea  ParamsDLOGStorage 

move  D4,  -(sp)  ;  ItemNumber 

pea  ItemType 

pea  ItemHandle 

pea  ItemBox 

_GetDItem 

move.l  ItemHandle,  -  (sp) 

move  D3,  -(sp) 

SetCt lvalue 


Toggle_Radio_Buttons 


Get  Param  Items 


ParamsDLOGStorage  ;  Select  'X_Org'  Parameter 
•X_Org_Item,  -  (sp)  ;  for  Quick  Replacement 
•0,  -(sp) 

#32767,  -(sp) 


DO,  D5 

•HlLite_Off,  D3 
•Radio_Item_l,  D4 
Hi  LI  te_Control 
•  Radio_Item_2,  D4 
HiLite_Control 
#Radlo_Item_3,  D4 
HiLite_Control 

Radio_l_State (A5) 
Radio_2_State (A5) 
Radi> o_3_State  (A5) 


;  (DO  gets  trashed  by  RCM  calls) 


;  turn  off  Everything 


;  Flag  them  as  OFF 


#HiLite_On,  D3  ;  turn  ON  the  Radio  Item 

D5,  D4  ;  that  was  Clicked 

HiLite  Control 

#Radio_Item_l,  D5  ;  and  Flag  the  apt  Item 
@2  ;  as  ON 

Radio  1  State  (AS) 


clr.l  -(sp) 

pea  ItemHit 

ModalDialog 


;  no  filterProc 


ItemHit,  DO 
DO 

ModalDLOG 

#1,  DO  ;  Clicked  'OK*  -  We're  Done  Dialoging  ? 

Validate  Items  ;  yes  -  Validate  &  Convert  numeric  entries 

#2,  DO  ;  Clicked  'Quit'  ? 

Set_Exit_Flag  ;  yes  -  tell  MainLine 

•Radio_Item_l,  DO  ;  Clicked  a  Radio  Button  for  penSlze  ? 
ModalDLOG  ;  no  -  wait  for  'OK*  or  'Quit* 


#Radio_Item_2,  D5 
03 

Radio  2  State  (A5) 


Radlo_3_State (A5) 
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MANDELBROT  PROGRAM 

LiStillQ  One  (Listing  continued,  text  begins  on  page  42.) 

Validate  Items 

_SelectWinaow  ;  so  _DialogSelect  works 

move 

•0,  D3 

Count  -  1 

RTS 

lea 

Count  Strings,  A2 

move 

•Count  Item  1,  D4  ; 

Item  •  of  1st  Count  (MaxCount) 

Draw  Patterns 

@0  BSR 

Get  Item  Text  ; 

get  the  next  Item  Text 

BSR 

Convert  7  Int  ; 

Convert  theString  to  Integer 

clr 

-(sp)  ;  Save  Digit  Char  Width 

move 

**1*#  - (sp)  ;  in  D4  for  Right-Justifying 

add 

110,  A2 

point  to  next  String 

CharWidth 

add 

•  1,  D4 

and  its  Item  Number 

move 

(sp)+,  D4 

add 

#1,  D3 

for  Next  Count  Range 

anp 

#4,  D3 

Done  all  4  Count  Ranges  ? 

move 

•Count  Str  Y,  Legend  Y  Pos(A5) 

EMI 

00 

not  yet 

move 

•0,  D3 

lea 

Count  Strings,  A3  ;  Addr  of  1st  Count  Str 

RTS 

; 

Return  to  MainLlne 

8Draw 

Counts 

Get  Item  Text 

;  A2  points  to  the  String 

move 

•Count  Str  X,  - (sp) 

move 

Legend  Y  Pos(A5),  - (sp) 

pea 

ParamsDLOGStorage  ; 

DLCG  Ptr 

MoveTo 

move 

D4,  -(sp) 

Item  Number 

pea 

ItemType  ; 

Not  Used 

cmp.b 

•Max  Count  Digits,  (A3)  ;  Truncate  STRs  if  too  long 

pea 

ItemHandle  ; 

passed  to  following  RCM  call 

EMI 

00 

pea 

ItemBox  ; 

Not  Used 

rrove.b 

•Max  Count  Digits,  (A3) 

GetDItem 

00 

clr.l 

DO  ;  Right -Justify  Count  Strings 

move. 1 

ItemHandle,  -  (sp) 

move 

•Max  Count  Digits,  DO 

move.l 

A2,  -(sp) 

clr 

D1 

Get I Text 

move.b 

(A3),  D1  ;  Byte  Count  for  String 

sub 

Dl,  DO  ;  Del  Digits  -  Max  Digits  -  Actual  Digits 

RTS 

mulu 

D4,  DO  ;  times  Digit  Char  Width 

move.l 

DO,  -(sp)  ;  -  amount  to  space  over 

Move 

;  Relative  Move 

Convert  2  Int 

move.l 

A3,  -(sp) 

move.l 

A 2,  AO 

Drawstring  ;  Write  the  Count  Range  Str 

move 

Pack7 

•  StringToNun,  -  (sp) 

Convert  Count  to  Numeric 

move.l 

(A5) ,  A 2  ;  QD  Vars  Ptr 

move 

D3,  D5 

Which  Count  Range  ? 

pea 

Gray  (A2) 

add 

D5,  D5 

Words  ->  Bytes  for  Offset 

PenPat 

lea 

Counts  (A5) ,  AO 

move.l 

•SFFFB0006,  -  (sp)  ;  Move  Up  i  Over  a  Bit 

move 

DO,  0  (AO,  D5) 

Index  t  Save  the  Count 

Move 

;  Draw  a  Short  Gray  Line  to 

; 

(  Ignore  the  Hi  Byte  ) 

move.l 

•S0000000D,  - (sp)  ;  separate  the  Patt  Rects 

RTS 

Line 

_PenNormal  ;  Back  to  Black  for  Next  String 

Save  Param  Items 

move 

Legend  Y  Pos (A5) ,  DO  ;  move  down  for  Next  String 

add 

•Pattern  Spacing,  DO 

move 

#0,  D3 

;  D3  not  used  here 

move 

DO,  Legend  Y  Pos (A5) 

move 

•X  Org  Item,  D4 

add.  1 

•Count  Str  Size,  A3;  point  to  Next  String 

lea 

X  Org  Str,  A2 

;  Following  routine  deposits 

BSR 

Get  Item  Text 

;  DITL  text  in  (A2) 

add 

*1,  D3 

anp 

•  4,  D3 

;  A2  (input)  points  to  Decimal 

DITL  String 

EMI 

;  DO  (returned)  contains  Fixed 

-Point  Conversion 

BSR 

Convert  2  Fixed  Point 

move 

;  XREF  routine  to  convert  frcm 

*0,  D3 

move.l 

DO,  X  Origin  (A5) 

STR  format  to  Fixed-Point 

lea 

Patterns,  A3 

;  format  via  SANE  intermediary 

move 

•Y  Org  Item,  D4 

@Draw 

Patterns 

lea 

Y  Org  Str,  A2 

BSR 

Get  Item  Text 

move 

Convert  2  Fixed  Point 

swap 

DO 

move.l 

DO,  Y_Origin(A5) 

move 

*Pattem_X,  DO  ;  Left 

move 

•Side  Length  Item,  D4 

lea 

lea 

Side  Length,  A2 

move.l 

DO,  (A0)  +  ;  TopLeft 

BSR 

Get  Item  Text 

add.l 

•$00130013,  DO  ;  19  X  19 

BSR 

move.l 

Convert  2  Fixed  Point 

DO,  Y  Side  (A5) 

move.l 

DO,  (A0)  ;  BottomRight 

RTS 

pea 

TempRect 

move.l 

(sp) ,  - (sp)  ;  push  2  copies  of  Rect  Addr 

move.l 

(sp),  -(sp) 

FrameRect 

Draw  Org  Strings 

move.l 

•$00010001,  - (sp) 

move 

•  X  Org  Scr  X,  -  (sp) 

InsetRect 

move 

•X  Org  Scr  Y,  D3 

move.l 

A3,  -(sp) 

move 

D3,  -(sp) 

FillRect 

_MoveTo 

pea 

•x  • 

move 

Legend  Y  Pos (A5) ,  DO  ;  move  down  for  Next  String 

Drawstring 

add 

•Pattern  Spacing,  DO 

pea 

X  Org  Str 

move 

DO,  Legend  Y  Pos (A5) 

_DrawStrlng 

add.l 

»Pattem_srze,  A3  ;  point  to  Next  Pattern 

move 

•X  Org  Scr  X,  -(sp) 

add 

*1,  D3 

add 

•Org  Spacing,  D3 

cmp 

*5,  D3 

move 

D3,  -(sp) 

EMI 

@Draw  Patterns 

MoveTo 

pea 

■Y  1 

RTS 

Drawstring 

pea 

Y  Org  Str 

_DrawString 

Draw_Mandel_Window 

move 

•  X  Org  Scr  X,  -  (sp) 

clr.l 

-(sp) 

add 

•Org  Spacing,  D3 

move 

#101,  -(sp) 

move 

D3,  -(sp) 

pea 

Ma nde 1 Wi ndStorage 

MoveTo 

move.l 

#-l,  -(sp) 

pea 

■s 

GetNewWindow 

Drawstring 

Set Port 

;  nuthin  hops  if  we  don’t  do  this 

pea 

Side  Length 

Drawstring 

lea 

MandelWi ndStorage,  A0 

pea 

port Rect (A0) 

RTS 

_EraseRect 

RTS 

Ope  n_Leg  e  nd_DLOG 

clr.l 

-  (sp) 

space  for  Funct  result 

InitManagers 

move 

*101,  -(sp) 

pea 

LegendDLOGStorage 

pea 

-4  (A5) 

move.l 

*-l,  -(sp)  ; 

in  front  of  everything 

InitGraf 

_Get  NewDl a 1 og 
move.l  (sp),  -(sp) 

_InltFonts 

_InitWindows 

_SetPort 

;  so  Title  prints 
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Listing  One 

Listing  Two 

(Listing  continued 

text  begins  on  page  42.) 

Listing  Two 

InitMenus 

;  <  Str2FP. INC  > 

Thur  10  April  '86  h.  katz 

clr.l 

-(sp) 

; 

Mon  14  April  '86 

InitDialogs 

TEInit 

InltCursor 

;  the  slings  and  arrows  .  .  . 

;  This  File  is  Linked  with  MandelZoom. ASM  to  provide  String-to  Floating-Point 

RTS 

;  and  Floating-Point  to  Fixed-Point  Conversions  for  the 

,*  X_Org,  Y_Org,  and 

Side_Len  DITL  Parameters 

-  Constants  (  in  Code  Space  )  - 

;  At  present  only  Single-Precision  SANE  Conversions  are  used 

MBarTitle  dc.b 

'Dr.  Dobb 

's  MandelZoom' 

;  A2  -  ptr  to  the  Decimal  String  on  Input 

;  DO  ~  the  Fixed-Pt 

Number  for  Output 

.ALIGN  2 

String_Format  3 

MandelWindStorage 

dcb.b 

156,  0 

Include  MacTraps.D 

Pa  ramsDLOGStorage 

dcb.b 

170,  0 

Include  SANEMacs.Txt 

LegendDLOGStorage 

dcb.b 

170,  0 

XDEF  Convert  2 

Fixed  Point 

ItemHit 

dc.w 

0 

ItemType 

dc.w 

0  ;  Not  Used 

Sign 

EQU  0  ;  Byte  Offsets  in  Decimal  Record 

ItemHandle 

dc.  1 

0  ;  passed  frctn  GetDItem  to  GetIText 

Exp 

EQU  2 

ItemBox 

dcb.l 

2,  0  ;  Not  Used 

Sig 

EQU  4 

theString  dcb.b 

256,  0 

theDialog  dc.l 

0 

;  for  dialogPtr  returned  by  IsDialogEvent 

FP  Sign 

EQU  31  ;  Bit  Offsets  in  Single-Precision  Result 

FP  Exp 

EQU  30 

X  Org  Str  dcb.b 

10,  0 

FP  Sig 

EQU  22 

Y  Org  Str  dcb.b 

10,  0 

Side  Length 

dcb.b 

10,  0 

SP  Exp  Bias 

EQU  127 

DP  Exp  Bias 

EQU  1023  ;  Code  for  Double-Precision  not  written 

Count  Strings 

dcb.b 

40,  0  ;  4  X  10  Bytes  each 

TempRect 

dcb.l 

2,  0  ;  holds  the  Patt  Rects  for  the  Legend 

TempSTR 

dcb.b 

40,  0 

Convert  2  Fixed  Point 

Event Re cord 

What: 

dc.w 

0 

lea 

Temp  String,  aO  ;  make  a  copy  of  incoming  string 

Message: 

dc.l 

0 

move.b 

(a2) ,  dO  ;  its  length 

When: 

dc.l 

0 

@0  move.b 

(a2)+,  (a0)  + 

0 

DBRA 

dO,  00 

Modifiers: 

dc.w 

0 

lea 

Temp_String,  aO  ;  replace  ptr  to  theString 

Patterns 

BSR 

Build  Decimal  Record 

dc.l 

SFFFFFFFF 

;  4  pixels  per  4  -  black 

dc.  1 

$FFFFFFFF 

pea 

Decimal  Record 

pea 

FP  Num 

dc.  1 

5FFAAFFAA 

;  3  pixels  per  4  -  dark  gray 

FDEC2S 

;  a  SANE  'trap' 

dc.  1 

SFFAAFFAA 

BSR 

Build  Fixed  Pt 

dc.l 

SAA00AA00 

;  1  pixel  per  4  -  light  gray 

dc.  1 

$AA00AA00 

RTS 

;  to  Mandelbrot 

dc.l 

$00000000 

;  0  pixels  per  4  -  pure  white 

dc.l 

$00000000 

Build_Fixed_Pt 

dc.  1 

SAA55AA55 

;  2  pixels  per  4  -  gray 

sf 

d2  ;  assume  Positive 

SAA55AA55 

lea 

FP  Num,  aO 

move. 1 

(aO) ,  dl  ;  save  the  Exponent 

lsl.l 

il,  dl  ;  shift  Sign  into  Carry 

bcc 

@1  ;  was  Positve 

st 

d2  ;  flag  as  Negative 

1  ;  Fixed-Pt  conversions  from 

1  ;  User  Entries  in  Params  DLOG 

81  swap 

dl  ;  move  Exp  into  Low  Word 

1 

lsr.w 

#8,  dl  ;  shift  Exp  to  Right 

Y_Side 

ds.l 

1  ;  Set  to  X_Side  for  now 

sub.b 

»SP_Exp_Bias,  dl  ;  unbias  it 

move.l 

(aO) ,  dO  ;  move  orig  FP  Num  into  register 

and.l 

IS007FFFFF,  dO  ;  clear  Exp 

ds 

1 

bset.l 

123,  dO  ;  add  the  leading  '1'  bit 

Num  Cols 

ds 

1 

tst.b 

d2 

Pix  Per  Pt 

ds 

1 

beq 

@2  ;  num  is  + 

neg.l 

dO 

4  ;  4  INTEGERS  dividing  the  Iterative 

;  Domain  into  5  Ranges  (&  Patterns) 

02  sub.b 

#7,  dl  ;  Neg  (7-Exp)  is  amount  to  shift 

1 

neg.b 

dl 

Row  Count  ds.w 

1 

fcmi 

@Shift  Left 

Col  Count  ds.w 

1 

asr.l 

dl,  dO 

bra 

@rts 

y  current  ds.w 

1 

@Shift  Left 

neg.b 

dl  ;  Max  Left  ShJ  ft  not  checked  for  yet 

C  Real 

ds.w 

1 

asl.l 

dl,  dO 

ds.w 

1 

C  imag 

ds.w 

1 

0rts  RTS 

ds.w 

1 

Z  Real 

ds.w 

1 

Build  Decimal  Record 

ds.w 

1 

1 

;  Strip  the  Sign  Char 

;  Strip  the  Decimal  Pt  and  Decrease  the  Exponent  Accordingly 

;  Finally  Strip  Leading  Zeroes 

ds.l 

1 

Del  C  imag 

ds.l 

1 

lea 

Decimal  Record,  al  ;  Zero  the  Record 

move.l 

#0,  (al) + 

Legend  Y  Pos 

ds.w 

1 

move.l 

#0,  (al) + 

move.l 

•0,  (al)  * 

1 

move. 1 

10,  (al)  + 

lea 

Decimal  Record,  al 

1 

Radio  2  State 

ds.b 

1 

cmp.b 

#'  +  ',  1  (aO)  ;  Strip  the  Plus  Sign,  if  any 

Radio  3  State 

ds.b 

1 

BNE 

@Strip  Minus  Sign 

BSR 

Shift  Count  Byte 

First  Entry 

ds.b 

1 

bra 

Strip  Decimal_Pt 

Mouse  Down 

ds.b 

1 

First  Pt 

ds.b 

1 

0Strip  Minus  Sign 

cmp.b 

1  (aO) 

END 

BNE 

Strip  Decimal  Pt 

move.b 

11,  Sign(al)  ;  Mark  Dec  Rec  Sign  as  Negative 

BSR 

Shi f  t_Count_By te 

S t r i p_De c  ima 1_P  t 

move.b 

(aO) ,  Slg(al)  ;  move  Count  to  Decimal_Record 

End  Listing  One 

(continued  on  page  86) 
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MANDELBROT  PROGRAM 

UStinQ  TWO  (Listing  continued,  text  begins  on  page  42.) 

lea 

1+Sig  (al) ,  a2 

;  point  to  1st  Digit 

0Loop  2 

add.  1 

#1,  aO 

;  points  to  1st  Digit  in  Src  Str 

move.b 

(aO)  +,  (al)  + 

shift  Count  +  Digits  to  Left 

clr 

dO 

DBRA 

dO,  0  Loop  2 

move.b 

Sig(al),  dO 

;  length  of  String 

sub.b 

#1,  dO 

;  -  1  for  DBRA 

0rts  RTS 

sf 

dl 

;  Passed_Decimal_Pt  Flag  -  FALSE 

@0  anp.b 

•  (aO) 

Shift  Count  Byte 

beq 

@Found  Decimal 

Pt 

move.b 

(aO)  +,  (a2)  + 

;  shift  the  digit  to  Decimal  Rec 

sub.b 

11,  (aO)  ;  Length  - 

Length  -  1 

tst.b 

dl 

;  are  we  past  the  Decimal  Pt  ? 

move.b 

(a0)+,  (aO) 

move  Count  Byte  over  one 

beq 

@Test  EOStr 

RTS 

sub 

#1,  Exp(al) 

bra 

0Test_EOStr 

@Found_Decima l_Pt 

St 

dl 

FP  Num 

working  space  for  both 

add.l 

#1,  aO 

;  point  past  decimal  point 

Single  &  Double  Precision  numbers 

sub.b 

•  1,  Sig  (al) 

;  Count  Count  -  1 

Decimal  Record 

Sign 

@Test_EOStr 

dc.w  0 

dcb.b  12,  0 

Exp 

Sig 

DBRA 

dO,  00 

Temp_String 

dcb.b  12,  0 

Strlp_Leadlng_Zeroes 

lea 

Sig  (al) ,  aO 

;  point  0  Count  Byte  in 

END 

move.b 

(aO),  dO 

;  Decimal  Record  Sig  Field 

sub.b 

#1,  dO 

;  setup  for  DBRA 

dO 

End  Listing  Two 

sf 

dl 

;  No  Leading  Zeroes  (yet) 

@Loop  1 

anp.b 

•  'O',  1  (aO) 

BNE 

0Test  4  Shift 

;  Encountered  a  Signif  Digit  ->  Done 

St 

dl 

BSR 

Shift  Count  Byte 

DBRA 

dO,  0Loop_l 

0Test_4_Shift 

tst.b 

dl 

;  Any  Non-Significant  Zeroes  Found  ? 

BEQ 

0rts 

;  no 

lea 

Sig (al) ,  al 

;  point  to  Sig  Count  Byte 

move.b 

(aO),  dO  ;  aO 

is  Count  Byte  (wherever  it  is) 

ext.w 

dO 
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Listing  Three 


MarvDLOG .  R 


*  Output  file  - 

Handels :Mandel_2 
APPLKATZ 


Mon  31  April  *86  h.  katr 


*  Input  file  - 

Include  Handels :Mandel  2.CodeR 


Type  HIND 

,101 

41  6  336  404 
Visible  NoGoAway 
0 
0 


Type  DLOG 

,101 

no  message 
30  415  330  500 
Visible  NoGoAway 
1 
0 

101 


Type  DITL 


Button 
240  3  265  S3 
New  Plot 

Button 

270  3  295  S3 

Quit 


Type  DLOG 

,100 

no  message 
50  100  250  400 
Visible  NoGoAway 
1 
0 

100 


; ;  Mandelbrot  ffindow 


; ;  docProc 


Legend1  Dialog 


;;  DBoxProc 


; ;  2  Items 
;;  Item  #1 


;;  Item  #2 


; :  Parameters  Dialog 


Type  DITL 


,100 


Button 

135  130  160  220 
Plot 

Button 

165  130  190  220 
Quit 

StaticText  Disabled  ;;  Item  #3 
8  30  25  235 
Mandelbrot  Parameters 

StaticText  Disabled  ;;  Item  #4 

40  15  56  75 

XjOrigin 

StaticText  Disabled  ;;  Item  IS 

70  15  86  75 

YjOrigin 

StaticText  Disabled  ; ;  Item  #6 
100  15  116  75 
Side 

StaticText  Disabled  ;;  Item  #7 

65  180  80  240 

Counts 

StaticText  Disabled  ;;  Item  #8 

155  15  170  45 

Pen 

RadioButton 
135  50  150  105 
1X1 

RadioButton 
155  50  170  105 
2X2 

RadioButton 
175  50  190  105 

4X4 

EditText  ; ;  It 

40  80  55  144 

-2.00 


18  Items 
Item  #1 


Item  #2 


;;  Item  #9 


;;  Item  #11 


XjOrigin 


EditText 
70  80  85  144 
-1.25 

EditText 

100  80  115  144 

2.500 

EditText 

20  245  35  280 
32 

EditText 
50  245  65  280 
12 

EditText 
80  245  95  280 
6 

EditText 

110  245  125  280 

4 


TYPE  ALRT 

,1 

40  100  180  400 
1 

7777 


Button 

100  220  120  270 
OK 

StaticText  Disabled 
40  30  60  290 
Numeric  Digits  Only 


Item  #13 


;;  Item  #14 


;;  Item  #15 


;;  Item  #16 


;;  Item  #17 


Default  -  Item  1 
0 


Y_Origin 


Side_Length 


4  initial  Defaults  for 
Patt  Ranges 


/  Draw  Box  /  3  Beeps 
(  ALL  stages  ) 
/  1  /  10 


End  Listings 
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_ DIGITAL  DISSOLVE 

Listing  One  (Text  begins  on  page  48.) 


procedure  DissBits  (srcB,  destB:  bitMap;  srcR,  dstR:  rect);  external; 
mike  morton 

release:  30  june  1986,  version  5.3 

this  version  is  formatted  for  the  Lisa  Workshop  assembler 

differences  from  version  5.2: 

extraneous  code  removed  from  bitwidth  routine 
introductory  corrments  are  much  shorter 

********************************************************************** 

*  copyright  1984,  1985,  1986  by  michael  s.  morton  * 

********************************************************************** 

DissBits  is  freeware,  you're  welcome  to  copy  it,  use  it  in  programs,  and 
to  modify  it,  as  long  as  you  leave  my  name  in  it.  i'd  be  interested  in 
seeing  your  changes,  especially  if  you  find  ways  to  make  the  central 
loops  faster,  or  port  it  to  other  machines/languages. 

if,  for  some  reason,  you  only  have  a  hard  copy  of  this  and  would  like  a 
source  on  a  diskette,  please  contact: 
robert  hafer 

the  boston  computer  society 
one  center  plaza 
boston,  mass.  02108 


include  files: 

tlasm/graftypes  —  definitions  of  "bitMap"  and  "rect" 
tlasm/quickmacs  —  macros  for  quickdraw  calls  (e.g.,  _hidecursor) 


.nolist 

.include  tlasm/graftypes 
.include  tlasm/quickmacs 
.list 


definitions  of  the  "ours"  record:  this  structure,  of  which  there  are 
two  copies  in  our  stack  frame,  is  a  sort  of  bitmap: 


oRows 

.equ 

0 

;  (word)  number  of  last  row  (first  is  0) 

oCols 

.equ 

oRows+2 

;  (word)  number  of  last  column  (first  is 

olbits 

.equ 

oCols+2 

;  (word)  size  of  left  margin  within  1st  1 

oStride 

.equ 

oIb>its+2  ;  (word) 

stride  in  meirory  from  row  to  row 

oBase 

.equ 

oStride+2  ;  (long) 

base  address  of  bitmap 

osize 

.equ 

oBase+4 

;  size,  in  bytes,  of  "ours"  record 

stack 

frame  elements: 

srcOurs 

.equ 

-osize 

;  (osize)  our  view  of  source  bits 

dstOurs 

.equ 

srcOurs-osize 

;  (osize)  our  view  of  target  bits 

sflast 

.equ 

dstOurs 

;  relative  address  of  last  s.f.  member 

sfsize 

.equ 

-sflast 

;  size  of  s.f.  for  LINK  (must  be  EVEN!) 

parameter  offsets  from  the  stack  frame  pointer,  A6: 

last  parameter  is  above  return  address  and  old  s.f. 

dRptr 

.equ 

4+4 

;  ''destination  rectangle 

sRptr 

.equ 

dRptr+4 

;  Asource  rectangle 

dBptr 

.equ 

sRptr+4 

;  Adestination  bitMap 

sBptr 

.equ 

dBptr+4 

;  A source  bitMap 

plast 

.equ 

sBptr+4 

;  address  just  past  last  parameter 

psize 

.equ 

plast -dRptr 

;  size  of  parameters,  in  bytes 

;  entrance:  set  up 

a  stack  frame,  save  some  registers,  hide  the  cursor. 

.proc 

dissBits 

;  main  entry  point 

link 

A6, #-sfsize 

;  set  up  a  stack  frame 

movem.  1 

D3-D7/A2-A5, - (SP) 

;  save  registers  compiler  may  need 

hidecurs 

;  don't 

let  the  cursor  show  for  now 

convert  source  and  destination  bitmaps  and  rectangles  to  a  format  we  prefer, 
we  won't  look  at  these  parameters  after  this. 


move.l  sBptr(A6),A0  ;  point  to  source  bitMap 

nvDve.l  sRptr  (A6) ,  A1  ;  and  source  rectangle 
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DIGITAL  DISSOLVE 


Listing  One  (Listing  continued,  text  begins  on  page  48.) 


lea 

srcOurs (A6) , A2  ; 

and  our  source  structure 

bsr 

CONVERT 

convert  to  our  format 

move.l 

dBptr (A6) ,A0 

point  to  destination  bitMap 

move.l 

dRptr  (A6)  ,A1 

and  rectangle 

lea 

dstOurs  (A6)  ,A2  ; 

and  our  structure 

bsr 

CONVERT 

convert  to  our  format 

check 

that  the 

rectangles  match  in  size. 

move.w 

srcOurs+oRows (A6) ,D0 

;  pick  up  the  number  of  rows 

anp.w 

dstOurs+oRows (A6) ,D0 

;  same  number  of  rows? 

bne 

ERROR 

nope  —  bag  it 

move.w 

srcOurs+oCols (A6) , DO 

;  check  the  number  of  columns 

anp.w 

dstOurs+oCols (A6) ,D0 

;  same  number  of  columns,  too? 

bne 

ERROR 

that ' s  a  bozo  no-no 

figure  the  bit- 

-width  needed  to  span  the  columns,  and  the  rows. 

move.w 

srcOurs+oCols (A6) , DO 

;  get  count  of  columns 

ext  .1 

DO 

make  it  a  longword 

bsr 

LOG  2 

figure  bit-width 

move.w 

D0,D1 

set  aside  that  result 

beq 

SMALL 

too  small?  wimp  out  and  use  copy Bits 

move.w 

srcOurs+oRows (A6) ,D0 

;  get  count  of  rows 

ext  .1 

DO 

make  it  a  longword 

bsr 

L0G2 

again,  find  the  bit-width 

tst.w 

DO 

is  the  result  zero? 

beq 

SMALL 

if  so,  our  algorithm  will  screw  up 

;  set  up  various 

constants  we'll  need  in  the  in  the  innermost  loop 

move.l 

#1,D5 

set  up. . . 

lsl.l 

D1,D5 

...the  bit  mask  which  is... 

sub.l 

#1,D5 

...bit-width  (cols)  l's 

add.w 

D1,D0 

find  total  bit-width  (rows  plus  columns) 

lea 

TABLE,  AO  ;  point  to  the  table  of  XOR  masks 

moveq 

1 0,D3 

clear  out  D3  before  we  fill  the  low  byte 

move.b 

0  (AO,  DO)  ,D3 

grab  the  correct  XOR  mask  in  D3 

;  table 

is  saved 

compactly,  since  no  mask  is  wider  than  a  byte. 

;  we  have  to  unpack  it  so  high-order  bit  of  the  DO-bit-wide  field  is  on: 

UNPACK 

add.l 

D3,D3 

shift  left  by  one 

fcpl.s 

UNPACK 

keep  moving  until  top  bit  that's  on  is 
aligned  at  the  top  end 

rol.l 

D0,D3 

now  swing  the  top  DO  bits  around  to  be 
bottom  DO  bits,  the  mask 

move.l 

D3,D0  ; 

1st  sequence  element  is  the  mask  itself 

;  do  all  kinds  of  preparation: 

move.l 

srcOurs+oBase (A6) , D2 

;  set  up  base  ptr  for  source  bits 

lsl.l 

f3,D2 

make  it  into  a  bit  address 

move.l 

D2,  AO 

put  it  where  the  fast  loop  will  use  it 

move.w 

s r cOirs +oLbi t s (A6)  ,D2  ;  now  pick  up  source  left  margin 

ext  .1 

D2 

make  it  a  longword 

add.l 

D2,  AO 

make  AO  useful  for  odd  routine  below 

move.l 

dstOurs+oBase (A6) ,D2 

;  set  up  base  pointer  for  target 

lsl.l 

#3,  D2 

again,  bit  addressing  works  out  faster 

move.l 

D2,A1 

stuff  it  where  we  want  it  for  the  loop 

move.w 

dstOurs+oLbits (A6) ,D2  ;  now  pick  up  destination  left  margin 

ext .  1 

D2 

make  it  a  longword 

add.l 

D2,A1 

and  make  A1  useful,  too 

move.w 

srcOurs+oCols (A6) , A2 

;  pick  up  the  often-used  count 

;  of  columns 

move.w 

srcOurs+oRows (A6) ,  D2 

;  and  of  rows 

add.w 

#1,D2 

make  row  count  one-too-high  for  compares 

ext  .1 

D2 

and  make  it  a  longword 

lsl.l 

D1,D2 

slide  it  to  line  up  w/rows  part  of  DO 

move.l 

D2,A4 

and  save  that  somewhere  useful 

move.w 

D1,D2 

put  log2  (columns)  in  a  safe  place  (sigh) 
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DIGITAL  DISSOLVE 


Listing  One  (Listing  continued,  text  begins  on  page  48.) 


try  to  reduce  the  amount  we  shift  down  D2.  this  involves: 

halving  the  strides  as  long  as  each  is  even,  decrementing  D2  as  we  go 

masking  the  bottom  bits  off  D4  when  we  extract  the  row  count  in  the  loop 

alas,  can't  always  shift  as  little  as  we  want,  for  instance,  if  we  don't 
shift  down  far  enough,  row  count  will  be  so  high  as  to  exceed  a  halfword, 
and  the  dread  mulu  instruction  won't  work  (eats  only  word  operands),  so, 

we  have  to  have  an  extra  check  to  take  us  out  of  the  loop  early. 


HALFLOOP 


move.w 

move.w 

move.w 

src0urs+oStride(A6) ,D4  ;  pick  up  source  stride 

dstOurs+oStride (A6) ,D7  ?  and  target  stride 

srcOurs+oRows (A6) ,D1  ;  get  row  count  for  klugey  check 

tst.w 

beq.s 

D2 

HALFDONE 

;  how's  the  bit count? 

;  skip  out  if  already  down  to  zero 

btst 

bne.s 

btst 

bne.s 

#0,D4 

HALFDONE 

#0,D7 

HALFDONE 

;  is  this  stride  even? 
nope  —  our  work  here  is  done 
;  how  about  this  one? 
have  to  have  both  even 

lsl.w 

bcs.s 

#1,D1 

HALFDONE 

;  can  we  keep  max  row  number  in  a  halfword? 
nope  —  D2  mustn't  get  any  smaller! 

lsr.w 

lsr.w 

sub.w 

bne.s 

#1,D4 

#1,D7 

#1,D2 

HALFLOOP 

;  halve  each  stride... 

;  . . .like  this 

;  and  remember  not  to  shift  down  as  far 
;  loop  unless  we're  down  to  no  shift  at  all 

move.w 

move.w 

;  no  tacky  platitudes,  please 

D4, srcOurs+oStride  (A6)  ;  put  back  source  stride 

D7,  dstOurs+oStride (A6)  ;  and  target  stride 

make  seme  stuff  faster  to  access  —  use  the  fact  that  (An)  is  faster 
to  access  than  d(An).  this  means  we'll  misuse  our  frame  pointer,  but 
don't  worry  —  we'll  restore  it  before  we  use  it  again. 


\5  ;  make  source  stride  faster 

;  to  access,  too 
save  framitz  pointer 
A6  ;  pick  up  destination  stride 
we  do  only  AND.w  x,D6  —  but  ADD.l  D6, x 


move.w 

srcOurs+oStride  i 

move.l 

A6,  -  (SP) 

move.w 

dstOurs+oStride i 

move.l 

#0,D6 

clr.w 

-(SP) 

bsr 

MULCHK 

tst.w 

(SP)  + 

bne 

NCMUL 

reserve  room  for  function  result 
go  see  if  strides  are  powers  of  two 
can  we  eliminate  the  horrible  MULUs? 
yes !  hurray ! 


main  loop:  map  the  sequence  element  into  rows  and  columns,  check  if  it' 
in  bounds  and  skip  on  if  it's  not,  flip  the  appropriate  bit,  generate 
the  next  element  in  the  sequence,  and  loop  if  the  sequence  isn't  done. 


check  row  bounds,  note  that  we  can  check  row  before  extracting  it  from 
DO,  ignoring  bits  at  bottom  of  DO  for  the  columns,  to  get  these  bits 
to  be  ignored,  had  to  make  A4  1-too-high  before  shifting  up  to  align  it. 


cmp.l 

bge.s 


A4,D0 

NEXT 


here  for  another  time  around 
is  row  in  bounds? 
no:  clip  this 


map  it  into  the  column;  check  bounds.  note  that  we  save  this  check 

for  second;  it's  a  little  slower  because  of  the  move  and  mask. 

chuck  sagely  points  out  that  when  the  "bhi"  at  the  end  of  the  loop  takes,  we 
know  we  can  ignore  the  above  corrparison.  thanks,  chuck,  you're  a 
great  guy. 


here  when  we  know  the  row  number  is  OK 


move.w 

D0,D6 

;  copy  the  sequence  element 

and.w 

D5,D6 

;  find  just  the  column  number 

cmp.w 

A2,D6 

;  too  far  to  the  right?  (past  oCols?) 

bgt.s 

NEXT 

;  yes:  skip  out 

move.l 

D0,D4 

;  we  know  element  will  be  used;  copy  it 

sub.w 

D6,D4 

;  remove  column's  bits 

lsr.l 

D2,D4 

;  shift  down  to  row,  NOT  right- justified 
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Listing  Ono  (Listing  continued,  text  begins  on  page  48.) 

;  get  source  byte, 

and  bit  offset.  D4  has  the  bit  offset  in  rows,  and 

;  D6  is  columns. 

move.w 

A5,D1 

;  get  the  stride  per  row  (in  bits) 

mulu 

D4,D1 

;  stride  *  row;  find  source  row's  offset  in  bits 

add.l 

D6,D1 

;  add  in  column  offset  (bits) 

add.l 

A0,D1 

;  plus  base  of  bitmap  (bits  [sic] ) 

move.b 

D1,D7 

;  save  the  bottom  three  bits  for  the  BTST 

lsr.l 

#3,D1 

;  while  we  shift  down  to  a  word  address 

move.l 

Dl,  A3 

;  and  save  that  for  the  test,  too 

not.b 

D7 

;  get  right  bit  number  (compute  #7-D7) 

;  find 

the  destination  bit  address  and  bit  offset 

move.w 

A6,D1 

;  extract  cunningly  hidden  destination  stride 

mulu 

Dl,  D4 

;  stride*row  number  =  dest  row's  offset  in  bits 

add.l 

D6,D4 

;  add  in  column  bit  offset 

add.l 

A1,D4 

;  and  base  address,  also  in  bits 

move.b 

D4,D6 

;  set  aside  the  bit  displacement 

lsr.l 

#3,D4 

;  make  a  byte  displacement 

not.b 

D6 

;  get  right  bit  number  (compute  #7-D6) 

btst 

D7,  (A3) 

;  test  the  D7th  bit  of  source  byte 

move.l 

D4,  A3 

;  point  to  target  byte  (don't  lose  CC  ffom  btst) 

bne.s 

SETON 

;  if  on,  go  set  destination  on 

bclr 

D6,  (A3) 

;  else  clear  destination  bit 

;  find 

the  next  sequence  element,  see  knuth,  vol  ii.,  page  29 

;  for  sketchy  details. 

NEXT 

;  jump  here  if  DO  not  in  bounds 

lsr.l 

#1,D0 

;  slide  one  bit  to  the  right 

bhi.s 

LOOP  ROW 

;  if  no  carry  out,  but  not  zero,  loop 

eor.l 

D3,  DO 

;  flip  magic  bits  for  bitwidth  we  want... 

anp.l 

D3,D0 

;  ...but  has  this  brought  us  to  square  1? 

bne.s 

LOOP 

;  if  not,  loop  back;  else... 

bra.s 

DONE 

;  ...we're  finished 

SETON 

bset 

D6,  (A3) 

;  source  bit  was  on;  set  destination  on 

;  copy  of  above  code,  stolen  for  inline  speed  —  sorry. 

lsr.l 

#1,  DO 

;  slide  one  bit  to  the  right 

bhi.s 

LOOP ROW 

;  if  no  carry  out,  but  not  zero,  loop 

eor.l 

D3,D0 

;  flip  magic  bits... 

anp.l 

D3,D0 

;  ...but  has  this  brought  us  to  square  1? 

bne.s 

LOOP 

;  if  not,  loop  back;  else  fall  through 

;  here 

when  done; 

the  (0,0) 

point  has  not  been  done  yet.  this  is 

;  really  the  (0,left  margin) 

point,  also  jump  here  from  another  copy  loop. 

DONE 

move.l 

(SP)+,A6 

;  restore  stack  frame  pointer 

move.w 

srcOurs+oIMts  (A6) ,  DO  ;  pick  up  bit  offset  of  left  margin 

move.w 

dstOurs+oLbits  (A6)  ,D1  ;  and  ditto  for  target 

not.b 

DO 

;  flip  to  number  the  bits  for  68000 

not.b 

Dl 

;  ditto 

;  alternate,  late 

entrance. 

when  SCREEN  routine  has  already  set  up  DO  and 

;  D1  (it  doesn't 

want  the  bit  offset  negated) . 

DONEA 

;  land  here  with  DO,  Dl  set 

move.l 

srcOurs+oBase (A6) , AO  ;  set  up  base  ptr  for  source  bits 

move.l 

dstOurs+oBase (A6) ,A1  ;  and  pointer  for  target 

bset 

Dl,  (Al) 

;  assume  source  bit  was  on;  set  target 

btst 

DO,  (AO) 

;  was  first  bit  of  source  on? 

bne.s 

DONE2 

;  yes:  skip  out 

bclr 

Dl,  (Al) 

;  no:  oops!  set  it  right,  and  fall  through 

;  return 

D0NE2 

;  here  when  we're  really  done 

ERROR 

;  we  return  silently  on  errors 

showcurs 

;  let's  see  this  again 

(continued  on  page  96) 
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Listing  One  (Listing  continued,  text  begins  on  page  48.) 


movem.  1 
unlk 
move.l 
add.l 
jmp  (AO) 


(SP) +, D3-D7/A2-A5  ;  restore  lots  of  registers 

A6  ;  restore  caller's  stack  frame  pointer 

(SP) +, AO  ;  pop  return  address 
#psize,SP  ;  unstack  parameters 
;  home  to  mother 


sleazo  code  for  when  we're  asked  to  dissolve  very  small  regions,  if 
either  dimension  of  the  rectangle  is  too  small,  we  bag  it  and  just 
delegate  the  problem  to  copyBits.  a  possible  problem  with  this  is 
if  someone  decides  to  substitute  us  for  the  standard  copyBits  routine 
—  this  case  will  become  recursive... 


SMALL 

move.l  sBptr  (A6) ,  -  (SP) 

move.l  dBptr  (A6) ,  -  (SP) 

move.l  sRptr  (A6) ,  -  (SP) 

move.l  dRptr  (A6) ,  -  (SP) 

move.w  IsrcCopy,- (SP) 
clr.l  -(SP) 

_copyBits  ;  do  the 

bra . s  D0NE2 


;  here  when  it's  too  small 
;  push  args:  source  bitmap 
;  destination  bitmap 

;  source  rectangle 

;  destination  rectangle 

;  transfer  mode  —  source  copy 

;  mask  region  —  NIL 

copy  in  quickdraw-land 
;  head  for  home 


code  identical  to  the  usual  loop,  but  A5  and  A6  have  been  changed  to 
shift  counts,  other  than  that,  it's  the  same,  really  it  is!  well,  no, 
wait  a  minute...  because  we  don't  have  to  worry  about  the  word-size 
mulu  operands,  we  can  collapse  the  shifts  and  countershifts  further 
as  shown  below: 


NCMUL  ;  here  for  alternate  version  of  loop 


tst.w 

D2 

;  is  right  shift  zero? 

beq.s 

NOMUL2 

;  yes:  can't  do  much  more... 

cxnp.  w 

#0,  A5 

;  how  about  one  left  shift  (for  source  stride) ? 

beq.s 

NCMUL2 

;  yes:  ditto 

cmp.w 

10, A6 

;  and  the  other  left  shift  (destination  stride)? 

beq.s 

N0MUL2 

;  yes:  can't  do  much  more... 

sub.w 

#1,D2 

;  all  three... 

sub.  w 

#1,  A5 

;  ...are... 

sub.w 

#1,  A6 

;  ...collapsible 

bra.s 

NCMUL 

;  go  see  if  we  can  go  further 

;  see  if 

we  can 

do 

the  super-special-case  loop,  which  basically  is 

;  equivalent  to 

any  rectangle  where  the  source  and  destination  are 

;  both  exactly  the 

width  of  the  Mac  screen. 

NOMUL2 

;  here  when  D2,  A5,  and  A6  are  all  collapsed 

tst.w 

D2 

;  did  this  shift  get  down  to  zero? 

bne.s 

NLOOP 

;  no:  skip  to  first  kludged  loop 

cmp.w 

#0,  A5 

;  is  this  zero? 

bne.s 

NLOOP 

;  no:  again,  can't  make  further  optimization 

cmp.w 

#0,  A6 

;  how  about  this? 

bne.s 

NLOOP 

;  no:  the  best-laid  plans  of  mice  and  men... 

cmp.w 

A2,D5 

;  is  there  no  check  on  the  column? 

bne.s 

NLOOP 

;  not  a  power-of-two  columns;  rats! 

move.w 

A0,D6 

;  grab  the  base  address  of  the  source 

and.b 

#7,D6 

;  select  the  low  three  bits 

bne.s 

NLOOP 

;  doesn't  sit  on  a  byte  boundary;  phooey 

move.w 

A1,D6 

;  now  try  the  base  of  the  destination 

and.b 

#7,D6 

;  and  select  its  bit  offset 

beq.s 

SCREEN 

;  yes!  do  extra-special  loop! 

;  fast. 

out  not 

super-fast  loop,  used  when  both  source  and  destination 

;  bitmaps  have  strides  which 

are  powers  of  two. 

NLOOP 

;  here  for  another  time  around 

cmp.l 

A4,D0 

;  is  row  in  bounds? 

bge.s 

NNEXT 

;  no:  clip  this 

NLOOPRCW 

;  here  when  we  know  the  row  number  is  OK 

move.w 

DO,  D6 

;  copy  the  sequence  element 

and.w 

D5,D6 

;  find  just  the  column  number 

cmp.w 

A2,D6 

;  too  far  to  the  right?  (past  oCols?) 

bgt.s 

NNEXT 

;  yes:  skip  out 

move.l 

D0,D4 

;  we  know  element  will  be  used;  copy  it 

sub.w 

D6,D4 

;  remove  column's  bits 

lsr.l 

D2,D4 

;  shift  down  to  row,  NOT  right-justified 

(continued  on  page  98) 
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LiStiDQ  Oil©  (Listing  continued,  text  begins  on  page  48.) 

move.w 

A5,D7 

get  log2  of  stride  per  row  (in  bits) 

move.l 

D4,D1 

make  a  working  copy  of  the  row  number 

lsl.l 

D7,D1 

*  stride/row  is  source  row's  offset  in  bits 

add.l 

D6,D1 

add  in  column  offset  (bits) 

add.l 

A0,D1 

plus  base  of  bitmap  (bits  [sic]) 

move.b 

D1,D7 

save  the  bottom  three  bits  for  the  BTST 

lsr.l 

S3,D1 

while  we  shift  down  to  a  byte  address 

move.l 

Dl,  A3 

and  save  that  for  the  test,  too 

not  .b 

D7 

get  right  bit  number  (compute  #7-D7) 

move.w 

A6,D1 

extract  log2  of  destination  stride 

lsl.l 

Dl,  D4 

stride*row  number  =  dest  row's  offset  in  bits 

add.l 

D6,D4 

add  in  column  bit  offset 

add.l 

A1,D4 

and  base  address,  also  in  bits 

move.b 

D4,D6 

set  aside  the  bit  displacement 

lsr.l 

#3,D4 

make  a  byte  displacement 

not.b 

D6 

get  right  bit  number  (compute  #7-D6) 

btst 

D7,  (A3) 

test  the  D7th  bit  of  source  byte 

move.l 

D4,  A3 

point  to  target  byte  (don't  ruin  CC  from  btst) 

bne.s 

NSETON 

if  on,  go  set  destination  on 

bclr 

D6,  (A3) 

else  clear  destination  bit 

NNEXT 

jump  here  if  DO  not  in  bounds 

lsr.l 

#1,D0 

slide  one  bit  to  the  right 

bhi.s 

N LOOP ROW 

if  no  carry  out,  but  not  zero,  loop 

eor.l 

D3,D0 

flip  magic  bits. . . 

cmp.l 

D3,D0 

...but  has  this  brought  us  to  square  1? 

bne.s 

NLOOP 

if  not,  loop  back;  else... 

bra.s 

DONE 

...we're  finished 

NSETON 

bset 

D6,  (A3) 

source  bit  was  on:  set  destination  on 

lsr.l 

#1,D0 

slide  one  bit  to  the  right 

bhi.s 

NLOOPROW 

if  no  carry  out,  but  not  zero,  loop 

eor.l 

D3,D0 

flip  magic  bits. . . 

cmp.l 

D3,D0 

...but  has  this  brought  us  to  square  1? 

bne.s 

NLOOP 

if  not,  loop  back;  else  fall  through 

bra.s 

DONE 

and  finish 

super-special  case,  which  happens  to  hold  for  the  whole  mac  screen  — 

or  subsets  of  it 

which  are  as  wide  as  the  screen,  here,  we've  found  that 

the  shift  counts 

in  D2,  A5, 

and  A6  can  all  be  collapsed  to  zero. 

and  D5  equals  A 2 

so  there's  no  need  to  check  whether  D6  is  in  limits  — 

or  even  take  it  out  of  DO! 

so,  this  loop  is  the  NLOOP  code  without 

the  shifts  or  the  check  on  the  column  number,  should  run  like  a  bat; 
have  you  ever  seen  a  bat  run? 

one  further  restriction  —  the  addresses  in  AO  and  A1  must  point  to 
integral  byte  addresses  with  no  bit  offset.  (this  still  holds 

for  full-screen 

copies.)  because  both  the  source  and  destination  are 

byte-aligned,  we 

can  skip  the  ritual  Negation  Of  The  Bit  Offset  which 

the  68000  usually  demands. 

SCREEN  ;  here  to  set  up  to 

do  the  whole  screen,  or  at  least  its  width 

move.l 

A0,D6 

take  the  base  source  address  — 

lsr.l 

#3,D6 

...  and  make  it  a  byte  address 

move.l 

D6,  AO 

replace  pointer 

move.l 

A1,D6 

now  do  the  same . . . 

lsr.l 

#3,D6 

...for... 

move.l 

D6,A1 

...the  destination  address 

bra.s 

N2LOOP 

jump  into  loop 

N 2 HEAD 

here  when  we  shifted  and  a  bit  carried  out 

eor.l 

D3,D0 

flip  magic  bits  to  make  the  sequence  work 

N2L00P 

here  for  another  time  around 

cmp.  1 

A4,  DO 

is  row  in  bounds? 

bge.s 

N 2 NEXT 

no:  clip  this 

N2  LOOP  RCW 

;  here  when  we  know  the  row  number  is  OK 

move.l 

D0,D1 

copy  row  number,  shifted  up,  plus  column  offset 

lsr.l 

#3,D1 

while  we  shift  down  to  a  word  offset 

btst 

D0,0(A0,D1)  ;  test  bit  of  source  byte 

bne.s 

N2SETON 

;  if  on,  go  set  destination  on 

bclr 

DO, 0 (Al, Dl)  ;  else  clear  destination  bit 

N 2 NEXT 

;  jump  here  if  DO  not  in  bounds 

lsr.l 

#1,D0 

;  slide  one  bit  to  the  right 

bhi.s 

N2  LOOP  ROW 

;  if  no  carry  out,  but  not  zero,  loop 

bne.s 

N 2 HEAD 

;  if  carry  out,  but  not  zero,  loop  earlier 

bra.s 

N 2 DONE 

;  0  means  next  sequence  element  would  have  been  D3 

N2SET0N 
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UStinQ  One  (Listing  continued, 

text  begins  on  page  48.) 

bset 

DO,  0  (A1,D1) 

source  bit  was  on:  set  destination  on 

lsr.l 

#1,D0 

slide  one  bit  to  the  right 

bhi.s 

N2L00PRCW  ;  if  no  carry  out,  but  not  zero,  loop 

bne.s 

N  2  HEAD 

if  carry  out,  but  not  zero,  loop  earlier 

; 

zero  means  the  loop  has  closed  on  itself 

because  our  bit- 

numbering  isn't  like  that  of  the  other  two  loops,  we  set 

up  DO  and  D1  ourselves  before  joining 

a  bit  late  with  the  common  code  to 

get  the  last  bit 

N 

2  DONE 

move.l 

(SP)+,A6  ;  restore  the  stack  frame  pointer 

move.w 

srcOurs+oIbits (A6) ,D0  ;  get  bit  offset  of  left  margin 

move.w 

dstOurs+oLbits (A6) ,D1  ;  and  ditto  for  target 

bra 

DCNEA  ;  go  do  first  bit,  which  sequence  doesn't  cover 

mulchk  —  see  if 

we  can  do  without  multiply  instructions. 

calling  sequence 

A5  holds  the  source  stride 

A6  holds  the  destination  stride 

clr.w 

-(SP) 

reserve  room  for  boolean  function  return 

bsr 

MULCHK 

go  check  things  out 

tst  .w 

(SP)  + 

test  result 

bne.s 

SHIFT 

if  non-zero,  we  can  shift  and  not  multiply 

(if  we  can 

shift,  A5  and  A6  have  been  turned  into  shift  counts) 

registers  used: 

none  (A5,  A6) 

MULCHK 

movem.  1 

D0-D3, -  (SP) 

stack  caller's  registers 

move.l 

A5,D0 

take  the  source  stride 

bsr 

BITWIDTH  ;  take  log  base  2 

move.l 

#1,D1 

pick  up  a  one. . . 

lsl.l 

D0,D1 

...and  try  to  recreate  the  stride 

cup.  1 

A5,D1 

does  it  cone  out  the  same? 

bne.s 

NCMULCHK  ;  nope  —  bag  it 

move.w 

D0,D3 

save  magic  logarithm  of  source  stride 

move.l 

A6,D0 

yes  —  now  how  about  destination  stride? 

bsr 

BITWIDTH  ;  convert 

that  one,  also 

move.l 

#1,D1 

again,  try  a  single  bit... 

lsl.l 

D0,D1 

...and  see  if  original  #  was  1  bit 

aup.l 

A6,D1 

how'd  it  come  out? 

bne.s 

NCMULCHK  ;  doesn't  match  —  bag  this 

we  can  shift  instead  of  multiplying. 

change  address  registers  &  tell 

our  caller. 

move.w 

D3,A5 

set  up  shift  for  source  stride 

move.w 

D0,A6 

and  for  destination  stride 

St 

4+16 (SP)  ;  tell  our 

caller  what's  what 

bra.s 

MULRET 

and  return 

NCMULCHK 

sf  4+16  (SP) 

tell  caller  we  can't  optimize 

MULRET 

here  to  return;  result  set 

movem. 1 

(SP)  +  ,D0-D3 

pop  some  registers 

rts 

all  set 

table  of  (longword)  masks  to  XOR  in  strange  Knuthian  algorithm. 

the  first  table 

entry  is  for  a  bit-width  of  two,  so  the  table  actually 

starts  two  bytes  before  that . 

hardware  jocks  among  you  may  recognize 

this  scheme  as  the  software  analog  of  a  "maximum-length  sequence 

generator". 

to  save  a  bit  of  room,  masks  are  packed  in  bytes,  but  should  be  aligned 

as  described  in 

the  code  before  being 

used. 

table  . equ 

*-2 

first  element  is  #2 

.byte 

3o 

2 

.byte 

3o 

3 

.byte 

3o 

4 

.byte 

5o 

5 

.byte 

3o 

6 

100 
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(Listing  continued,  text  begins  on  page  48.) 

.byte 

3o 

7 

.byte 

27o 

8 

.byte 

21o 

9 

.byte 

llo 

10 

.byte 

5o 

11 

.byte 

145o 

12 

.byte 

33o 

13 

.byte 

65o 

14 

•  t>yte 

3o 

15 

.byte 

55o 

16 

.byte 

llo 

17 

.byte 

201o 

18 

.byte 

71o 

19 

.byte 

llo 

20 

.byte 

5o 

21 

.byte 

3o 

22 

.byte 

41o 

23 

.byte 

33o 

24 

.byte 

llo 

25 

.byte 

161o 

26 

.byte 

71o 

27 

.byte 

llo 

28 

.byte 

5o 

29 

.byte 

145o 

30 

.byte 

llo 

31 

.byte 

243o 

32 

align  2 

convert  —  convert  a  parameter  bitMap  and  rectangle  to  our  internal  form. 

calling  sequence 

lea 

bitMap,  AO  ;  point  to  the  bitmap 

lea 

rect ,  A1 

and  the  rectangle  inside  it 

lea 

ours, A2 

and  our  data  structure 

bsr 

CONVERT 

call  us 

when  done,  all  fields  of  the  "ours"  structure  are  filled  in: 

oBase  is 

address  of  first  byte  in  which  any  bits  are  to  be  changed 

olbits  is  number  of  bits  into 

that  first  byte  which  are  ignored 

oStride 

Ls  the  stride  from  one  row  to  the  next,  in  bits 

oCols  is 

the  number  of  columns  in  the  rectangle 

oRows  is 

the  number  of  rows 

registers  used: 

DO,  Dl,  D2 

CONVERT 

save  the  starting  word  and  bit  address  of  the  stuff: 

move.w 

top (Al)  ,D0 

pick  up  top  of  inner  rectangle 

sub.w 

bounds+top (AO) , DO 

figure  rows  to  skip  within  bitmap 

mulu 

rowbytes (AO) ,D0 

compute  bytes  to  skip  (relative  offset) 

add.  1 

baseaddr (AO) ,D0 

;  find  absolute  address  of  first  row  to  use 

move.w 

left (Al) , Dl 

;  pick  up  left  coordinate  of  inner  rect 

sub.w 

bounds+left (AO) ,D1 

;  find  columns  to  skip 

move.w 

D1,D2 

;  copy  that 

and.w 

#7,D2 

;  compute  bits  to  skip  in  first  byte 

move.w 

D2,oIiilts(A2) 

;  save  that  in  the  structure 

lsr.w 

#3,D1 

;  convert  column  count  from  bits  to  bytes 

ext.l 

Dl 

;  convert  to  a  long  value,  so  we  can... 

add.  1 

Dl,  DO 

;  add  to  row  start  in  bitmap  to  find  1st  byte 

move. 1 

DO,  oBase  (A2) 

;  save  that  in  the  structure 

save  stride  of  bitmap;  this  is  same  as  for  the  original,  but  in  bits. 

move.w 

rowbytes (AO) ,D0 

;  pick  up  the  stride 

lsl.w 

#3,  DO 

?  multiply  by  eight  to  get  a  bit  stride 

rrave.w 

DO, oStride  (A2) 

;  stick  it  in  the  target  structure 

save  the  number 

of  rows  and  columns. 

move.w 

bottom  (Al)  ,  DO 

;  get  the  bottom  of  the  rectangle 

sub.w 

top(Al)  ,D0 

;  less  the  top  coordinate 

sub.w 

#1,D0 

;  get  number  of  highest  row  (1st  is  zero) 

kxni.s 

CERROR 

;  nothing  to  do?  (note:  0  IS  ok) 

move.w 

DO, oRows  (A2) ; 

;  save  that  in  the  structure 

nvDve.w 

right (Al) ,D0 

;  get  the  right  edge  of  the  rectangle 

sub.w 

left (Al)  ,D0 

;  less  the  left  coordinate 

sub.w 

#1,D0 

;  make  it  zero-based 

tmi 

CERROR 

;  nothing  to  do  here? 

move.w 

DO,  oCols  (A2) 

;  save  that  in  the  structure 
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all  done,  return. 

rts 

error  found  in  CONVERT,  pop  return 

and  jump  to  the  error  routine,  such  as  it  is. 

:error 

addq.l 

#4,  SP 

;  pop  four  bytes  of  return  address. 

bra.s 

ERROR 

;  return  silently 

log2  —  find  the  ceiling  of  the  log, 

base  2,  of  a  number. 

bitwidth  —  find 

how  many  bits  wide 

a  number  is 

calling  sequence: 

move.l 

N,  DO 

;  store  the  number  in  DO 

bsr 

L0G2 

;  call  us 

move.w 

DO,... 

;  DO  contains  the  word  result 

registers  used:  D2,  (DO) 

BITWIDTH 

sub.l 

#1,D0 

;  so  2**n  works  right  (sigh) 

LOG  2 

tst.l 

DO 

;  did  they  pass  us  a  zero? 

beq.s 

LOGDONE 

;  if  DO  was  one,  answer  is  zero 

move.w 

#32, D2 

;  initialize  count 

L0G2LP 

lsl.l 

#1,D0 

;  slide  bits  to  the  left  by  one 

dbcs 

D2,D0G2LP  ;  decrement  and  loop  until  a  bit  falls  off 

move.w 

D2,D0 

;  else  save  our  value  where  we  promised  it 

LOGDONE 

;  here  with  final  value  in  DO 

rts 

;  and  return 

.end  ?  procedure  dissBits 

End  Listing 
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LiSt'lDQ  One  (Text  begins  on  page  120.) 

Listing  1.  Using  the  predefined  NUMERI C_ERROR  Ada  exception. 

begin 

function  Power  (BASE,  EXPONENT  :  FLOAT)  return  FLOAT  Is 

—  sequence  of  statements 

Conmand  Worker; 

begin 

—  sequence  of  statements 
exception 

return  Exp (Exponent  *  Ln(Base)); 

when  Boss_Angry  *■> 

—  Try  to  deal  with  the  boss 

end  Conmand  Foreman; 

—  This  is  the  area  to  handle  exceptions 

exception 

begin 

when  NUMERIC  ERROR  -> 

—  sequence  of  statements 

if  Base  -  0  then 

Conmand  Worker; 

return  0; 

Conmand  Foreman; 

else  —  return  "infinity" 

-  sequence  of  statements 

return  FLOAT' FIRST; 

exception 

end  if; 

when  Boss  Angry  -*> 

end  Power; 

—  fire  foreman 
end  The  Boss; 

End  Listing  One 

End  Listing  Three 

Listing  Two 

Listing  Four 

Listing  2.  General  form  of  exception  handling  block. 

Listing  4.  The  retry  approach  with  exception  handlers. 

procedure  Big_Trouble  is 

with  TEXT__IO;  use  TEXT_IO; 

Negative  Absolute  Temperature, 

procedure  Days  of  our  lives; 

Negative  Pressure,  Negative  Volume  :  exception; 

type  Day  Name  is  (Sun,  Mon,  Tue,  Wed,  Thu,  Fir,  Sat); 

Temperature,  Pressure,  Volume  :  FLOAT; 

package  DAY_IO  Is  new  TEXT_IO.ENUMERATION_IO  (Day_Name) ; 
use  Day  10; 

begin 

—  define  time-out 

—  procedure  to  calculate  temperature.  Pressure  and  volume 

Time_Out  :  constant  integer  5; 

—  define  variable 

—  Calculate  temperature  in  Rankin 

Day  :  Day  Name; 

if  Temperature  <  0.0  then 

—  define  exception 

raise  Negative  Absolute  Temperature; 

Wrong  Day  :  exception; 

end  if; 

—  Calculate  pressure  and  volume 

begin 

for  Count  in  l..Tlme  Out  loop 

if  Pressure  <0.0  then 

raise  Negative  Pressure; 

PUT ("What  day  is  it?");  NEW  LINE; 

end  If; 

if  Volume  <  0.0  then 

begin  —  exception  handling  block  starts  here 

GET (Day);  NEW  LINE; 

raise  Negative  Volume; 

PUT  ("Have  a  nice  ");  PUT (Day);  NEW  LINE; 

end  if; 

exit;  —  exit  for  loop  when  answer  is  correct 

—  other  procedure  statements 

exception 

exception  —  handling  block 

when  CONSTRAI NT_ERR0R  -> 
if  Count  -  Time  Out  then 

when  NUMERIC  ERROR  -> 

PUT ("Sorry!  Loop  time-out"); 

—  handle  bad  function  arguments,  underflow  or  overflow 

raise  Wrong_Day; 
else 

when  Negative  Absolute  Temperature  ■> 

PUT ("Sorry!  No  such  weekday");  NEW  LINE; 

PUT ("You  have  ");  PUT (Time  Out  -  Count); 

—  handle  negative  absolute  temperature  results 

PUT ("  more  times  to  try);  NEW_LINE; 

PUT ("Let  us  try  once  more");  NEW  LINE; 

when  Negative  Pressure  |  Negative  Volume  -> 

end  if; 

end;  —  end  error  handler 

—  handle  negative  pressure  or  volume  values 

end  loop;  —  end  for  loop 
end  Days_of_our_lives; 

when  others  -> 

End  Listing  Four 

—  handle  all  other  problems 

Listing  Five 

end  Big  trouble; 

End  Listing  Two 

Listing  5.  Using  an  alternative  method  with  exception  handlers. 

Listing  Three 

with  TEXT  IO;  use  TEXT  IO; 

Listing  3.  Ada  exception  handling  scope. 

procedure  Root  is 

Result,  Guessl,  Guess2,  Accuracy  :  FLOAT; 

procedure  The  Boss  is 

Max_Iter  :  INTEGER; 

Diverge,  Fatal  Error  ;  exception; 

Boss_Angry  ;  exception; 

procedure  Conmand_Worker  is 

function  F (X  :  FLOAT)  return  FLOAT  is 

begin 

begin 

—  sequence  of  statements 

return  X  *  X  *  X  -  5.0; 

if  income  <  0.0  then  raise  Boss_Angry;  end  if; 

—  sequence  of  statements 

end  Command  Worker; 

procedure  Newton (Guess,  Accuracy  :  FLOAT;  Max  Iter  :  INTEGER)  is 
—  Newton's  method  to  find  the  root  of  a  function 

procedure  Command  Foreman  is 

(continued  on  page  113) 
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LiStinQ  Five  (Listing  continued,  text  begins  on  page  120.) 

Funct,  Derivative,  h,  Diff  :  FLOAT; 

end  Bisection; 

begin 

begin  —  Root  — 

loop 

PUT ("Enter  first  guess  for  the  root  ");  GET(Guessl);  NEW_LINE; 

if  ABS  (Guess)  >1.0  then  h  0.01  *  Guess; 

PUT("Enter  second  guess  for  the  root  ");  GET(Guess2);  NEW  LINE; 

else  h  0.01; 

PUT("Enter  desired  accuracy");  GET (Accuracy) ;  NEW  LINE; 

end  if; 

PUT("Enter  maximum  number  of  iterations  ");  GET (Max_Iter) ; 

NEW  LINE;  NEW  LINE; 

Funct  F (Guess); 

PUT ("Root  -  "); 

Derivative  (F (Guess  +  h)  -  Funct)  /  h; 

begin  —  start  outer  exception  handler 

Diff  Funct  /  Derivative; 

—  Try  Newton's  method  first 

Guess  Guess  -  Diff; 

Newton (Guessl,  Accuracy,  Max_Iter) ; 
exit;  —  terminate  program  successfully 

Max  Iter  Max  Iter  -  1; 

exception 

if  Max  Iter  <  0  then 

when  NUMERIC  ERROR  I  Diverge  -> 

raise  Diverge; 

begin  —  start  inner  exception  handler 

end  if; 

—  This  method  will  definitely  work,  but  is  slower 

Bisection (Guessl,  Guess2,  Accuracy); 

exit;  —  terminate  successfully  with  second  method 

if  ABS (Diff)  o  Accuracy  then  exit;  end  if; 

exception 

end  loop; 

when  others  -> 

PUT (“Fatal  Error.  Cannot  recover"); 

PUT (Guess) ; 

NEW_LINE; 

end;  —  inner  exception  handler 

end  Newton; 

end;  —  outer  exception  handler 

end  Root;  £n(|  Listing  Five 

procedure  Bisect  ion (A,  B,  Accuracy  :  FLOAT;  Max  Iter  ;  INTEGER)  is 

—  Bisection  method  to  find  the  root  of  a  function 

Listing  Six 

Mean,  FA,  FB,  FM  :  FLOAT; 

Listing  6.  The  clean  up  method  used  in  exception  handlers. 

begin 

FA  F (A) ;  FB  F (B) ; 

—  Get  midpoint  estimate  for  the  root 

with  TEXT  10;  use  TEXT  10; 

Mean  (A  +  B)  /  2.0; 

procedure  Root  is 

while  ABS (A  -  B)  >  Accuracy  loop 

Result,  Guess,  Accuracy  :  FLOAT; 

Max  Iter  :  INTEGER) 

FM  F (Mean) ; 

Diverge  ;  exception; 

—  Does  A  and  Mean  have  same  function  sign? 
if  FM  *  FA  >  0.0 

then 

function  F (X  :  FLOAT)  return  FLOAT  is 

A  Mean;  FA  FM; 

else 

begin 

B  Mean;  FB  FM; 

return  X  *  X  *  X  -  5.0; 

end  if; 

end  F; 

—  Get  midpoint  estimate  for  the  root 

Mean  (A  +  B)  /  2.0; 

procedure  Newton  (Guess,  Accuracy  :  FKJAT;  Max_Iter  :  INTEGER)  is 
—  Newton's  method  to  find  the  root  of  a  function 

Max  Iter  Max  Iter  -  1; 

if  Max  Iter  <  0  then 

Funct,  Derivative,  h,  Diff  :  FLOAT; 

raise  Fatal  Error; 

end  if; 

begin 

loop 

end  loop; 

if  ABS (Guess)  >1.0  then  h  0.01  *  Guess; 

else  h  0.01; 

PUT (Mean) ; 

end  if; 
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LiStjnQ  SiX  (Listing  continued,  text  begins  on  page  120.) 

Funct  F (Guess);  I  Listing  Seven 


Funct  F (Guess); 

Derivative  (F (Guess  +  h)  -  Funct)  /  h; 
Diff  Funct  /  Derivative; 

Guess  Guess  -  Diff; 

Max  _Iter  Max_Iter  -  1; 
if  Max_Iter  <  0  then 
raise  Diverge; 
end  if; 


if  ABS (Diff)  o  Accuracy  then  exit;  end  if; 
end  loop; 

NEW_LINE;  NEW_LINE; 

PUT ("Root  -  ");  PUT (Guess); 

NEW_LINE;  NEW_LINE; 
end  Newton; 

begin  —  Root  — 

PUT ("Enter  guess  for  the  root  ") ;  GET (Guess);  NEW_LINE; 

PUT ("Enter  desired  accuracy");  GET (Accuracy) ;  NEW_LINE; 

PUT ("Enter  maximum  number  of  iterations  ");  GET (Max_Iter) ; 
loop 

begin  —  start  exception  handler 
—  Try  Newton's  method  first 
Newton  (Guess,  Accuracy,  Max_Iter) ; 

exit;  —  exit  open  loop  and  terminate  program  successfully 
exception 

when  Diverge  -> 

PUT  ("Enter  guess  for  the  root  "); 

GET (Guess);  NEW_LINE; 
end;  —  exception  handler 
end  loop; 

end  Root;  End  Listing  Six 


Listing  7.  Module  SafeLibO,  a  subset  of  MathLlbO  with  error 

trapping  features. 

DEFINITION  MODULE  SafeLibO; 

(*  Definition  module  of  SafeLibO,  the  safer  version  of  MathLlbO  *) 

(*  The  EXPORT  is  not  needed  for  new  Modula-2  definition  *) 

EXPORT  QUALIFIED  SQRT,  121,  EXP,  EXPRANGE; 

(*  Largest  argument  for  oxp(X)  that  yields  exp()  -  9.9999E+99  *) 

CONST  EXPRANGE  -  230.26; 


PROCEDURE  SQRT (X  :  REAL;  VAR  ArgumentERROR  :  BOOLEAN)  :  REAL; 
(*  Square  root  function  with  an  argument  error  flag  *) 

PROCEDURE  LN  (X  :  REAL;  VA£_  ArgumentERROR  ;  BOOLEAN)  :  REAL; 

(*  Natural  logarithm  function  with  an  argument  error  flag  *) 


PROCEDURE  EXP (X  :  REAL;  VAR  ArgumentERROR  ;  BOOLEAN)  :  REAL; 
(*  Exponential  function  with  an  argument  error  flag  *) 


PROCEDURE  GetNext (Current,  MaxFlag  :  CARDINAL; 

VAR  Found  ;  BOOLEAN; 

ErrorFlag  ;  ARRAY  OF  BOOLEAN)  :  CARDINAL 

END  SafeLibO. 


IMPLEMENTATION  MODULE  SafeLibO; 

FROM  MathLlbO  IMPORT  sqrt,  exp.  In; 

PROCEDURE  SQRT (X  :  REAL;  VAR  ArgumentERROR  :  BOOLEAN)  :  REAL; 
(*  Square  root  function  with  an  argument  error  flag  *) 

BEGIN 

ArgumentERROR  FALSE; 

IF  X  <  0.0  THEN 

ArgumentERROR  TRUE; 

X  ABS (X) 

END; 

RETURN  sqrt (X) 


PROCEDURE  LN (X  :  REAL;  VAR  ArgumentERROR  :  BOOLEAN)  :  REAL; 
(*  Natural  logarithm  function  with  an  argument  error  flag  *) 
ELSE  X  10.0 

END; 

END; 

RETURN  In (X) 


PROCEDURE  EXP  (X  ;  REAL;  VAR  ArgumentERROR  ;  BOOLEAN)  :  REAL; 
(*  Exponential  function  with  an  argument  error  flag  *) 

BEGIN 

ArgumentERROR  :■  FALSE; 

IF  X  >  EXPRANGE 
THEN 

ArgumentERROR  TRUE; 

BEGIN 

ArgumentERROR  FALSE; 

IF  X  <-  0.0  THEN 

ArgumentERROR  : -  TRUE; 

IF  X  <  0.0  THEN  X  ABS(X) 

X  I-  1.0  /  EXPRANGE 


RETURN  exp (X) 


PROCEDURE  GetNext  (Current,  MaxFlag  :  CARDINAL; 

VAR  Found  :  BOOLEAN; 

ErrorFlag  :  ARRAY  OF  BOOLEAN)  :  CARDINAL; 
VAR  Last  ;  CARDINAL; 
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BEGIN 

Last  HIGH (ErrorFlag) ; 

IF  MaxFlag  >  Last  THEN  MaxFlag  Last  END; 

Found  FALSE; 

WHILE  (Current  <-  Last)  AND  (NOT  Found)  DO 

IF  ErrorFlag [Current]  THEN  Found  TRUE  END; 
INC (Current) ; 

END; 


RETURN  Current 
END  GetNext; 

END  SafeLibO. 


End  Listing  Seven 


Listing  Eight 


Listing  8.  Module  SafeLibl ,  a  second  alternate  subset  of 
MathLibO  with  error  trapping  features. 


DEFINITION  MODULE  SafeLibl; 

(*  Definition  module  of  SafeLibl,  the  safer  version  of  MathLibl  *) 

(*  The  EXPORT  is  not  needed  for  new  Modula-2  definition  *) 

EXPORT  QUALIFIED  SQRT,  LN,  EXP,  EXPRANGE, 

MAXERRORSTACK,  ErrorStack; 

(*  Largest  argument  for  exp(X)  that  yields  exp()  =  9.9999E+99  *) 
CONST  EXPRANGE  -  230.26; 

MAXERRORSTACK  -  50; 


VAR  ErrorStack  :  RECORD 

HeightErrorStack  :  [0. .MAXERRORSTACK] ; 
FuncName  :  ARRAY  [1.  .MAXERRORSTACK]  OF 
ARRAY  [0..3]  OF  CHAR 

END; 


PROCEDURE  SQRT (X  :  REAL)  :  REAL; 
(*  Square  root  function  *) 

PROCEDURE  LN (X  :  REAL)  :  REAL; 

(*  Natural  logarithm  function  *) 

PROCEDURE  EXP (X  :  REAL)  :  REAL; 
(*  Exponential  function  *) 

END  SafeLibl. 


IMPLEMENTATION  MODULE  SafeLibl; 

FRCW  MathLibO  IMPORT  sqrt,  exp.  In; 

PROCEDURE  SQRT (X  :  REAL)  :  REAL; 

(*  Square  root  function  *) 

BEGIN 

IF  X  <  0.  THEN 

PushErrorStack ("SQRT") ; 

X  ABS(X) ; 

END; 

RETURN  sqrt (X) 


END  SQRT; 


PROCEDURE  LN (X  :  REAL)  :  REAL; 

{*  Natural  logarit?vn  function  *) 

BEGIN 

IF  X  <-  0.0  THEN 

Argument ERROR  TRUE; 

IF  X  <  0.0  THEN  X  ABS (X) 

ELSE  X  10.0 

END; 

END; 


RETURN  In (X) 
END  LN; 


PROCEDURE  EXP  (X  :  REAL)  :  REAL; 
(*  Exponential  function  *) 
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UstinQ  Eight  (Listing  continued,  text  begins  on 

page  120.) 

BEGIN 

END; 

WRITELN; 

IF  X  >  EXP RANGE 

END; 

THEN 

END; 

Argument ERROR  TRUE; 

X  1.0  /  EXPRANGE 

END; 

BEGIN 

setupRa;  (*  SETUP  BIGARRAY  *) 

RETURN  exp (X) 

makeRA(A,  1.0,  noinit) ; 

END  EXP; 

(*  Creating  test  matrix  *) 

FOR  J  1  TO  MAX  DO  BEGIN 

FOR  K  1  TO  MAX  DO 

PROCEDURE  ClearErrorStack; 

setRA  (A,  K,  J,  1.0); 

setRA (A,  J,  J,  2.0) 

BEGIN 

END; 

ErrorStack.HeightErrorStack  0 

END  ClearErrorStack; 

(*  The  test  below  will  ensure  that  the  user  does  not  spend  *) 

(*  a  lot  of  time  looking  at  a  rather  obvious  matrix  when  its  *) 

(*  size  is  large.  *) 

PROCEDURE  PushErrorStack (Name  :  ARRAY  OF  CHAR) ; 

IF  MAX  <-  10  THEN  BEGIN 

VAR  I  :  CARDINAL; 

WRITELN ('Matrix  is  '); 

SHOW  MATRIX; 

BEGIN 

WRITELN;  WRITELN; 

WITH  ErrorStack  DO 

END; 

INC (HeightErrorStack) ; 

WRITELN ('Starting  matrix  invertion'); 

I  0; 

DET  1.0; 

WHILE  (I  <-  HIGH (Name))  AND  (Name [I]  <>  0C)  DO 

FOR  J  1  TO  MAX  DO  BEGIN 

FuncName [HeightErrorStack, I]  Name [I) 

PIVOT  getRA  (A, J,  J) ; 

END; 

DET  DET  *  PIVOT; 

setRA  (A,  J,  J,  1.0)  ; 

IF  I  <  HIGH  (Name)  THEN  FuncName[I+l]  0C  END; 

FOR  K  1  TO  MAX  DO 

setRA  (A,  J,K,  (getRA  (A,  J,K)  /  PIVOT)); 

END;  (*  WITH  *) 

FOR  K  1  TO  MAX  DO 

END  PushErrorStack; 

IF  K  <>  J  THEN  BEGIN 

TEMPO  getRA  (A,  K,  J)  ; 

setRA (A, K, J, 0.0) ; 

PROCEDURE  InErrorO  :  BOOLEAN; 

FOR  L  1  TO  MAX  DO 

BEGIN 

setRA  (A,  K,  L,  (getRA  (A,  K,  L)  -  getRA  (A,  J,  L)  *  TEMPO)); 

RETURN  (ErrorStack.HeightErrorStack  >  0) 

END  InError; 

END;  (*  End  of  outer  for- loop  *) 

WRITELN (' PRESS  <CR>  to  view  matrix  ');  READLN(CH);  WRITELN; 

BEGIN  (*  Module  initialization  *) 

WRITELN ('The  inverse  matrix  is  '); 

ClearErrorStack 

SHOW  MATRIX; 

END  SafeLibl. 

WRITE ('Determinant  -  '); 

WRITE  (DET)  ; 

WRITELN;  WRITELN; 

END. 

End  Listing  Eight 

End  Listings 

Listing  Nine 

Listing  9.  Turbo  Pascal  matrix  inversion  program  using  Turbo 

Extender  utilities. 

PROGRAM  INVERT; 

(*  Program  to  test  speed  of  floating  point  matrix  inversion.  *) 

(*  The  program  will  form  a  matrix  with  ones'  in  every  member  *) 

(*  except  the  diagonals  which  will  have  values  of  2.  *) 

CONST  MAX  -  140; 

RArowsPerPage  -  20; 

RAcolsPerPage  -  20; 

RApagesDown  -  7; 

RApagesAcross  -  7; 

TYPE  RAelementType  -  REAL; 

(*$I  RARRAY. INC*) 

VAR  J,  K,  L  ;  INTEGER; 

DET,  PIVOT,  TEMPO  :  REAL; 

A  :  RAarrayPtr; 

CH  :  CHAR; 

PROCEDURE  SHCW_MATRIX; 

BEGIN 

FOR  J  1  TO  MAX  DO  BEGIN 

FOR  K  1  TO  MAX  DO  BEGIN 

WRITE (getRA (A, K, J) ) ; 

WRITE ( '  ' )  ; 
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Error  Handling  in  Ada  and  Modula-2,  Large  Turbo  Pascal  Matrices 


In  this  issue  I  will  discuss  error 
handling  (also  known  as  excep¬ 
tions)  iq  Ada  an<j  Modula-2.  In  the 
case  of  Modula-2,  I  will  concentrate 
on  handling  errors  for  several  math¬ 
ematical  functions  exported  by  the 
standard  library  MathLibO.  The  Pas¬ 
cal  section  of  the  column  looks  at 
writing  programs  to  handle  matrices 
with  sizes  greater  than  64K  using  the 
Turbo  Extender  package. 

Exceptions  in  Ada 

Ada  was  designed  for  numerous  ap¬ 
plications,  including  real-time  sys¬ 
tems.  The  language's  designers  chose 
to  tackle  error  handling  effectively 
rather  than  pay  it  lip  service  as  did 
the  designers  of  standard  Pascal  and 
Modula-2.  As  a  result,  Ada  recognizes 
an  explicit  error-handling  mecha¬ 
nism,  namely,  the  exception.  The  ba¬ 
sic  concept  behind  exceptions  is  for  a 
program  to  detect  an  error  condition 
and  direct  the  program  flow  control 
to  resume  at  the  exception  handling 
area.  No  explicit  GOTO  statements  are 
used,  although  their  effect  is  still  at¬ 
tained.  Thus,  programmers  are  re¬ 
lieved  from  using  “defensive”  pro¬ 
gramming  methods,  as  is  the  case 
with  standard  Pascal  and  Modula-2. 

Ada  has  five  predefined  exceptions 
—the  CONSTRAINT-ERROR,  NUMERIC 
-ERROR,  PROGRAM-ERROR,  STOR¬ 
AGE-ERROR,  and  TASKING-ERROR. 
Listing  One,  page  104,  shows  the  pre¬ 
defined  NUMERIC— ERROR  exception 


by  Namir  Clement 
Shammas 


in  use  with  a  floating-point  power 
function.  In  this  example,  the  func¬ 
tion  body  consists  of  one  statement 
followed  by  the  exception  handling 
block.  Ada  requires  that  such  blocks 
be  placed  at  the  end  of  a  program  or 
routine  (more  about  the  scope  of  ex¬ 
ceptions  later).  Zero  or  negative  values 


for  the  Base  variable  are  invalid  argu¬ 
ments  for  the  natural  logarithm  func¬ 
tion.  The  exception  handling  block 
examines  the  value  assigned  to  Base. 
If  it  equals  zero,  the  function  returns  a 
zero;  otherwise,  it  returns  the  largest 
negative  value  that  is  supported  by 
the  implementation.  Notice  that  if  the 
arguments  of  function  Power  are  val¬ 
id  but  large  in  magnitude,  an  over¬ 
flow  occurs  and  the  largest  negative 
value  is  also  returned. 

Ada  allows  you  to  define  your  own 
exceptions  by  declaring  their  names 
followed  by  ;  exception;.  To  invoke 
user-defined  exceptions,  use  the  raise 
keyword  followed  by  the  corre¬ 
sponding  exception  name.  Listing 
Two,  page  104,  gives  a  general 
scheme  for  defining  and  raising  ex¬ 
ceptions.  Notice  that  the  first  when 
clause  in  the  exception  handling 
block  uses  the  predefined  NUMERIC 
—ERROR  exception.  The  second  when 
clause  tackles  negative  absolute-tem¬ 
perature  values,  and  the  third  clause 
deals  with  both  negative  pressures 
and  volumes.  The  last  when  others 
clause  serves  as  an  otherwise  catchall 
error  trap.  The  listing  shows  how  the 
if  statement  is  used  in  raising  user- 
defined  exceptions.  Notice  how  this 
Ada  listing  handles  erroneous  values 
without  resorting  to  a  series  of  nested 
if  statements,  as  would  be  the  case 
with  Pascal  or  Modula-2. 

Ada  enables  you  to  use  several  ex¬ 
ception  handlers  and  control  their 
scope  of  action  and  so  allows  some 
exceptions  to  override  others.  Con¬ 
sider  Listing  Three,  page  104,  where 
procedure  The— Boss  defines  the 
Boss— Angry  exception  and  two  local 


procedures,  namely  Command 
— Worker  and  Command— Foreman. 
There  are  two  exception  handlers  for 
Boss^\ngry — the  first  is  located  in¬ 
side  procedure  Command— Foreman, 
the  other  at  the  end  of  the  main  pro¬ 
cedure.  When  the  main  procedure 
starts  executing,  it  first  calls  for  pro¬ 
cedure  Command— Worker.  If  the 
Boss— Angry  exception  is  raised  dur¬ 
ing  the  first  direct  call,  the  exception 
handler  in  the  main  procedure  is  in¬ 
voked.  Assuming,  on  the  other  hand, 
that  the  above  call  proceeds  smooth¬ 
ly,  the  main  procedure  resumes  nor¬ 
mally  and  invokes  procedure  Com¬ 
mand-Foreman.  The  latter  calls  for 
procedure  Command— Worker.  If 
during  this  process  the  Boss— Angry 
exception  is  raised,  the  local  handler 
is  used  instead  of  the  global  one. 

The  role  of  exception  handlers  falls 
into  the  following  categories: 

1.  Halt  program  execution. 

2.  Retry  the  program. 

3.  Employ  another  method  or 
approach. 

4.  Clean  up  variables  and  resume 
program  execution. 

Halting  the  program  after  displaying 
an  appropriate  error  message  is  the 
least  thing  a  program  should  do.  This 
course  of  action  uses  Ada’s  exception 
feature  to  a  minimum  because  no  at¬ 
tempt  is  made  to  remedy  the  error. 

The  second  approach  to  using  ex¬ 
ception  handlers  retries  a  routine  for 
a  fixed  number  of  times  to  prevent  it 
from  being  trapped  indefinitely. 
Thus,  the  program  simulates  a  time¬ 
out.  Listing  Four,  page  104,  shows  a 
simple  example  for  handling  errors 
associated  with  enumerated  types. 
The  procedure  defines  a  new  data 
type  for  the  weekdays  and  creates  a 
new  set  of  customized  I/O  routines. 
The  Time-Out  constant  is  defined 
and  set  equal  to  5,  and  a  user-defined 
Wrong— Day  exception  is  declared. 
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The  for  loop  contains  the  main  rou¬ 
tine  body.  The  first  statement  inside 
the  loop  prompts  the  user  to  enter  an 
abbreviated  day  name.  The  rest  of 
the  loop  contains  the  exception  han¬ 
dling  block,  starting  with  the  GET( ) 
procedure.  If  a  correct  day  name  is 
entered,  the  program  responds  with 
a  brief  greeting  message  and  exits 
from  the /or  loop.  By  contrast,  enter¬ 
ing  an  incorrect  day  name  causes  a 
constraint-type  error  and  triggers  the 
exception  handling  mechanism.  The 
user  is  given  a  chance  to  reenter  a 
correct  day  name  until  the  loop  times 
out.  Notice  that  one  when  clause  in 
the  exception  handler  deals  with 
constraint  errors.  The  user-defined 
Wrong— Day  exception  is  not  used  in 
any  when  clause.  Why  define  it  at  all? 
The  answer  is  that  it  is  raised  to  cause 
a  fatal  error  and  halt  the  program. 

The  third  approach  involves  using 
an  alternate  method  when  the  first 
one  is  plagued  by  an  error.  Listing 
Five,  page  104,  shows  a  realistic  appli¬ 
cation  for  finding  the  root  of  a  non¬ 
linear  function.  The  main  method  se¬ 
lected  employs  the  popular  and 
highly  efficient  Newton's  method. 
This  method  is  vulnerable  to  func¬ 
tions  that  have  maxima,  minima,  and 
saddle  points  (that  is,  where  the  slope 
is  zero)  near  the  root,  and  so  I  have 
used  the  bisection  method  (also 
known  as  the  interval-halving  meth¬ 
od)  as  an  alternate  method.  The  bisec¬ 
tion  method  is  slower  but  is  guaran¬ 
teed  to  get  a  solution  on  condition 
that  the  two  supplied  guesses  form 
an  interval  containing  the  root.  The 
listing  shows  the  use  of  two  nested 
exception  handlers.  The  first  tackles 
any  error  generated  by  Newton’s 
method.  This  can  be  a  numeric  error 
or  divergence  error  raised  by  the  test 
for  May— Iter.  If  an  error  occurs,  the 
program  resorts  to  the  bisection 
method.  If  this  technique  encounters 
any  problem  (such  as  an  overflow  be¬ 
cause  of  a  corrupt  function),  it  in¬ 
vokes  its  own  exception  handler  and 
triggers  the  Fatal— Error  exception. 
Because  there  is  no  handler  for  the 
latter  exception,  the  program  will 
then  halt. 

The  fourth  approach  to  exception 
handling  uses  a  cleanup  to  alter  the 
error-causing  values  of  one  or  more 


variables  and  then  resume  program 
execution.  I  have  modified  the  appli¬ 
cation  in  Listing  Five  to  demonstrate 
a  cleanup  operation;  the  modified 
code  is  shown  in  Listing  Six,  page  113. 

Modula-2  Exceptions 

Standard  Modula-2  does  not  have 
Ada-like  exceptions,  and  so  program¬ 
mers  must  set  up  their  own  error- 
trapping  schemes.  Several  standard 
Modula-2  libraries  defined  by  Niklaus 
Wirth  include  error-flagging  Boolean 
variables.  I  will  focus  on  the  Math- 
LibO  library,  which  provides  mathe¬ 


matical  functions  with  no  error  trap¬ 
ping.  Listing  Seven,  page  114,  shows 
the  definition  and  implementation 
modules  of  SafeLibO,  a  subset  library 
of  MathLibO.  This  version  offers  pro¬ 
tection  against  out-of-range  argu¬ 
ments  for  the  square  root,  exponen¬ 
tial,  and  natural  logarithm  functions. 

The  definition  module  SafeLibO  ex¬ 
ports  the  upper  limit  for  the  expo¬ 
nential  function.  The  exported  con¬ 
stant  can  be  increased  to  reflect 
higher  numeric  ranges  attained  by 
using  the  8087  chip  in  an  IBM  PC- 
based  Modula-2  implementation.  The 
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definition  module  also  declares  the 
heading  of  the  exported  functions. 
Notice  that  each  mathematical  func¬ 
tion  has  one  additional  argument 
comp  red  to  functions  in  the  stan¬ 
dard  MathLibO.  This  second  argu¬ 
ment  is  ArgumentERROR,  a  Boolean 
flag  to  signal  that  an  out-of-range  er¬ 
ror  has  occurred.  The  offending  val¬ 
ue  of  the  argument  is  made  valid,  al¬ 
though  the  returned  function  value 
in  the  case  of  argument  error  is 
meaningless.  I  wrote  the  SafeLibO 
module  to  track  argument  errors  in 
an  expression  containing  several 
mathematical  functions.  I  also  in¬ 
cluded  function  GetNegt  to  return  the 
next  error  systematically  by  using  an 
array  of  Boolean  error  flags. 

Suppose  I  want  to  execute  the  as¬ 
signment  statement  shown  in  Table 
1,  below.  Using  GetNegt  allows  my 
application  program  to  pinpoint  the 
particular  function  and  the  call  (for 
multiple  function  calls  in  an 
expression). 

An  alternative  method  does  away 
with  the  Boolean  out-of-range  argu¬ 


ments  and  instead  uses  an  error 
stack.  Listing  Eight,  page  115,  shows 
the  definition  and  implementation 
modules  for  SafeLibl.  This  version 
exports  a  record-typed  ErrorStack 
variable.  Its  structure  is  composed  of 
a  stack  height  counter  and  an  array 
of  function  names.  When  a  mathe¬ 
matical  function  receives  an  invalid 
argument,  it  pushes  its  name  into  the 
stack  and  increases  the  stack  height 
counter. 

To  use  this  library,  the  application 
program  must  issue  a  ClearError- 
Stack  before  every  assignment  that 
involves  the  mathematical  function 
in  question.  Following  the  assign¬ 
ment  statement,  the  library  function 
InErrorf )  will  indicate  if  the  function 
arguments  were  correct.  In  case  of  an 
error,  the  height  counter  returns  the 
number  of  functions  that  were  sup¬ 
plied  with  invalid  arguments.  The 
stack  contains  the  names  of  these 
functions.  The  only  drawback  of  this 
method  over  the  first  one  is  the  case 
of  multiple  calls  for  the  same  func¬ 
tion  in  an  expression.  The  problem 
with  this  method  is  that  the  occur¬ 
rence  of  the  offending  function  is  not 
apparent. 


Large  Turbo  Pascal  Arrays 

Turbo  Pascal  (Versions  1.0  through 
3.0)  imposes  a  64K  limit  on  the  data 
segment,  but  I  have  found  a  product 
that  enables  programmers  to  over¬ 
come  this  barrier.  Turbo  Extender  (a 
product  of  TurboPower  Software) 
supplies  the  user  with  several  inter¬ 
esting  alternatives  to  support  large 
matrices  of  any  type.  Each  method 
comes  with  its  own  include  file.  Just 
how  big  can  these  matrices  be?  The 
maximum  number  of  columns  and 
rows  is  32,767,  leading  to  matrices 
containing  one  billion  elements!  Tur¬ 
bo  Extender  uses  a  paging  technique 
that  maintains  part  of  the  matrix  in 
memory  and  stores  the  rest. 

The  memory  schemes  used  for 
large  matrices  are: 

1.  RAM-based — This  method  is  able  to 
fit  matrices  in  up  to  640K  of  standard 
memory.  The  application  program 
must  define  the  size  of  the  RAM-resi¬ 
dent  portion  of  the  big  matrix.  The 
large  matrix  is  made  up  of  a  matrix  of 
pages,  and  so  the  number  of  column 
and  row  pages  must  also  be  defined. 
This  type  of  matrix  is  defined  at  com¬ 
pile  time. 

2.  Disk-based  array — This  technique 
stores  the  matrix  in  a  data  file.  The 
application  program  must  specify 
the  same  parameters  as  in  the  RAM- 
based  version.  In  addition,  the  num¬ 
ber  of  pages  in  RAM  must  also  be  de¬ 
fined.  Disk-based  matrices  are 
defined  during  program  compila¬ 
tion.  This  alternative  applies  a  virtu¬ 
al-memory  method  for  swapping 
RAM  pages  that  have  been  unused  for 
the  longest  time.  The  RAM-resident 
pages'  sizes  and  the  number  of  mem¬ 
ory-resident  pages  determine  the 
speed  of  accessing  the  matrix. 

3.  Virtual  arrays — These  are  very 
similar  to  disk-based  arrays.  The  dif¬ 
ference  is  that  virtual  arrays  are  dy¬ 
namically  allocated  at  run  time. 

4.  Expanded-memory  arrays — These 
are  similar  to  virtual  arrays,  except 
they  reside  in  the  expanded-memory 
section.  The  page  size  is  automatical¬ 
ly  assigned  by  the  library.  The  appli¬ 
cation  program  needs  only  to  specify 
the  number  of  rows  and  columns. 

5.  Sparse  arrays — These  are  dynami¬ 
cally  allocated  as  a  linked  list.  Scan¬ 
ning  for  sparse  matrix  elements  is 
done  in  two  phases:  the  first  locates 
the  vicinity  of  the  sought  element; 


REPEAT 

Pressure  :=  SQRT(Temp,100.,ArgEr[1])  *  LN(Volume,22.4,ArgEr[2]) 

Current :  =  0; 

Current :  =  GetNext(Current,  2,  Found,  ArgEr) 

IF  Found  THEN 

(*  statement  to  trace  errors  and  either  adjust  values,  or  recalculate  tTemp  or  Volume*) 
END; 

UNTIL  NOT  Found; 


Table  1:  Using  GetNext  in  an  assignment  statement 

Square  Matrix  Size 

Inversion  Time 

(hh:mm:ss.ff) 

Comments 

10 

00:00:00.71 

Turbo  Pascal 

20 

00:00:05.16 

“  ” 

30 

00:00:17.30 

“  ” 

50 

00:01:19.42 

“  ” 

75 

00:04:26.61 

“  ” 

90 

00:07:40.33 

“ 

100 

overflow 

“  ” 

140 

01:16:33.47 

Turbo  Extender 

20 X  20-page  size, 

7  pages 

140 

01:16:32.32 

28 X  28-page  size, 

5  pages 

140 

01:16:33.75 

35X35- page  size, 

4  pages 

Table  2:  Matrix-inversion  benchmark  timings  using  the  8087  chip 
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the  second  pinpoints  it. 

To  use  a  large  matrix  of  any  data 
type,  the  application  program  must 
first  initialize  its  support.  The  ex- 
panded-memory  array  needs  a  sec¬ 
ond  initializing  procedure.  The  actu¬ 
al  matrices  that  are  accessed  by 
pointers  are  dynamically  created 
and  optionally  initialized  by  library 
procedures.  Other  procedures  and 
functions  are  available  to  store  and 
recall  matrix  elements  and  clear,  de¬ 
lete,  save,  load,  and  flush  virtual  ar¬ 
rays.  Error  handling  is  supported  via 
a  number  of  Boolean  flags  defined  in 
the  library. 

Listing  Nine,  page  116,  shows  a  Tur¬ 
bo  Pascal  program  that  carries  out  a 
matrix-inversion  benchmark  on  a 
matrix  of  140  rows  and  140  columns. 
Notice  the  initialization  and  matrix- 
creation  procedures.  In  addition,  you 
can  see  the  numerous  calls  for  the  li¬ 
brary  routines  to  store  and  recall  ma¬ 
trix  elements. 

Table  2,  page  124,  contains  the  tim¬ 
ing  results.  I  tried  three  different 
combinations  of  page  size  and  num¬ 
ber  of  pages  and  still  obtained  the 
same  timings.  The  table  also  shows 
the  timings  of  the  8087-support  Tur¬ 
bo  Pascal  version  for  smaller  matri¬ 
ces.  The  Turbo  Extender  manual  re¬ 
ports  a  threefold  decrease  in  speed 
access  for  REALS.  The  fact  that  big  ma¬ 
trices  can  be  employed  is  a  welcome 
feature. 
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Graphics 

Z3D  from  Computer 
Graphics  Center  is  a  new 
3-D  graphics  program  for 
the  Macintosh  computer. 
The  program  displays  shad¬ 
ows  cast  from  3-D  objects 
created  by  the  user  and 
shades  these  objects.  The 
program  has  12  fonts  avail¬ 
able,  which  can  also  be  dis¬ 
played  in  3-D.  Entire  scenes 
can  be  viewed  from  any  an¬ 
gle.  Z3D  is  priced  at  $99. 
Reader  Service  No.  16. 
Computer  Graphics  Center 
Inc. 

444  High  St. 

Palo  Alto,  CA  94301 
(415)  325-3111 

The  IB-3D1  3D  Graphics 
Package  from  SubLOGiC 
Corp.  contains  a  set  of  pro¬ 
grams  for  the  creation  and 
real-time  animation  of  3-D 
objects.  The  package  in¬ 
cludes  a  custom  high-speed 
assembler/linker,  a  VIEW 
program  to  view  and  ani¬ 
mate  3-D  databases,  and  the 
Real-Time  Animation  Lan¬ 
guage  (RTAL)  graphic  driv¬ 
ers  that  are  also  used  in  sev¬ 
eral  flight-simulator 
programs.  The  IB-3D1  3D 
Graphics  Package  is  avail¬ 
able  for  the  IBM  PC  and 
compatibles  and  costs  $995. 
Reader  Service  No.  17. 
SubLOGiC  Corp. 

713  Edgebrook  Dr. 
Champaign,  IL  61820 
(217)  359-8482 

MSI  Logic  has  begun  ship¬ 
ping  the  EVC  (Enhanced 
Video  Controller)-315,  an 
advanced  graphics  chip. 
The  EVC-315  integrates  five 
graphics  standards,  is  user 


programmable,  and  can 
operate  at  a  high  frequen¬ 
cy  to  achieve  high  resolu¬ 
tions.  The  chips  are  avail¬ 
able  to  OEMs,  and  the  prices 
begin  at  $65  per  chip  for  a 
minimum  order  of  10,000. 
Reader  Service  No.  18. 

NSI  Logic  Inc. 

Cedar  Hill  Business  Park 
247-B  Cedar  Hill  Rd. 
Marlboro,  MA  01752 
(617)  460-0717 

The  Inport  device  inter¬ 
face  from  Microsoft  Corp. 
is  for  hardware  manufac¬ 
turers  who  want  to  inte¬ 
grate  graphics  input  de¬ 
vices  into  their  products. 
The  interface  scheme  in¬ 
cludes  a  new,  40-pin,  cus¬ 
tom  integrated  circuit  and 
a  small,  compact  9-pin  con¬ 
nector.  Together  the  chip 
and  connector  reduce  the 
amount  of  circuit-board 
and  end-bracket  space  re¬ 
quired  to  provide  a  graph¬ 
ics  input  device  for  person¬ 
al  computers.  Reader 
Service  No.  19. 

Microsoft  Corp. 

16011  N.E.  36th  Wy. 

P.O.  Box  97017 
Redmond,  WA  98073-9717 
(206)  882-8080 

Definicon  Systems  has 
announced  MMM,  a  32-bit 
graphics  board  line  for  IBM 
PC-compatible  personal 
computers.  MMM  combines 
a  million  bytes  of  on-line 
memory,  a  million  pixels 
on  the  screen,  and  a  mil¬ 
lion  instructions  per  sec¬ 
ond.  The  three-board  prod¬ 
uct  line  comprises  two 
computing  engines,  DSI-020 
and  DSI-780,  which  are 
based  on  Motorola’s  68020 
CPU  and  68881  FPU,  as  well 
as  a  graphics  processor 
based  on  Hitachi’s  63484 
chip.  DSI-020  (16  MHz)  costs 
$1,994,  DSI-780  (16  MHz) 
costs  $3,295,  the  graphics 
expander  board  costs 


$1,495,  and  the  256-color 
option  for  the  graphics 
board  costs  $400.  Reader 
Service  No.  20. 

Definicon  Systems 
31324  Via  Colinas,  Ste.  108 
Westlake  Village,  CA  91362 
(818)  889-1646 

A  new  line  of  single-slot, 
IBM  PC-compatible,  add-in 
graphics  boards  are  avail¬ 
able  from  Pronto  Com¬ 
puters.  The  HR-1200  Series 
of  color  graphics  boards 
provide  flicker-free  graph¬ 
ics  on  60-Hz  noninterlaced 
monitors  at  1,280  X  1,024 
pixels  with  either  8-bit,  256- 
color  display  or  4-bit,  16-col- 
or  display  from  a  palette  of 
4,096  colors.  The  boards 
also  include  a  256  X  12  col¬ 
or  lookup  table,  three  high¬ 
speed  digital/analog  con¬ 
verters,  and  1.5-megabyte 
memory  per  screen  image. 
The  1,280  X  1,024-pixel  ver¬ 
sion  with  256  simultaneous 
color  display  capability  is 
priced  at  $3,495;  the 
1,280  X  1,024-pixel  board 
with  16-color  capability  is 
$2,795;  the  1,024  X  768-pix- 
el  board  with  256-color  ca¬ 
pability  is  $2,895;  and  the 
1,024  X  768-pixel  board 
with  16-color  capability  is 
$2,195.  Reader  Service  No. 
21. 

Pronto  Computers  Inc. 

3730  Skypark  Dr. 

Torrance,  CA  90505 
(213)  539-6400 

Languages 

QuickBASIC  2.0  from  Mi¬ 
crosoft  Corp.  is  a  high- 
performance  BASIC  compil¬ 
er  that  offers  high-speed, 
in-memory  compilation 
and  allows  users  to  create 
structured  and  modular 
programs.  In  addition,  its 
built-in  editor  and  debug¬ 
ger  shorten  development 
time,  letting  programmers 
write,  compile,  and  debug 
their  programs  without 


having  to  leave  the  pro¬ 
gramming  environment. 
QuickBASIC  2.0  runs  on  the 
IBM  PC  and  compatibles 
and  costs  $99.  Reader  Ser¬ 
vice  No.  22. 

Microsoft  Corp. 

16011  N.E.  36th  Wy. 

P.O.  Box  97017 
Redmond,  WA  98073-971 7 
(206)  882-8080 

CniPress  Software  has 
announced  UniShell,  a 
Bourne  shell  script  compil¬ 
er.  UniShell  analyzes  a 
shell  script,  translates  it 
into  the  C  language,  com¬ 
piles  it  using  the  system  C 
compiler,  and  then  pro¬ 
duces  an  executable  pro¬ 
gram.  UniShell  programs 
run  faster  than  shell 
scripts,  can  take  advantage 
of  the  sticky  bit  and  setuid 
for  increased  efficiency 
and  security,  are  portable, 
and  have  well-structured 
and  readable  C  code.  Prices 
vary  according  to  comput¬ 
er  system.  Source  code  is 
available  for  $4,995.  Reader 
Service  No.  23. 

UniPress  Software 
2025  Lincoln  Hwy. 

Edison,  NJ  08817 
(201)  985-8000 

A  Modula-2  language  sys¬ 
tem  is  now  available  from 
Djavaheri  Bros.  This  Mo¬ 
dula-2  runs  on  the 
MC68020  processor-based 
Unix  system  Altos  3068 
Computer  System.  The 
price  for  the  product  is 
$495.  Reader  Service  No.  24. 
Djavaheri  Bros. 

697  Saturn  Ct. 

Foster  City,  CA  94404 
(415)  341-1768 

Allen  Systems’  CP-97  Pas¬ 
cal  Cross  Compiler  for  the 
8097  16-bit  microcontroller 
on  a  chip  is  a  complete  pro¬ 
gramming  environment 
oriented  around  a  subset  of 
the  Pascal  programming 
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language.  The  CP  (Control 
Pascal)  system  is  designed 
to  run  on  IBM  PCs  and  com¬ 
patibles  and  includes  a 
screen  editor,  cross  compil¬ 
er,  interpreter,  translator, 
terminal  driver,  and  run¬ 
time  support  software.  CP- 
97  costs  $200.  Reader  Ser¬ 
vice  No.  25. 

Allen  Systems 
2151  Fairfax  Rd. 

Columbus,  OH  43221 
(614)  488-7122 

The  cEnglish  Data  Base  In¬ 
terface  Library  from  cLine 
has  more  than  200  func¬ 
tions  that  provide  easy  ac¬ 
cess  to  the  capabilities  of 
the  industry-standard  file 
management  system  C- 
ISAM.  This  library  allows  C 
applications  to  be  moved 
easily  between  MS-DOS, 
Xenix,  and  Unix  with  100 
percent  portability  across  a 
wide  range  of  systems.  The 
function  library  includes  a 
broad  inventory  of  tools 
for  screen  and  memory 
management,  database  in¬ 
terfacing,  formatting,  and 
utilities.  The  C  functions 
are  accessed  by  using  an 
English-like  preprocessor 
that  creates  Lattice  C-com- 
patible  source  code.  Read¬ 
er  Service  No.  26. 
cLine 

3550  Camino  del  Rio  North 
Ste.  208 

San  Diego,  CA  92108 
(619)  281-5593 

Cobalt  Blue  has  an¬ 
nounced  the  release  of  RTC, 
a  Ratfor-to-C  translator,  in 
both  PC-DOS  and  VAX-VMS 
formats.  RTC  is  priced  at 
$450  for  PC-DOS  and  $1,950 
for  VAX-VMS.  Reader  Ser¬ 
vice  No.  27. 

Cobalt  Blue 
1683  Milroy,  Ste.  101 
San  Jose,  CA  95124 
(408)  723-0474 

Intelligence  Ware’s  Intelli¬ 


gence/Compiler  is  an  ex- 
pert-system  development 
environment  and  knowl¬ 
edge  compiler  that  pro¬ 
vides  advanced  symbolic 
computing  technology  on 
business  and  industrial 
computer  systems.  The  In¬ 
telligence/Compiler  pro¬ 
duces  code  that  allows  ex¬ 
pert  systems  to  be 
interfaced  to  conventional 
languages,  applications, 
and  external  databases  or 
used  on  portable  comput¬ 
ers.  Reader  Service  No.  28. 
IntelligenceWare  Inc. 

9800  S.  Sepulveda  Blvd. 

Ste.  730 

Los  Angeles,  CA  90045 
(213)  417-8896 

For  the  IBM  PC 

International  Battery 
Corp.  (IBC)  is  now  market¬ 
ing  lithium  replacement 
batteries  for  the  IBM  PC/AT. 
The  AT's  internal  real-time 
clock  is  maintained  by  an 
independent  battery  locat¬ 
ed  on  the  motherboard 
when  the  power  is 
switched  off.  When  this 
battery  fails,  the  format¬ 
ting  memory  of  the  com¬ 
puter  shuts  down,  requir¬ 
ing  total  reconfiguration  of 
the  hardware.  The  re¬ 
placement  batteries  cost 
$27.50  each.  Reader  Service 
No.  31. 

International  Battery  Corp. 
6860  Canby  Ave.,  Ste.  113 
Reseda,  CA  91335 
(818)  609-0516 

The  Bubbl-Tec  division 
of  PC/M  has  announced  the 
PC-1  Bubbl-Board,  a  mag¬ 
netic-bubble,  mass-storage 
system  for  the  IBM  PC,  PC/ 
XT,  and  PC/AT.  The  PC-1 
provides  V2  megabyte  of 
magnetic-bubble  memory 
on  a  single  PC  adapter  card. 
The  system  also  provides 
512K  of  nonvolatile  mass 
storage  and  incorporates 
intelligent  control  firm¬ 
ware  and  circuitry  that 
handles  bubble-device  for¬ 
matting  and  control,  inter¬ 


faces  the  bubble-memory 
system  to  the  PC's  bus 
structure,  and  provides  for 
both  soft-  and  hard-error 
detection  and  correction. 
The  512K  version  of  the  PC- 
1  system  is  priced  at  $1,111. 
Reader  Service  No.  32. 
Bubbl-Tec 
6805  Sierra  Ct. 

Dublin,  CA  94568 
(415)  829-8700 

Sysgen  has  introduced  an 
internal  Winchester  sub¬ 
system  featuring  remov¬ 
able  hard-disk  cartridges 
for  the  IBM  PC,  PC/XT,  PC/ 
AT,  and  compatibles.  Dura- 
Pak  provides  PC  users  with 
the  transportability,  securi¬ 
ty,  and  unlimited  capacity 
characteristic  of  removable 
media.  The  system  is  inter¬ 
nal,  leaving  no  footprint. 
The  single-drive,  15-mega- 
byte  DuraPak  system  is 
priced  at  $1,295,  and  the  30- 
megabyte,  dual-drive  Dura¬ 
Pak  is  priced  at  $2,095. 
Reader  Service  No.  33. 
Sysgen  Inc. 

47853  Warm  Springs  Blvd. 
Fremont,  CA  94539 
(415)  490-6770 

A  new  plug-in  board  for  the 
IBM  PC  and  compatibles,  Mi¬ 
crosoft  Corp.'s  MACH  10  is 
designed  to  improve  the 
PC’s  ability  to  run  the 
graphical  user  interface 
and  multitasking  features 
of  Microsoft  Windows.  The 
board  replaces  the  8088 
processor  chip  with  a  16-bit 
8086  that  runs  at  nearly  10 
MHz  and  uses  high-speed 
cache  memory  to  act  as  a 
buffer  between  the  proces¬ 
sor  and  the  computer's 
main  memory.  MACH  10,  in¬ 
cluding  the  InPort  Mouse 
and  Windows,  has  a  sug¬ 
gested  retail  price  of  $549. 
Reader  Service  No.  34. 
Microsoft  Corp. 

16011  N.E.  36th  Wy. 

P.O.  Box  97017 
Redmond,  WA  98073-9717 
(206)  882-8080 


For  the  Atari  ST 

Abacus  Software  has  an¬ 
nounced  Introduction  to 
MIDI  Programming  for  the 
Atari  ST  by  Len  Dorfman 
and  Dennis  Young.  The 
book  includes  the  source 
listings  for  a  comprehen¬ 
sive  MIDI  editor,  driver, 
and  animated  player  for 
any  of  the  Casio  CZ  series 
synthesizers.  The  source 
can  be  modified  for  other 
makes  and  models.  The 
price  of  the  book  is  $19.95. 
Reader  Service  No.  29. 
Abacus  Software 
2201  Kalamazoo  SE 
P.O.  Box  7211 
Grand  Rapids,  MI  49510 

(616)  241-5510 

Mark  Williams  Co.  has  be¬ 
gun  shipping  Mark  Wil¬ 
liams  C  for  the  Atari  ST.  It 
features  a  complete  imple¬ 
mentation  of  K  &  R  C  plus 
the  recent  extensions  to  C 
implemented  under  Unix. 
It  includes  a  shell,  utilities, 
and  a  full-screen  editor  and 
costs  $179.95.  Reader  Ser¬ 
vice  No.  30. 

Mark  Williams  Co. 

1430  W.  Wrightwood  Ave. 
Chicago,  IL  60614 
(312)  472-6659 

Networking 

A  Hayes-compatible  2,400- 
baud  modem,  one  of  the  L 
series,  is  available  from 
Leading  Edge  Hardware 
Products.  The  modem  is 
priced  at  $289.  Reader  Ser¬ 
vice  No.  35. 

Leading  Edge  Hardware 
Products  Inc. 

225  Turnpike  St. 

Canton,  MA  02021 

(617)  828-8150 

A  linking  program  from 
EKD  Computer  Sales  and 
Supplies  Corp,  pcAny- 
where  can  support  up  to 
19,200  baud,  offers  conver¬ 
sational  and  copilot  mode, 
can  transfer  files  bidirec¬ 
tionally,  and  can  be  used 
with  28  popular  terminals 
with  customization  for 
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other  terminal  types  avail¬ 
able.  It  is  priced  at  $95  for 
each  host  machine.  The  re¬ 
mote  computer  program 
ATERM  can  be  copied  as 
many  times  as  required. 
Reader  Service  No.  36. 

EKD  Computer  Sales  and 
Supplies  Corp. 

764  Middle  Country  Rd. 
Selden,  NY  11784 
(516)  736-0500 

PCC/Systems  has  intro¬ 
duced  cc:Mail,  a  high-end 
electronic-mail  product. 
Cc:Mail  has  a  file-server- to- 
file-server  message  ex¬ 
change  that  can  be  used  on 
individual  networks  and 
between  networks  that  are 
bridged  together.  All  users 
of  local-area  networks  can 
exchange  text,  graphics, 
and  files  with  any  other  PC 
user  who  is  either  within 


or  outside  the  network. 
Cc:Mail  for  LANs  sells  for 
$995  for  a  ten-user  starter 
package  and  is  available 
for  a  variety  of  networks. 
Reader  Service  No.  37. 
PCC/Systems 

480  California  Ave.,  Ste.  201 
Palo  Alto,  CA  94306 
(415)  321-0430 

Miscellaneous 

Motorola's  Microprocessor 
Products  Group  has  an¬ 
nounced  the  25-MHz  (40- 
nanosecond)  version  of  the 
MC68020  32-bit  micropro¬ 
cessor  and  the  20-MHz  (50- 
nanosecond)  version  of  the 
MC68881  Floating  Point  Co¬ 
processor.  Prices  vary  ac¬ 
cording  to  quantity  and 
speed.  Reader  Service  No. 
38. 

Motorola  Inc. 
Microprocessor  Products 
Group 

P.O.  Box  3600 
Austin,  TX  78764 


(512)  928-6000 

The  Disk  Defender  from 
Director  Technologies  is 
a  hardware  write-protect 
device  for  fixed  Winches¬ 
ter  disks.  The  product  con¬ 
sists  of  a  circuit  board,  a 
control  box,  and  a  ribbon 
cable.  The  circuit  board 
can  be  installed  in  either 
the  short  or  long  slot  of  the 
IBM  PC,  PC/XT,  and  compati¬ 
ble  computers.  Using  full 
protection,  the  entire  hard 
disk  is  readable  but  not 
writable.  The  suggested  re¬ 
tail  price  is  $185.  Reader 
Service  No.  39. 

Director  Technologies  Inc. 
P.O.  Box  7067 
Evanston,  IL  60204 
(312)  475-3070 

Burton  Systems  Soft¬ 
ware  is  now  shipping  TUB, 
a  source-code-revision  con¬ 
trol  system  and  librarian 
for  PC-DOS  and  MS-DOS  com¬ 


puters.  TLIB  works  with 
LANs  and  handles  synchro¬ 
nized  control  of  multiple, 
related  source  files.  A  copy 
of  Landon  Dyer's  MAKE  util¬ 
ity  is  also  included.  TLIB  is 
not  copy-protected  and  is 
available  for  $99.95.  Reader 
Service  No.  40. 

Burton  Systems  Software 
P.O.  Box  4156 
Cary,  NC  27511-4156 
(919)  469-3068 

Phoenix  Technologies' 

PC /AT -compatible 
ROM  BIOS  for  Intel’s  80386  is 
now  available.  The  Phoe¬ 
nix  BIOS  includes  such  fea¬ 
tures  as  extended  central 
processor  diagnostics,  full 
32-bit  memory  testing,  sup¬ 
port  for  the  80387  numeric 
coprocessor,  and  support 
for  processing  speeds  up  to 
20  MHz.  Reader  Service  No. 
41. 

Phoenix  Technologies  Ltd. 
320  Norwood  Park  S 
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Norwood,  MA  02062 
(617)  769-7020 

Software  Composers  has 
announced  Delta  Board,  a 
4>/2  X  6V2-inch  circuit 
board  built  around  the  No- 
vix  NC4000  single-chip 
Forth  engine.  The  board 
provides  essentials  for  im¬ 
mediate  application  use: 
stack  memory,  program 
RAM,  and  EPROM  with  a 
public-domain  Forth  inter¬ 
preter.  Delta  Board  costs 
$795.  Reader  Service  No.  42. 
Software  Composers 
210  California  Ave.,  Ste.  F 
Palo  Alto,  CA  94306 
(415)  322-8763 

The  STD  bus-based  system 
from  Devtek  Systems  sup¬ 
ports  program  develop¬ 
ment  for  8085,  Z80,  8086, 
and  8088  CPUs.  An  IBM  PC  or 


compatible  is  used  as  the 
system  console  and  for 
program  storage.  Pro¬ 
grams  are  downloaded  to 
the  STD  system  where  a  full 
complement  of  debugging 
utilities  can  be  operated 
from  the  PC.  The  price  is 
$695.  Reader  Service  No.  43. 
Devtek  Systems 
P.O.  Box  5224 
Lancaster,  PA  17601 
(717)  560-0652 

Viasyn  Corp.  is  now  ship¬ 
ping  the  CompuPro  286/80, 
a  multiuser  computer.  The 
CompuPro  286/80  includes 
an  80-megabyte  hard  disk 
with  a  dedicated  512K 
cache  buffer,  a  16-slot  S- 
100R  motherboard,  a  bpilt- 
in  tape  backup  unit,  800K 
floppy-disk  drive,  768K  of 
main  memory,  and  an  8- 
MHz  80286  central  proces¬ 
sor.  The  computer  has  a 
suggested  list  price  of 
$12,500.  Reader  Service  No. 


44. 

Viasyn  Corp. 

26538  Danti  Ct. 

Hayward,  CA  94545-3999 
(415)  786-0909 

PCMK  from  G.  W.  Glass¬ 
cock  brings  MS-DOS  pro¬ 
grammers  the  power  of 
the  Unix  make  command. 
Using  information  stored 
in  the  make  file  and  built- 
in  knowledge,  PCMK  can 
automatically  construct  a 
program.  Features  provid¬ 
ed  by  the  program  are 
wildcard  character  expan¬ 
sion,  full  path-name  sup¬ 
port,  user-defined  macros, 
access  to  DOS  environment 
via  macros,  access  to  inter¬ 
nally  generated  macros, 
built-in  rules  defined  by  us¬ 
ers,  and  direct  execution  of 
commands  using  the  envi¬ 
ronment  Path  variable. 
The  price  is  $21.  Reader 
Service  No.  45. 

G.  W.  Glasscock 


15617  S.E.  Fairwood  Blvd. 
Renton,  WA  98058 
(206)  271-0638 

Premier  Technologies 

has  announced  LiteDrive,  a 
portable  internal  hard-disk 
system  to  enhance  the  Ze¬ 
nith  Data  Systems’  Z-171 
laptop  computer.  The  sys¬ 
tem  adds  27  times  the  origi¬ 
nal  disk  capacity  at  up  to  20 
times  the  access  speed.  The 
10-megabyte  system  is  in¬ 
stalled  in  place  of  the  sec¬ 
ond  floppy  and  runs  on 
both  battery  and  AC  power. 
Reader  Service  No.  46. 
Premier  Technologies  Inc. 
1890  McGraw  Ave. 

P.O.  Box  16279 
Irvine,  CA  92714 
(714)  261-1184 
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Speaking  of  languages  that  you 
don’t  speak  of,  have  you  pro¬ 
grammed  in  BASIC  lately?  BASIC,  as  ev¬ 
eryone  knows,  is  not  an  appropriate 
language  for  serious  software  devel¬ 
opment,  having  been  expressly  cre¬ 
ated  for  teaching  beginning  pro¬ 
grammers  to  program  badly.  BASIC  is 
slow.  BASIC:  encourages  bad  program¬ 
ming  practices.  BASIC  is  limited  to  64K 
RAM  for  data.  BASIC  does  not  provide 
a  set  of  development  tools.  Conse¬ 
quently  ODJ,  although  founded  to  put 
BASIC  in  the  hands  of  programmers 
in  1976,  has  not  wasted  space  on  BA¬ 
SIC  recently. 

Now  there  are  those  who  argue, 
for  their  own  mercenary  purposes 
no  doubt,  that  BASIC  is  becoming  a  se¬ 
rious  development  language.  They 
point  to  the  impressive  compiled- 
code  speed  measures  turned  in  by 
the  latest  implementations.  But 
should  we  pay  any  attention  to  Hal 
Hardenbergh’s  claim  that  he  has 
benchmarked  his  own  HBASIC  (nee 
Halgol)  for  the  Atari  ST  at  speeds 
more  comparable  to  C  code  than  to  ST 
BASIC  code? 

They  say  that  the  control  structures 
of  BASIC  have  evolved  to  the  point  that 
the  language  actually  encourages 
structured  style,  that  case  statements 
and  multiline  if-then-else  structures 
kill  the  taste  for  spaghetti  code,  that 
with  True  BASIC  and  QuickBASIC  the 
language  is  even  getting  away  from 
line  numbers.  They  argue  that  BASIC 
functions  and  subroutines  are  becom¬ 
ing  more  effective  tools  for  modular¬ 
izing  code,  with  more  flexible  param¬ 
eter-passing  techniques  and  the 
possibility  of  defining  subroutines  to 
be  external  or  internal.  They  talk 
about  how  the  new  versions  of  BASIC 
offer  significant  support  for  function 
libraries;  how  QuickBASIC  supports 
separately  compiled  modules  without 
a  linking  step;  and  how  Mach  2,  a  col¬ 


lection  of  utilities  from  Microhelp  in 
Marietta,  Georgia,  embodies  a  new 
method  for  incorporating  assembly- 
language  routines  into  interpreted  BA¬ 
SIC  programs. 

I  think  these  must  be  the  same  peo¬ 
ple  who  point  out  that  the  64K  mem¬ 
ory  limitation  that  has  kept  BASIC  in 
the  toy  category  for  years  has  been 
eliminated  in  the  modern  BASICS  and 
in  products  such  as  Mach  2. 

But  they  really  show  their  igno¬ 
rance  when  they  point  out  the  ease 
of  use  of  the  new  BASICs;  how  they 
blend  characteristics  of  a  compiler 
and  an  interpreter;  and  how  the  pro¬ 
gramming  environment  provided  ; 
with,  say,  QuickBASIC  is  a  dream. 
Don’t  they  know  that  serious  pro¬ 
gramming  languages  should  not  be 
easy  to  use?  And  then  they  argue  that 
it's  time  to  take  a  fresh  look  at  BASIC. 

Who  do  these  people  think  they're 
talking  to?  If  BASIC  had  become  a  seri¬ 
ous  programming  language,  don’t 
they  think  you’d  already  know  about 
it?  Why  you'd  have  been  reading  arti¬ 
cles  about  it  in. . . . 

Last  month  I  wrote  about  Stan  Kel- 
ly-Bootle’s  yacc  (yet  another  com¬ 
ment  compiler),  which  ignores  the 
code  and  compiles  the  comments. 
My  cousin  Corbett  tells  me  that  he 
was  reminded  of  SK-B’s  yacc  this 
week  as  he  read  something  Niklaus 
Wirth  said:  "Die  Grundidee  hinter 
Pascal,  wie  auch  schon  bei  ALGOL,  war, 
dass  man  Strukturen  einfuhrt,  damit 


die  Sat ze  der  Sprache  sich  spiiter  so 
pr'Asentieren,  dass  man  beim  l^esen 
die  Struktur  des  Programms  erkennen 
kann."  (PC  Magazin,  vol  21,  no.  22, 
May  1986.) 

Which  in  real  language,  Corbett  j 
tells  me,  means  something  like:  "The 
idea  behind  Pascal  and  ALGOL  was  to 
invent  structures  that  would  allow 
you  to  program  by  writing  English 
sentences  that  implement  the  pro¬ 
gram  logic.’’  The  goal  seems  eminent¬ 
ly  right;  it’s  probably  what  the  de¬ 
signer  of  COBOL  would  say  she  had  in 
mind.  Corbett  maintains  that  it  is  ob¬ 
vious  that  neither  of  them  did  it  right. 
He  restates  the  goal  this  way:  In  con¬ 
structing  the  syntax  of  a  program¬ 
ming  language,  how  close  can  we  get 
to  the  ideal  of  making  the  efficient 
implementation  of  the  program  in 
the  language  and  the  clear  statement 
of  the  algorithm  in  English  identical? 

Corbett  is  now  engaged  in  a  massive 
comment  compilation  project  not 
connected  with  Stan  Kelly-Bootle’s 
;  scheme.  He  argues  that  if  we  knew 
just  how  programmers  wanted  to  ex¬ 
press  their  algorithms  in  English,  we 
would  have  a  model  for  the  syntax  of 
the  ideal  programming  language,  the 
one  that  makes  the  English  descrip-  ! 
lion  and  the  code  identical.  But  the 
kinds  of  sentences  we  want  to  write 
describing  the  logic  of  programs,  he 
claims,  are  just  the  ones  we  are  al¬ 
ready  writing — called  comments — 
only  spelled  better.  Corljett  plans  to 
do  a  linguistic  analysis  of  program¬ 
mers’  comments — along  the  lines  of 
the  textual  analyses  used  to  establish 
authorship  of  manuscripts — to  deter¬ 
mine  the  kinds  of  language  constructs 
we  really  need  in  the  perfect  pro¬ 
gramming  language. 


Michael  Swaine 
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A  multitasking  ► 
kernel 


OPERATING  SYSTEMS:  A  Multitasking  kernel 

by  Ken  berry 

Ken  presents  a  task  scheduler  that  participates  in  every 
task  but  is  almost  always  invisible.  The  kernel  lets  you 
simulate  multitasking  features  of  the  80286  and  80386  on 
processors  such  as  the  8086  and  8088.  Ken  s  operating 
system,  called  Tele,  implements  a  task  scheduler  so  that  it 
presents  the  same  environment  on  v  arious  processors 
ALGORITHMS:  In  Search  oi  a  Sine 
bv  Richard  A.  Campbell 

An  algorithm  for  computing  mathematical  functions  based 
on  a  polynomial  approximation  of  a  Taylor  series  formula. 
The  algorithm  is  executed  in  both  BASIC  and  NS320xx 
assembly  language. 

OPERATING  SYSTEMS:  Echelon’s  Z-System 

by  Morris  Simon 

The  modular  design  of  this  8-hit  system's  command 
processor  gives  it  unusual  speed  and  efficiency. 

PROCESSORS:  Scries  32000  Cross  Assembler 

by  Richard  Rodman 

A  table-driven  assembler  that  can  he  modified  for  other 
processors 
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About  llifi  Cover 

A  multitasking  operating  system 
is  simultaneously  bandleader 
and  musician,  and  its  results 
must  be  harmonious. 


This  Issue 

With  the  advent  of  Intel’s  80386 
microprocessor,  true  multitask¬ 
ing  is  clearly  visible  on  the  DOS 
horizon,  but  the  road  to  take  us 
there  a  multitasking  operating 
system  is  still  l>eing  surveyed. 
Our  feature  article  leads  the  way 
by  showing  how  to  build  a  task¬ 
scheduling  kernel  the  bedrock 
on  which  a  multitasking  operat¬ 
ing  system  is  constructed. 


String 

comparisons 


16-BIT  SOFTWARE  TOOLBOX 

by  Ray  Duncan 

Ray's  readers  discuss  file  handles,  file-name  wildcards,  and 
Concurrent  Dos.  Rav  presents  8086-  and  68000-based  string 
comparison  routines  and  recommends  a  book  for  the 
80286. 

STRUCTUB  ED  PHOGRA MM  I NG 

by  Namir  Clement  Shammas 

Narnir  shows  how  to  implement  procedural  parameters  in 
Turbo  Pascal  and  dm-  Modula-2's  local  modules  to  take 
advantage  of  static  variables.  He  also  explains  two  methods 
of  modifying  menus  within  an  application  program 
without  altering  the  application  itself 


Turbo  Pascal  ^ 
and  Modula-2 


Ncxl  Issue 

We  ll  Begin  tile  new  year  with  a 
look  at  the  present  and  future  of 
the  Motorola  68000  line  of  pro¬ 
cessors  How  are  the  chips  being 
used  now,  and  what  will  the 
new  members  of  the  family  lie 
like?  What  will  the  68030  lor  ru¬ 
mored  680461  add  in  terms  of 
speed  and  memory? 
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It's  two-thousand- 
odd  miles  from  the 
East  Coast  of  the  Unit¬ 
ed  States  to  the  West. 

t  know  exactly  in 
what  year  1  learned 
this  rough  and  homely 
statistic  because  is 
linked  in  my  memory 
with  a  disturbing 
childhood  insight  into 
the  nature  of  subjec¬ 
tive  time. 

Halfway  through  the  sixth  grade,  1 
realized  that  1  had  forgotten  the  fifth 
grade.  Thinking  back,  1  couldn't  de¬ 
cide  whether  important  events  had 
occurred  in  the  fourth  grade  or  in  the 
fifth  or  even  in  the  early  part  of  the 
sixth.  Until  then,  each  school  year 
had  seemed  as  distinct  as  a  life  unto 
itself,  and  summers  were  not  vaca¬ 
tions  but  a  succession  of  heavens.  But 
that  winter  the  days  and  weeks  be¬ 
gan  to  slide  into  one  another  like  seg¬ 
ments  of  a  telescope,  and  the  only 
event  in  my  life  that  I  could  with  any 
certainty  assign  to  my  otherwise  van¬ 
ished  fifth-grade  year  was  reading 
that  it  was  two-thousand-odd  miles 
from  the  East  Coast  of  the  United 
States  to  the  West. 

By  the  early  1980s,  decades  were 
telescoping.  While  researching  a 
book  on  what  1  thought  was  the  first 
decade  of  the  personal  computer,  1 
rediscovered  an  article  written  in  the 
late  1970s  by  Sot  Libes  (rhymes  with 
Phoebus)  on  the  first  decade  of  hobby 
computing.  Sol  referred  to  that  arti¬ 
cle  in  an  early  issue  of  his  magazine, 
S-i00  Microsystems,  in  1980.  I  read  S- 
100  Microsystems  scrupulously  back 
then  because  I  was  working  on  S-100 
systems  and  I  enjoyed  Sol  s  News  and 
Views  column.  You’ll  find  some  of 
Sol's  thoughts  from  that  period  in  mi¬ 
crocomputing  history  in  our  Ar¬ 
chives  section  on  page  8  tin  case 
you're  nostalgic  for  them,  too). 

Well,  it  was  entertaining  to  read 
about  the  S-100  bus  in  1980.  The  IEEE 
had  just  decided  to  establish  a  stan¬ 


dard  for  the  bus  in¬ 
vented  by  Ed  Roberts 
and  MITS  and  seized 
upon  by  early  micro¬ 
computer  hobbyists 
and  entrepreneurs. 
After  Roberts  de¬ 
nounced  the  other  en¬ 
trepreneurs  as  "para¬ 
sites,"  entrepreneur 
Howard  Fullmer  re¬ 
named  his  company 
Parasitic  Engineering,  and  the  IEEE 
made  Fullmer  cochairman  of  the  S- 
100  bus  standard  subcommittee.  So, 
there  were  some  differences  of 
opinion. 

lime  continued  to  telescope,  and 
within  a  few  years  the  IEEE  had 
adopted  the  S-100  bus  standard  and 
Sol's  magazine  had  been  purchased 
and  promoted  and  put  to  death  by  a 
major  publisher.  Time  had  tele¬ 
scoped  me  into  this  job,  and  I  wrote  a 
brief  epitaph  for  Microsystems. 

Sol  ignored  all  epitaphs  and  in  the 
spring  of  1985  began  anew  with  Mi¬ 
cro/Systems  Journal,  featuring  most 
of  the  familiar  contributors.  There 
were  changes  that  reflected  changed 
realities,  but  it  still  had  the  quality 
one  expected  from  Sol  Libes. 

Ahem. 

This  fall,  M&T  Publishing  acquired 
Micro/Svstems  Journal.  Micro/Svs- 
tems  Journal  has  joined  the  group  of 
M&T  publications  that  includes  Dr. 
Dobb's  Journal  of  Software  Tools, 
Turbo  Tech  Report,  and  Business  Soft¬ 
ware  Magazine.  Sol  will  remain  edi¬ 
tor  and  will  remain  in  New  Jersey, 
and  he  and  I  will  consult  with  one 
another. 

I'm  looking  forward  to  working 
with  one  of  the  legends  of  the  indus¬ 
try.  Of  course,  it's  two-thousand-odd 
miles  from  the  East  Coast  of  the  Unit¬ 
ed  States  to  the  West.  But  we  hope  to 
telescope  that  distance. 

Michael  Swain e 
editor-in-chief 
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Our  latest  issue  of 
the  listings  on 
disk  is  out  now.  On  it 
you'll  find  an  eclectic 
collection  of  files,  from 
Jan  Steinman  s  Worm 
Memory  Test  for  the 
68000  to  Richard  Rod- 
man's  32000  assembler 
(in  this  issue).  You'll 
find  Mclvor  s  Radix 
Sort;  Ashdown's  Cubic 
Splines  program;  the  benchmarks 
used  in  the  Elkins/King  turbo  board 
review;  a  whole  bunch  of  stuff  from 
Holub's  and  Duncan's  columns;  and  a 
couple  of  interesting  Macintosh  pro¬ 
grams,  including  the  Digital  Dissolve 
demo  by  Mike  Morton  and  Howard 
Katz's  Mandelbrot  program.  See  the 
DID  ad  catalog  for  more  information. 

This  month's  theme  is  operating 
Systems,  and  we  have  a  couple  of  in¬ 
teresting  offerings.  The  lead  article 


focuses  on  a  task 
scheduling  routine, 
the  central  kernel  of 
any  multitasking  sys¬ 
tem. 

Echelon's  ZCPR  is  a 
Z80  CP/M  work-alike 
that  is  not  only  more 
powerful  than  the 
original  CP/M  but  also 
is  more  interesting:  the 
code  is  tighter  and 
takes  good  advantage  of  the  Z80  in¬ 
struction  set.  In  this  issue,  Morris  Si¬ 
mon  takes  a  look  at  ZCPR. 

This  issue  also  features  a  complete 
32000-family  cross  assembler  by 
Richard  Rodman.  We’re  printing  the 
listings  in  Cauzin  Soft  strip  format. 
What  do  you  think  of  the  Softstrip 
listings?  Please  call  or  write. 
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I  am  no  businessman.  Moreover,  I  am 
the  kind  of  person  who  likes  to  take  on  a 
variety  of  projects  and  not  tie  myself  to 
projects  that  take  up  all  my  time  and  run 
on  for  years.  However,  it  has  become  ap¬ 
parent,  after  aproaching  many  people, 

;  that  the  only  way  an  S-100  magazine  wilt 
come  into  existence  is  if  I  assume  die  re¬ 
sponsibility.”  So!  Lilres,  S-100  Microsys- 
1  terns,  vol  t,  no.l,  1980. 

"John  C.  Dvorak  is  publishing  a  monthly 
four  page  review'  of  software.  The  primary 
emphasis  is  on  North  Star  system  software. 
The  sample  issue  1  received  contained  a 
|  great  deal  of  useful  information.  John  also 
distributes  a  wide  selection  of  North  Star 
software.” — Sot  Lilies,  S-100  Microsystems, 
Nov. /Dec.  1980. 

"1  remember  only  five  years  ago  buying 
my  first  copy  of  Basic  for  only  $5.  It  was  a 
mini-version  of  about  2K  bytes  of  code  on 
paper  tape.The  autiior  sold  it  directly,  as  a 
hobby.  He  had  a  good  full  titne  job  anti  this 
was  just  a  little  project  on  the  side. The  pro 
gram  provided  only  the  very  fundamental 
Basic  functions...and  there  were  a  few 
hugs  in  the  program. 

"  Today,  things  have  changed  radically  t 
have  changed  . . .  from  a  pure  hobbyist-- 
I  to  an  entrepreneur  that  relies  on  his  sys- 
j  tern  for  income.  My  needs  have  changed.  I 
need  powerful  software  which  will  allow 
!  me  to  do  my  tasks  quickly.  Also,  I  need  soft-  i 
ware  that  is  bug-free  and  does  not  consume  j 
my  time  with  debugging. 

"■....  1  think  that  I  am  typical  of  most  mi¬ 
crocomputer  users.  1  am  sure  that  most  of 
the  computer  hobbyists  of  two  to  five  years 
ago  are  the  entrepreneurs  of  today,  it 
seems  like  all  of  my  old  computer  hobbyist 
buddies  are  making  money  with  their  sys¬ 
tems,  one  way  or  another.  Although  we 
still  play  around  with  our  systems  just  for 
the  fun  of  it,  most  of  our  time  is  now  spent 
on  income  producing  projects.  "—Sol  Libes, 
S-100  Microsystems,  Sept./f§;t,  1980. 

"The  Aitair-8800  used  a  100-pin  bus  that 
was  laid  out  by  an  anonymous  draftsman 
who  arbitrarily  assigned  signal  names  to 
groups  of  connector  pins.  Originally 
known  as  the  Aitair  bus/  its  name  was 
quickly  changed  bv  other  manufacturers 
;  of  compatible  products  to  the  'Altair/tMSAi 
bus'  and  the  Aitair /tMSAl/Protech  bus.' 
Tills  was  too  much,  and  at  Atlantic  City  in 
1976  Crornemeo's  Roger  Melon  coined  the 
name  S-100  bus/  which  was  universally 
adopted  despite  protests  from  MJTS  that  it 
was  still  the  Aitair  bus.’  Sol  Libes,  Mi- 
j  crosystems,  May  1983. 
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Burning  C 

Dear  DDJ, 

So,  the  high  priest  of  obsCu- 
rity  defends  the  purity  of 
the  faith  against  the  un¬ 
washed.  Or  was  Allen  Ho- 
lub's  August  Viewpoint 
merely  a  stalking-horse? 
Better  make  that  a  dead 
horse;  let’s  flog  it  some 
more. 

First  of  all,  my  program¬ 
ming  credentials  are  better 
left  unsaid,  though  I  do 
program  regularly  in  two 
assembly  languages,  read 
(manual  in  hand)  two  or 
three  more,  own  and  try 
to  read  Knuth,  hate  strong¬ 
ly  typed  languages,  dislike 
long-winded  compilers, 
and  love  Forth.  And  as  for 
C,  it  is  everything  negative 
that  has  been  published  in 
DDJ  et  al.  You  might  accu¬ 
rately  surmise  that  I 
wouldn't  want  to  take  Mr. 
Holub’s  C  classes  and  that 
U.C.  Berkeley  wouldn't  let 
me  anyway.  But.  .  .  . 

It  doesn't  take  too  long 
for  the  non-C-fluent  to  re¬ 
alize  what  is  the  problem 
with  the  language  and 
their  grasp  of  it:  that  the 
ordinary  control  struc¬ 
tures  they  use  in  any  other 
language  are  damned  diffi¬ 
cult  to  pick  out  of  a  C  list¬ 
ing.  They  are  so  difficult 
that  someone  has  even 
written  a  book  about  it: 
The  C  Puzzle  Book.  In  spite 
of  Mr.  Holub’s  wishy  "C  is 
difficult  [because  of]  the 
ways  that  pointers  are 
used  and  so  forth”  and 
washy  “assembly-lan¬ 
guage  programmers  usual¬ 


ly  have  little  difficulty 
learning  about  pointers,’’  it 
is  the  symbols  of  the  lan¬ 
guage  that  boggle — you 
are  continually  reminded 
that  everything  you  know 
is  wrong.  %  !=  II  %s\n 
indeed! 

main! ) 

{curse 

(K  =  =  ~R  &,&  "s  % 

>>  C) 

=  K&R’s  C”; 

} 

Combine  two  glaring  stu¬ 
pidities:  a  language-wide 
propensity  for  the  least  pos¬ 
sible  typing  (these  guys  are 
two-fingered  for  sure)  and 
a  finicky  syntax  based  upon 
{}();/*  */.  (God  forbid 
that  you  miss  one.)  Add  a 
heavy  dose  of  self-righ¬ 
teous  disdain  for  anyone 
less  than  an  operating  sys¬ 
tem  hacker;  a  black-box 


("well,  this  bit  works  so  let’s 
forget  comments”)  library 
archive;  vested  interests  of 
book  publishers  to  sell 
books  that  almost  explain; 
and  finally,  those  software 
firms  and  authors  who  al¬ 
ready  have  "it”  on  one  ma¬ 
chine  (so  let’s  port  it  every¬ 
where).  Result:  a  popular 
language  with  commercial 
interests  that’s  difficult  to 
learn  yet  easy  to  use  and 
that  pays  increasing  divi¬ 
dends  to  those  who  have 
the  most  time  and  code 
invested. 

Anyway,  “Easy  C”  by 
Orlin  and  Heath  did  one 
thing  that  all  of  C  Chest 
never  has:  permitted  me  to 
read  and  use  C  within  an 
hour.  The  authors'  ap¬ 
proach  to  C  is  unique  in 
that  they  didn’t  say  every¬ 
thing  I  knew  was  wrong. 
So,  with  some  quick  typ¬ 
ing,  I've  my  own  EASYC.H. 


Interestingly,  mine  isn’t 
much  like  Orlin  and 
Heath’s  but  more  like 
Forth  (the  control  con¬ 
structs)  and  9900  assembly 
language  (the  operators).  I 
use  it  to  write  code  that  I 
can  read  tomorrow,  and 
with  its  listing  in  hand,  I 
can  decipher  even  Mr.  Ho- 
lub’s  constructs. 

I  once  wrote  a  disassem¬ 
bler  that  printed  out  the 
English  translation  of  in¬ 
structions — for  example, 
Load  Immediate  for  LI.  Af¬ 
ter  a  while  I  got  impatient 
with  its  long-windedness 
and  put  the  "correct’’  ones 
into  the  data.  I  guess  I 
learned  the  language.  EA¬ 
SYC.H  works  in  the  same 
way.  After  a  while,  INC  gets 
more  tiresome  to  type  than 
+  +.  The  neat  thing  about 
EASYC.H  is  that  I  can  mix 
the  representations  within 
the  same  program.  Allen 
Holub  reveals  more  the  ex¬ 
pert’s  impatience  than  in¬ 
sight  into  how  Easy  C  can 
aid  the  beginner. 

And  yes,  the  defines  for 
>  =,  <=,  >,  <  are  dumb. 
But  the  ones  for  &&,  1 1,  I, 
==,  &,  *,  /, ;  «,  », 
+  +, - ,  and  %,  are  god¬ 

sends  for  someone  who 
can’t  stand  to  look  at  (or 
use)  C  more  than  once  a 
month.  If  Allen  Holub 
wanted  to  do  something 
really  useful  with  C  Chest, 
he  might  publish  yet  an¬ 
other  pipeline  program 
that  would  purify  yours.c 
his.c  and  its  converse  bas¬ 
tardize  his.c  readable.c. 

Purify  might  be  already 
done  by  the  first  pass 
through  the  parser,  but  I 
could  see  using  bastardize 
every  time  I  downloaded  a 
C  program.  Or  typed  in  one 
of  Mr.  Holub’s  gems  of  con¬ 
ciseness.  That'll  work  very 
nicely — it  will  require  the 
least  typing  and  provide 
the  most  readability. 


Dr.  Dobb's  Journal,  December  1986 


10 

803 


LETTERS 


Finally,  computers  were 
developed  to  help  math 
wizards  do  millions  of  cal¬ 
culations — big  deal.  I  use 
mine  to  write  letters,  call 
up  CIS,  and  draw  pictures.  I 
couldn't  care  less  why  C 
was  put  on  this  earth  and 
will  resist  the  fascist  Pascal 
to  my  dying  day.  If  you're 
new  to  the  programming 
business,  you  should  be 
learning  Forth,  not  Pascal. 
Frederick  Hawkins 
1020  N.  6th  St. 
Allentown,  PA  18102 


Structured 

Programming 

Dear  DDJ, 

I  was  surprised  that  Mr. 
Shammas'  column  on  ge¬ 
neric  routines  (Structured 
Programming,  August 
1986)  did  not  include  any 
reference  to  the  ability  to 
create  generic  C  routines 
through  the  preprocessor. 
I  should  point  out  that  this 
is  not  my  idea.  The  tech¬ 
nique  is  described  in  Ad¬ 
vanced  C:  Food  for  the  Edu¬ 
cated  Palate,  by  Narain 
Gehani  (Computer  Science 
Press,  1985) — a  useful  and 
well-written  book.  I  in¬ 


clude  a  generic  sort  routine 
[see  Table  1,  below]  that  I 
have  found  useful  for  sort¬ 
ing  arrays  of  various  types. 
It  can  be  instantiated  by: 

GENERIC_SORT(int _ sort, 

int,  >), 
or 

GENERIC—SORT- 

(float_sort,  float,  <) 

The  sort  I  used  is  the  stan¬ 
dard  Shell  sort,  a  la  K  &  R. 
Keep  up  the  good  work! 
Kit  Kauffmann 
Algorithms  Unlimited 
P.O.  Box  3516 
Ogden,  UT  84409 


Dear  DDJ, 

I  read  with  interest  the  Au¬ 
gust  1986  Structured  Pro¬ 
gramming  column  about 
generic  procedures  in  Ada 
and  Modula-2.  I  agree  that 
generic  procedures  are 
powerful  and  desirable 
features. 

Both  languages  imple¬ 
ment  generic  procedures 
in  an  overly  complicated 
manner,  however.  I  use  a 
language  in  which  all  pro¬ 
cedures  and  functions  are 
generic  because  all  formal 
parameters  are  typeless 
until  the  procedure  or 
function  is  called.  Another 
feature  of  this  language 
that  helps  toward  generic 
procedures  and  functions 
is  coercion  between  data 
types.  You  can  set  string 
variables  equal  to  numeric 
types  and  vice  versa.  Inte¬ 
ger  variables  set  equal  to  a 
real  number  will  automati¬ 
cally  round  the  real  num¬ 
ber  to  the  nearest  integer. 
Real  number  variables  can 
take  on  the  value  of  inte¬ 
gers.  I  feel  that  late  binding 
procedures  and  functions 
and  coercion  between  data 
types  provide  an  ideal  pro¬ 
gramming  environment. 
The  language  that  provides 
these  features  is  Sinclair 
SuperBasic  as  implement¬ 
ed  on  the  Sinclair  QL.  This 
version  of  BASIC  is  highly 
structured  and  flexible, 
supporting  such  features 
as  bitwise  manipulation.  I 
have  included  a  listing  [Ta¬ 
ble  2,  left]  of  a  generic  Shell 
sort  in  SuperBasic  that  can 
sort  strings,  reals,  and  inte¬ 
gers.  Love  your  magazine! 

Michael  A.  McCoy 

Box  84  King  Edward’s  Ct. 

Rocky  Mount,  NC  27803 
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#define  GENERIC_SORT(NAME,  ELEM-TYPE,  OP)  NAME(v,  n)\ 

ELEM_TYPE  v[  ];  int  n;\ 

{\ 

ELEM_TYPE  temp;\ 
int  gap,  i,  j;\ 

for(gap  =  n/2;  gap  >  0;  gap  /=  2)\ 
for<i  =  gap;  i  <  n;  i++)\ 

for(j  =  i-gap;  j  >=  0  &&  v[j]  OP  v[j+gap];j  -  =  gap)\ 

{\ 

temp  =  v[j);\ 
v[j]  =  v[j+gap];\ 
v[j+gap]  =  temp;\ 

}\ 

} 

Table  1: 

Generic  sort  routine  in  C 

100 

REMark  Example  of  a  generic  Shell  sort  in  Sinclair  SuperBasic 

110 

j 

120 

DEFine  PROCedure  shell_sort(L,Num) 

130 

LOCal  Offset%,l,J,K,  Divide_And_Conquer,Get_ln_Order,ln_Order, Tempi 

140 

Offset%  =  Num 

150 

REPeat  Divide_And_Conquer 

160 

IF  Offset%  <=  1  THEN  EXIT  Divide_And_Conquer 

170 

Offset%  =  Offset%  /  2 

180 

REPeat  Get_ln_Order 

190 

ln_Order  =  —  1 

200 

K  =  Num  —  Offset% 

210 

FOR  J  =  0  to  K 

220 

1  =  J  +  Offset% 

230 

IF  L(J)  >  Lfl)  THEN 

240 

ln_Order  =  0 

250 

Tempi  =  Lfl) 

260 

L(l)  =  L(J) 

270 

L(J)  =  Tempi 

280 

END  IF 

290 

END  FOR  J 

300 

IF  ln_OrderTHEN  EXIT  Get_ln_Order 

310 

END  REPeat  Get_ln_Order 

320 

END  REPeat  Divide_And_Conquer 

330 

END  DEFine  shelLsort 

Table  Z:  Generic  Shell  sort  in  Sinclair  SuperBasic 
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And  you  may  ask  yourself 
What  is  that  beautiful 
house ? 

And  you  may  ask  yourself 
Where  does  that  highway 
go  top 

And  you  may  ask  yourself 
Am  I  right?  . .  .  Am  I 
wrong ? 

And  you  may  say  to 
yourself 

My  God!  What  have  I  done? 
from  "Once  in  a  Lifetime  ” 
— David  Byrne,  Brian  Eno 

I've  a  confession  to  make — 
I’m  really  a  composer,  a 
musician,  not  a  computer 
programmer  at  all.  I  went 
back  to  school  to  learn  how 
to  build  synthesizers,  and 
learning  about  computers 
was  a  side  effect.  I  like  to 
program  and  to  design 
hardware,  but  I've  become 
increasingly  uncomfort¬ 
able  about  engineering  as  a 
profession.  More  accurate¬ 
ly,  I  have  reservations 
about  the  uses  to  which  my 
work  can  be  put. 

My  main  reservations 
have  to  do  with  weapons 
construction.  I  don’t  like  it, 
but  it  can  be  difficult  to  get 
away  from.  After  graduat¬ 
ing,  I  worked  on  miltary- 
related  projects  for  a  while 
without  really  worrying 
about  the  ultimate  pur¬ 
poses  of  my  work.  The 
work  was  technically  in¬ 
teresting  and  wasn't  close¬ 
ly  related  to  weapons  de¬ 
velopment — or  so  I 
thought.  One  day,  after 
working  for  a  year  on  a 
consulting  project — build¬ 
ing  a  manufacturing  con¬ 
trol  system  for  airplanes — I 

by  Allen  Holub 

discovered  that  the  air¬ 
planes  in  questions  were  F- 
16s.  This  project  was  much 
too  close  to  weapons  pro¬ 
duction  for  me  to  be  com¬ 
fortable;  I  could  no  longer 


ignore  what  I  was  doing. 

This  put  me  in  a  real 
quandary.  On  one  hand  I 
was  disgusted  by  what  I 
was  building;  on  the  other 
hand  I  had  committed  my¬ 
self  to  finishing  the  project 
and  I’m  very  old-fashioned 
about  fulfilling  promises.  If 
I  just  left  the  project,  it 
wouldn't  get  finished  (I 
was  managing  the  soft¬ 
ware  development  and 
had  written  a  good  portion 
of  the  code).  I  dealt  with 
my  conscience  by  doubling 
my  consulting  rate  and  giv¬ 
ing  the  extra  money  away 
to  peace  groups.  The  client 
was  not  happy  but  had  no 
choice.  I  finished  up  the 
project  as  quickly  as  I  could 
and  left. 

I  had  no  trouble  finding 
another  consulting  job.  My 
new  client's  reaction  to 
what  had  transpired  at  the 
old  job  was  more  amuse¬ 
ment  than  anything  else, 
and  I  thought  I  had  found  a 
company  with  a  con¬ 
science.  Unfortunately,  the 
new  company  started  pro¬ 
ducing  products  that  were 
sold  almost  exclusively  to 
defense  contractors.  I 
wasn't  working  on  these, 
but  I  was  still  uncomfort¬ 
able.  Giving  money  to 
peace  groups  didn't  satisfy 
my  conscience  anymore. 

There  is  no  easy  way  for 
me  to  deal  with  conflicts 
between  my  professional 
interests,  financial  needs, 
and  conscience.  The  prob¬ 
lems  have  been  made 
worse  by  the  Reagan  ad¬ 
ministration’s  emphasis  on 
defense  spending — let’s 
face  it,  an  ever  increasing 
percentage  of  the  interest¬ 
ing  and  well-paying  jobs 
are  in  weapons  work.  My 
solution  has  been  to  move 
gradually  out  of  the  field.  I 
only  take  consulting  pro¬ 
jects  that  I'm  convinced  are 
not  related  to  weapons  and 


with  companies  that  don't 
do  weapons  work.  I’m  a 
DUMPY,  a  downwardly  mo¬ 
bile  young  professional. 
My  income  has  dimin¬ 
ished,  but  it's  still  adequate. 
More  important,  I’m  doing 
things  that  I  think  benefit 
society. 

To  make  my  "sudden  on¬ 
slaught  of  conscience"  (to 
quote  one  of  my  managers) 
more  intelligible,  I'll  ex¬ 
plain  some  of  my  political 
views.  I've  come  to  believe 
that  the  out-of-control 
arms  buildup  is  not  just  the 
responsibility  of  govern¬ 
ment.  Nuclear  weapons 
don't  spring,  like  Athena, 
fully  armed  from  the  head 
of  Zeus.  They're  designed 
and  built  by  engineers  and 
programmers,  by  you  and 
me.  If  we  refused  to  build 
them,  they  wouldn't  exist. 

How  is  it,  then,  that  a 
programmer  who  sup¬ 
ports  a  nuclear  freeze  goes 
off  to  work  every  morning 
for  a  defense  subcontrac¬ 
tor  that's  making  control 
systems  for  F-16s?  How  can 
we  allow  a  regular  pay- 
check  to  be  more  impor¬ 
tant  than  the  ultimate 
harm  we  are  doing  to  soci¬ 
ety?  Weapons  work  is 
grave  digging,  quite  literal¬ 
ly.  What  good  is  a  nice  fat 
paycheck  when  your  life 
has  been  reduced  to  a  heap 
of  radioactive  slag?  If  nu¬ 
clear  weapons  are  used 
again,  won’t  the  develop¬ 
ers  be  just  a  much  mass 
murderers  as  the  madmen 
who  pushed  the  buttons? 

Of  course,  there  are  peo¬ 
ple  who  have  thought 
about  these  issues  and  have 
come  to  the  opposite  con¬ 
clusion  from  mine:  They 
believe  that  a  strong  nucle¬ 
ar  arsenal  makes  the  world 
a  safer  place.  Though  I 
think  they're  wrong,  these 
people  are  at  least  acting 
according  to  their  beliefs.  I 


have  a  hard  time,  though, 
with  people  who  refuse  to 
look  at  the  issues  and  build 
weapons  anyway.  We 
don't  mitigate  the  effect  of 
our  work  by  not  analyzing 
what  we’re  doing.  That  the 
human  race  could  be  put  to 
an  end,  and  that  some  hu¬ 
mans  seem  to  be  trying  to 
do  just  that,  should  give 
any  thinking  person  pause. 
That  people  can  just  sit 
back  and  let  this  happen  is 
unconscionable.  That  some 
engineers  claim  to  oppose 
the  use  of  nuclear  weapons 
or  don’t  look  at  the  issues  of 
weapons  production  and 
still  help  to  build  them  is 
worse. 

What  I'm  trying  to  do  is 
to  convince  you  to  do 
something.  Those  who 
don't  like  the  work  their 
companies  are  doing  could 
try  to  change  things.  If  they 
can’t,  they  could  get  anoth¬ 
er  job — like  Peter  Hagel- 
stein,  the  key  Star  Wars  sci¬ 
entist  who  recently 
resigned  from  Lawrence 
Livermore  Lab  because  he 
was  reportedly  so  unhap¬ 
py  about  doing  weapons 
research  with  X-ray  lasers. 

I  strongly  believe  that  an 
engineering  ethics  course 
should  be  a  required  part 
of  every  EECS  curricu¬ 
lum — a  course  that  would 
get  people  to  look  beyond 
that  fat  paycheck  to  the  ef¬ 
fects  of  their  work  on  soci¬ 
ety.  Those  of  us  who  work 
for  universities  could  try  to 
get  such  a  course  going.  We 
can  contact  our  legislators. 
We  can  work  with  peace 
groups.  Whatever  we  do, 
we  musn't  sit  around  and 
wait  for  the  bombs  to  be 
dropped — or  they  will  be. 

DDJ 
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A  Multitasking 
Kernel 


Tele  is  a  multitasking 
operating  system  for 
the  IBM  PC  and  com¬ 
patibles  that  is  written  in  C 
and  assembly  language.  This 
article  describes  in  detail  the 
most  critical  part  of  Tele,  the 
task  scheduler,  which  han¬ 
dles  the  allocation  and  distri¬ 
bution  of  CPU  time  to  the  var¬ 
ious  tasks  in  the  system.  If  you  roll  your  own  operating 
system,  the  task  scheduler  probably  will  present  the  most 
difficult  problems.  I  hope  to  provide  enough  information 
to  make  it  possible  for  you  to  design  a  task-scheduling 
kernel  for  your  own  multitasking  operating  system. 

Tele  contains  three  large  blocks  of  code:  the  run-time 
library,  the  file  system,  and  the  task  scheduler.  These  ac¬ 
count,  roughly,  for  1/3, 1/2,  and  1/6  of  the  total  amount  of 
code. 

The  Run-Time  Library 

The  Tele  run-time  library  has  unique  features,  but  all 
such  libraries  are  essentially  alike.  They  encapsulate  algo¬ 
rithms  common  to  a  wide  range  of  applications  and 
thereby  reduce  the  amount  of  time  needed  to  code  appli¬ 
cation  programs. 

The  File  System 

Tele's  file  system  is  complex  because  of  my  requirement 
that  it  support  both  MS-DOS  and  Unix  media.  All  my  devel¬ 
opment  tools  were  written  for  MS-DOS,  so  all  the  files  had 
to  be  on  MS-DOS  media.  I  could  therefore  use  MS-DOS  for 
the  file  system  as  I  implemented  other  parts  of  Tele.  I 
eventually  completed  the  Tele  file  system  to  significantly 


Ken  Berry,  P.O.  Boy  966,  Jackson,  CA  95642-0966. 
®  1986  by  Ken  Berry.  All  rights  reserved 


improve  performance,  but 
everything  else  was  fully 
tested  at  that  time. 

Task  Scheduler 

The  security  kernel,  or  task 
scheduler,  of  an  operating 
system  is  responsible  for  the 
allocation  of  system  re¬ 
sources  to  tasks.  It  takes  its 
name  from  military  and  financial  applications  in  which 
security  means  protection  against  intrusion  and  sabotage. 
I  don’t  worry  about  that  kind  of  security  because  I  don’t 
leave  my  computer  connected  to  the  public  communica¬ 
tions  system.  I  do,  however,  make  programming  mis¬ 
takes.  In  particular,  I  sometimes  mess  up  the  stack  and 
cause  a  program  to  return  to  the  wrong  location.  When  a 
program  runs  wild,  it  can  execute  any  conceivable  code, 
so  there  is  no  logical  difference  between  a  saboteur  pro¬ 
gram  introduced  by  a  spy  and  a  benign  program  that  has 
run  wild.  An  operating  system  that  cannot  be  crashed  by 
an  application  is  identical  to  one  that  is  secure  from 
intrusion. 

In  order  to  make  a  secure  (or  crashproof)  system,  you 
must  have  a  task  scheduler  that  enforces  certain  rules  on 
every  other  program.  The  rules  determine  what  data  can 
be  accessed  and  where  control  can  be  passed;  they  must 
be  enforced  on  the  execution  of  every  instruction.  Proces¬ 
sors  such  as  the  80286  and  80386  check  every  instruction 
for  security  violations.  Other  processors,  such  as  the 
68000  and  32000  series  can  also  support  secure  systems. 
The  more  common  8086  and  8088  processors  cannot. 

The  necessary,  and  sufficient,  rules  for  a  secure  system 
are  simple.  All  programs  are  ranked  according  to  security 
level,  or  degree  of  trust.  A  task  can  access  data  only  at  its 
own  level  or  at  a  less  trusted  level.  It  can  call  another 
program  or  subroutine  at  its  own  level  or  at  a  more  trust- 
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Tele  implements  an  80386-like 
task  scheduler  on  ‘\ unsecure * 
processors . 
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Tele  uses  a  fixed  execution  interval — that  is,  a  periodic 
interrupt  is  used  to  divide  time  into  equal  intervals.  Each 
interrupt  marks  the  end  of  an  application  task  execution 
interval.  Higher  priority  tasks  are  allowed  to  execute 
more  often,  but  all  tasks  are  equal  in  being  allowed  to 
execute  for  one  interval  at  a  time.  Another  way  of  imple¬ 
menting  priorities  is  to  vary  the  execution  interval,  allow¬ 
ing  higher  priority  tasks  to  execute  for  longer  each  time.  I 
had  to  use  the  fixed-period  method  because  a  standard  PC 
has  only  one  programmable  interrupt  available. 

The  interrupt  is  generated  by  an  8253  clock/timer  cir¬ 
cuit  attached  to  an  8259  interrupt  controller.  The  8253 
provides  three  programmable  timers:  one  of  these  is  used 
to  refresh  memory  (Tele  makes  use  of  this  for  high-resolu¬ 
tion  timing,  as  explained  later),  another  generates  the  sig¬ 
nal  used  for  the  operator  alarm  speaker,  and  the  third 
timer  can  be  used  to  interrupt  the  processor. 

Tele  actually  requires  three  interrupts.  One  is  necessary 
to  measure  time  and  maintain  a  time-of-day  clock.  Anoth¬ 
er  is  needed  to  update  the  console  display.  The  display 
driver  Tele  uses  is  six  times  more  efficient  than  the  stan¬ 
dard  BIOS,  besides  supporting  window  overlays.  The  dis¬ 
play  driver  is  relevant  here  only  because  it  requires  a  peri¬ 
odic  interrupt  synchronized  to  the  display  hardware.  The 
third  interrupt  required  is  to  preempt  application  tasks. 
Fortunately,  it  is  possible  to  serve  all  three  functions  with  a 
single  interrupt  provided  it  has  a  fixed  period  (which  must 


be  harmonically  related  to  the  display  hardware). 

Function  t _ tick  in  Listing  Four  services  the  system  tick 

interrupt.  Because  bad  things  happen  if  it  does  not  com¬ 
plete  executing  before  the  next  interrupt,  an  interlock  is 
provided  to  ignore  subsequent  interrupts  until  the  first  is 
complete.  This  is  a  protection  that  should  only  be  needed 
in  debugging,  but  it  costs  little  time  and  those  bad  things 
that  happen  involve  corrupting  the  stack  and  making  the 
processor  run  wild. 

After  preventing  reentrance,  the  current  application 
task  execution  interval  is  terminated  by  storing  OjcFF  in 
the  system  variable  t^astrm.  Then  the  system  state  is  en¬ 
tered,  as  explained  later.  The  next  step  is  to  save  the  com¬ 
plete  machine  state  of  the  interrupted  task.  The  state  is 
saved  on  the  task  stack,  and  then  a  special  system  stack  is 
made  current. 

Tele  measures  the  execution  time  of  all  tasks  to  a  high 
resolution.  This  is  described  in  detail  later  but  is  accom¬ 
plished  by  a  call  to  function  t—rtmark  immediately  after 
storing  the  application  machine  state.  All  processor  cy¬ 
cles  until  the  next  call  to  t_rtmark  will  be  counted  and 
accumulated  under  an  internal  task. 

The  initial  operations  take  a  small,  fixed  amount  of  time 
so  that  control  reaches  the  fourth  step  in  synchrony  with 
the  console  display  hardware.  Function  w — cdspl  is 
called  just  as  the  vertical  blanking  interval  begins  so  that 
the  display  can  be  updated  rapidly  without  any  interfer¬ 
ence  appearing  on  the  screen.  The  display  update  can  last 
almost  4  milliseconds  under  some  conditions.  When  the 
tick  clock  has  a  frequency  higher  than  that  of  the  display, 


Figure  1:  Task-scheduling  state  machine 
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off  by  several  milliseconds — it  is  only  the  long-term 
(greater  than  1  second)  averages  that  are  correct. 

Finally  t - tick  is  ready  to  terminate  the  current  appli- 

say  120  Hz,  w — cdspl  is  not  called  on  each  interrupt.  Be-  cation  task  execution  interval  and  return  control  to 

cause  w. — cdspl  recieves  control  about  GO  times  each  sec-  t _ krnl.  These  other  operations  may  seem  complicated, 

ond,  for  a  120-Hz  tick  clock,  half  the  interrupts  bypass  the  but  they  execute  very  quickly  and  have  no  side  effects.  No 
display  update.  problems  will  develop  by  ignoring  the  first  several  steps 

The  next  step  is  to  maintain  the  time-of-day  clock.  Tele  and  assuming  that  control,  in  response  to  a  tick  interrupt, 
provides  the  current  time  of  day  to  application  programs  goes  immediately  to  label  tick3. 

in  an  ASCII  character  string  accurate  to  0.05  second.  The  First,  t_rtmark  is  again  called  to  resume  counting  pro¬ 
tick  frequency  is  nearly  a  multiple  of  this  but  not  exactly,  cessor  cycles  for  the  interrupted  task.  Then  t _ tick  de- 

so  t - tick  maintains  a  series  of  counters  to  skip  some  ticks  cides  whether  to  resume  the  interrupted  task  or  to  pass 

and  duplicate  others.  The  end  result  is  that  the  long-term  control  back  to  t _ krnl.  Some  tasks  must  not  be  interrupt- 

average  is  very  nearly  20  Hz.  The  time-of-day  clock  is  ed — for  instance,  a  system  program  might  be  rearranging 
intended  to  present  the  time  to  the  operator  and  to  time-  the  linkage  between  tasks.  If  control  were  to  return  to  the 
stamp  operations  (it  looks  fast  to  a  human  being).  task  scheduler  before  the  linkage  was  fully  corrected, 

To  simplify  developing  Tele  under  MS-DOS,  I  also  main-  pointers  could  get  lost  and  bad  things  happen.  One  way  to 
tain  the  standard  BIOS  time-of-day  interrupt.  The  BIOS  pro-  prevent  this  would  be  to  disable  interrupts,  but  that 
grams  the  tick  clock  to  produce  an  18.2-Hz  interrupt.  Tele  would  impinge  on  the  device  drivers.  In  fact,  it  is  impor- 
uses  some  additional  counters  to  derive  this  frequency  tant  to  make  all  times  that  interrupts  are  disabled  as  short 
from  its  20-Hz  clock.  The  standard  BIOS  procedure  is  as  possible.  The  time  required  to  update  the  task  queue 
maintained  by  relocating  its  interrupt  vector  before  linkages  is  much  too  long. 

t _ tick  is  installed  to  service  the  tick  clock.  The  alternate 

interrupt  is  then  invoked  at  the  appropriate  times  to  Execution  States 

maintain  a  long-term  average  of  18.2  interrupts  per  sec-  Tele  solves  this  problem  by  defining  two  execution  states: 
ond.  Notice  that  at  any  particular  instant  the  clocks  can  be  application  and  system.  A  program  enters  the  system 


Figure  2:  System  state  function 
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state  when  it  must  be  allowed  to  finish  an  operation  be¬ 
fore  it  is  preempted.  This  is  something  like  disabling  in¬ 
terrupts,  but  the  interrupt  hardware  remains  fully  func¬ 
tional  and  enabled.  In  the  application  state,  a  task  may  be 
preempted  and  not  resumed  for  an  indefinite  period.  I 
call  the  special  state  system  to  emphasize  that  it  must  not 
be  entered  lightly.  Programs  that  enter  it  must  be  de¬ 
bugged  and  be  sure  to  exit  from  the  system  state  at  their 
earliest  opportunity.  Figure  2,  page  20,  is  a  flowchart  of  a 
program  that  enters  the  system  state. 

The  system  state  is  entered  with  the  sys—entr  macro 
(see  Listing  Two).  OyFF  is  stored  in  the  system  variable 
sys—ilck  with  a  locked  exchange  instruction.  The  lock  en¬ 
sures  that  OyFF  is  stored  and  the  orginal  contents  are  load¬ 
ed  without  any  intervening  bus  cycles.  Therefore  it  will 
work  even  if  multiple  processors  are  accessing  a  common 
memory.  Whenever  sys—ilck  contains  OyFF,  the  current 
program  is  in  the  system  state.  When  it  contains  OyOO,  the 
program  is  in  the  application  state.  The  sys^entr  macro 
stores  OyFF  in  sys—ilck  and  stores  the  original  contents  of 
sys—ilck  in  a  local  flag. 

After  the  protected  operation  is  complete,  the  sys^eyit 
macro  is  used  to  exit  from  the  system  state.  The  tick  ser¬ 
vice  function,  t _ tick,  uses  the  sys—entr  macro  but  does 

not  use  sys—eyit.  All  other  functions  that  execute  in  the 
system  state  use  both  macros. 


In  the  sys_ey;f  macro,  variable  t—astrm  is  examined 
first.  If  it  contains  OyOO,  the  current  execution  interval  has 
not  terminated  and  control  returns  normally.  If  t—astrm 
contains  OyFF,  the  current  application  has  been  preempt¬ 
ed  while  it  was  in  the  system  state.  Instead  of  returning 
control  to  the  calling  program,  sys—eyit  examines  the  orig¬ 
inal  sys-ilck  value.  If  sys—ilck  contained  OyOO,  the  current 
task  is  terminated  by  calling  function  t_term  (Listing 
Three).  But  if  both  t—astrm  and  sys—ilck  contain  OyFF,  the 
function  calling  the  current  one  (where  sys—eyit  is  being 
processed)  was  already  in  the  system  state.  Again  control 
returns  to  the  calling  program.  This  scheme  allows  pro¬ 
grams  to  be  nested  in  the  system  state.  Eventually  control 
will  return  to  the  first  program  to  enter  the  system  state.  At 
that  time  the  t—astrm  variable  controls  processing. 

Function  f _ tick  is  slightly  different.  One  difference  is 

because  t _ tick  is  the  only  function  to  set  t—astrm  to  OyFF. 

T—astrm  is  set  to  OyOO  when  an  application  task  is  initially 
dispatched.  It  is  set  to  OyFF  when  the  tick  interrupt  occurs. 

The  other  difference  involves  the  stack.  Every  task  has 
its  own  stack — at  least  one.  The  task  scheduler  also  has  its 

own  private  stack.  Function  t _ tick  saves  the  interrupted 

machine  state  on  the  application  stack  and  then  establish¬ 
es  the  system  stack — that  is,  the  stack  private  to  t _ krnl. 

The  system  stack  is  then  used  for  all  subsequent  process¬ 
ing  within  t _ tick. 

When  control  is  ready  to  exit  from  t _ tick,  only  the 

value  of  sys—ilck  at  the  time  of  the  interrupt  need  be 
examined  (t—astrm  is  always  set  by  this  time).  If  it  was 
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tfyOO,  control  simply  returns  into  the  system  stack.  But  if 
sys—ilck  contained  OyFF  at  the  time  the  tick  interrupt  oc¬ 
curred,  the  task  was  in  the  system  state  and  should  not  be 

preempted.  In  this  case,  t _ tick  restores  the  original  stack 

and  returns  into  it,  thereby  resuming  the  interrupted 
task.  That  task  will  then  finish  whatever  operation  re¬ 
quired  system  state  protection  and  will  eventually  exe¬ 
cute  a  sys—eyit  macro,  causing  control  to  enter  function 
t_fer/n. 

Figure  1  shows  the  task  queues  and  the  paths  along 
which  tasks  are  moved  from  one  queue  to  another.  The 
paths  are  labeled  according  to  the  function  that  performs 
the  transfer.  Function  f_ferm  is  shown  moving  the  cur¬ 
rent  task  to  the  priority  queue  (from  C  to  P).  T _ tick  per¬ 

forms  this  same  function. 

Closely  related  to  function  t—lerm  are  functions  f_re/s, 
tspnd,  and  t_walf.  All  these  functions  call  another, 


t _ trmap,  to  terminate  the  current  application  task.  This 

is  done  by  first  storing  the  current  machine  state  on  the 

application  stack.  Then  control  enters  function  t _ sstk  to 

establish  the  system  stack  (the  stack  used  by  t _ krnl). 

T _ sstk  exits  by  returning  to  the  caller  of  t _ trmap. 

The  difference  between  t_term,  tspnd,  t—wait,  and 

t__re/s  is  in  the  value  they  return.  Because  t _ stck  has 

changed  the  stack,  they  return  into  the  system  stack,  not 
the  stack  they  were  called  with.  Their  return  codes  are 

ultimately  presented  to  t _ krnl  and  determine  the  path 

that  the  task  will  follow  away  from  queue  C  in  Figure  1. 

Function  t_term  returns  a  code  of  0  and  causes  the  task 
to  be  returned  to  the  priority  queues,  P.  There  it  will 
compete,  on  the  basis  of  priority,  with  other  tasks  to  be 
returned  to  the  execution  queue,  X.  Function  t_re/s  re¬ 
turns  a  code  of  —1,  which  causes  the  task  to  be  returned 
to  the  bottom  of  the  execution  queue. 

T^spnd  returns  a  positive  return  code  between  1  and 
32,767.  This  number  indicates  the  number  of  ticks  for 
which  the  task  will  be  suspended.  That  is,  if  the  return 
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value  is  12  and  the  tick  frequency  is  120  Hz,  the  task  will 
be  suspended  for  1/10  second.  T_waff  is  a  combination;  it 
first  calls  tspnd  and  then  calls  t_re/s.  Therefore  tspnd 
suspends  the  task  for  a  time,  after  which  the  task  is  placed 
at  the  top  of  the  execution  queue.  T—wait  suspends  the 
task  but  restores  it  to  the  bottom  of  the  queue. 

Tele  therefore  has  a  real-time  scheduling  capability 
based  on  the  frequency  of  the  tick  clock.  The  resolution  is 
not  adequate  for  many  applications  but  is  sufficient  for 
times  relevant  to  the  human  operator.  For  example,  an 
alarm  can  be  sounded  by  beeping  the  speaker,  and  the 
duration  of  the  beep  is  measured  by  the  tick  clock  using 
function  t^spnd.  The  standard  BIOS  enters  an  idle  loop  that 
literally  wastes  time  to  measure  the  beep's  duration,  but 
Tele  is  able  to  continue  doing  other  work.  Similarly,  many 
Tele  drivers  utilize  special  tasks  and  t^spnd  to  implement 
time-outs  and  thereby  detect  unresponsive  equipment. 

Looping 

T-krnl  processes  the  return  codes  from  t—term  and  its 

associated  functions.  T _ krnl  is  an  infinite  loop — once 

control  enters,  it  never  leaves  except  by  calling  applica¬ 
tion  tasks.  The  application  tasks  eventually  return  to 

t _ krnl  and  control  continues  to  loop.  Figure  3,  page  24, 

shows  the  flowchart  for  t _ krnl. 

At  the  beginning  of  the  loop  t^astrm  is  examined.  If  it 
contains  OyOO,  no  tick  interrupt  has  occurred.  Otherwise 

it  will  contain  OyFF,  and  function  t_ _ wtst  is  called. 

T _ wtst  will  examine  the  wait  queue  (W)  and  move  all 

tasks  scheduled  to  be  executed  at  the  current  system  tick 
to  the  top  of  the  execution  queue.  Then  the  execution 
queue  is  examined.  If  it  is  not  empty,  the  task  on  top  is 
made  current;  it  is  moved  from  X  to  C  as  shown  in  Figure 
1.  If  the  execution  queue  is  empty,  t _ krnl  will  keep  loop¬ 

ing.  Eventually  a  task  will  appear  in  the  execution  queue, 
and  it  will  be  executed. 

Tasks  are  actually  executed  by  calling  function  t _ ytsk. 

T — yfsk  first  calls  t^rtmark  to  stop  accumulating  proces¬ 
sor  cycles  to  the  task  scheduler.  It  then  calls  function 

t — dspap,  which  is  the  converse  of  function  t _ trmap.  It 

restores  an  application  stack  and  then  loads  the  machine 

registers  from  it.  Control  will  exit  from  t _ dspap  to  the 

point  following  an  earlier  call  to  t _ trmap,  and  the  appli¬ 

cation  will  run  until  it  terminates  (or  is  terminated). 

Control  will  then  return  to  the  point  following  the  call 

to  t — dspap  in  function  t _ ytsk.  The  return  code  set  by 

t_term  and  its  associated  functions  is  then  presented  to 

t — yts/c,  which  passes  it  back  to  t _ krnl  when  t _ pctsk 

returns.  Before  returning,  t _ yf.sk  again  calls  t _ rtmark. 

This  time  the  call  causes  subsequent  processor  cycles  to 
be  accumulated  to  the  task  scheduler. 

T — yfs/c  is  able  to  determine  the  actual  execution  time 
of  the  application  task.  This  can  be  much  less  than  a  full 
system  tick  interval  if  the  application  was  interrupted 
many  times.  If  the  true  execution  time  is  less  than  a  cer¬ 
tain  threshold,  t _ yfsk  immediately  executes  the  task 

again.  This  is  done  only  if  the  task  was  preempted.  If  the 
task  terminated  itself  (by  calling  t^spnd,  t—rels,  or  f_waif), 
no  check  of  execution  time  is  made. 

If  the  task  had  a  fair  chance  at  the  processor,  or  termi¬ 
nated  itself,  control  returns  from  t _ yfsk  to  f _ krnl.  Now 

the  return  code  established  by  f_ferm  and  the  others  is 


examined.  If  the  return  is  less  than  0,  function  t - inyq  is 

called  to  move  the  task  to  the  bottom  of  the  execution 

queue.  If  the  return  is  0,  function  t _ inpq  is  called  to  move 

the  task  to  the  priority  queues.  Otherwise  function 

t _ inwq  is  called  to  insert  the  task  into  the  wait  queue. 

That  completes  the  task  scheduler  loop,  which  is  often 
called  a  monitor  or  supervisor  cycle  in  other  operating 
systems. 

Multitasking  System  Techniques 

Tele  uses  its  central  task-scheduling  algorithm  to  support 
other  features.  Figure  1  indicates  that  function  t — sch 
moves  tasks  from  the  priority  queue  to  the  bottom  of  the 
execution  queue.  This  function  is  not  called  by  any  other 
task.  It  is  placed  in  the  execution  queue  when  the  system 
is  initialized.  When  it  executes,  it  enters  the  system  state 
and  processes  the  priority  queues,  taking  tasks  from  P  to 
the  bottom  of  X.  It  places  itself  at  the  bottom  of  the  execu¬ 
tion  queue  last.  Therefore,  when  all  the  tasks  it  has  sched¬ 
uled  have  been  run,  it  will  run  again  itself  in  order  to 
schedule  more. 

It  is  easy  to  extend  this  concept  to  several  versions  of 

t _ sch,  each  operating  on  a  different  set  of  priority 

queues.  Some  IBM  mainframe  operating  systems  obtain  a 
similar  effect  with  programs  called  initiators. 

A  similar  function  is  t _ clndr,  which  lives  in  the  wait 

queue.  It  provides  for  long-term  calendar  functions  by 
periodically  executing  and  then  rescheduling  itself  in  the 
wait  queue.  As  shown  in  Figure  1,  the  wait  queue  ac¬ 
counts  for  a  short  time — about  30,000  ticks.  At  a  120-Hz 
tick  clock  rate,  this  is  about  4.5  minutes.  T _ clndr  exe¬ 

cutes  once  every  minute.  It  examines  an  extended  calen¬ 
dar  file  on  disk,  and  as  the  time  to  execute  programs 
nears,  it  creates  tasks  in  the  wait  queue. 

High-Resolution  Clock 

Tele  measures  the  execution  time  of  every  application 
task.  It  also  measures  the  amount  of  time  spent  processing 
the  system  tick  interrupt  and  scheduling  the  next  task. 
This  is  done  with  a  resolution  of  15  microseconds. 

A  standard  IBM  PC  uses  one  channel  of  an  8257  DMA 
(direct  memory  access)  controller  to  refresh  dynamic 
memory.  Dynamic  memory  chips  are  based  on  leaky  ca¬ 
pacitors,  which  means  they  must  be  read  periodically  in 
order  to  maintain  their  contents  (when  read,  the  chip 
automatically  recharges  its  capacitors).  Most  dynamic 
memory  chips  can  be  properly  refreshed  by  reading  128 
consecutive  addresses  every  2  milliseconds.  Most  PCs  do 
this  by  programming  one  channel  of  the  same  8253 
counter  to  produce  a  signal  with  a  15-microsecond  peri¬ 
od.  This  signal  then  requests  the  DMA  controller  to  read 
the  memory.  Special  circuitry  causes  all  memory  chips  to 
be  read  at  once  (the  data  read  is  ignored).  The  DMA  con¬ 
troller  automatically  increments  its  address  after  each 
request. 

The  processor  can  read  the  current  address  in  the  DMA 
controller  at  any  time.  Because  the  refresh  circuitry  runs 
continuously  from  the  time  the  computer  is  powered  up, 
the  current  address  is  a  convenient  high-resolution  clock. 

In  standard  PCs,  the  processor  clock  and  8253  clock  are 
both  derived  from  the  same  crystal.  They  therefore  main¬ 
tain  a  constant  phase  difference.  When  the  tick  clock  is 
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tasks  that  get  short  execution  intervals  because  of  heavy 

interrupt  service. 

started,  the  current  reading  of  the  high-resolution  clock  is 

Installation 

saved.  This  allows  programs  to  relate  the  high-resolution 

Tele  is  designed  to  be  a  collection  of  programmers'  tools. 

clock  to  the  current  time  of  day  and  make  absolute  time 

The  listings  with  this  article  are  suitable  for  inclusion 

measurements  to  within  15  microseconds. 

with  small-memory-model  C  programs.  To  make  them 

Tele  itself  only  uses  the  high-resolution  clock  to  count 

work,  you  must  assemble  and  compile  them  into  a  li- 

processor  cycles.  A  refresh  cycle  is  72  processor  cycles  on 

brary .  Then  you  can  reference  these  functions  from  your 

a  4.77-MHz  processor — it  is  more  on  faster  ones.  There- 

own  programs. 

fore  the  number  of  processor  cycles  measured  can  vary 

I  developed  the  code  using  the  Lattice  C  compiler,  Ver- 

from  run  to  run.  The  count  tends  to  become  more  accu- 

sion  2,  and  Microsoft  MASM  assembler,  Version  1.  I  later 

rate  as  longer  runs  are  measured. 

upgraded  to  Versions  3  and  4  and  had  to  make  minor 

Function  t—rtmark  (Listing  Four)  is  provided  to  read  the 

changes.  If  you  use  Lattice  C,  Version  3,  you  should  in- 

high-resolution  clock.  It  keeps  track  of  the  previous  read- 

elude  the  switches  —  w  —cc  in  the  LC1  command  line. 

ing  so  that  each  time  it  is  called  it  accumulates  the  interval 

This  specifies  word  alignment  of  variables  and  nested 

just  terminated  toward  some  task.  Tele  mostly  measures 

comments.  If  you  use  another  compiler,  you  must  ensure 

execution  time  to  document  its  actions.  This  data  is  useful 

these  conditions  and  may  have  to  make  other  changes  as 

in  tuning  the  system  and  diagnosing  some  application 

well.  The  assembly-language  programs  contain  macros 

problems.  The  only  regular  use  made  of  it  is  in  rerunning 

(pseg,  endps,  dseg,  and  endds )  defined  with  the  Lattice 

Books  on  Operating  System  Design 

The  principles  and  practice  of  operating  system  design 

programming  language.  It's  not  a  tutorial,  but  enough  of 

cannot  be  communicated  in  one  magazine  article.  The 

the  language  is  covered  that  you'll  be  able  to  follow  the 

two  books  reviewed  here  should  be  on  the  desk  of  any 

code  in  the  remainder  of  the  book  (provided  that  you 

operating  system  builder.  Prentice-Hall  has  been  doing 

know  a  language  such  as  Pascal  pretty  well).  There’s 

great  things  with  computer-science  textbooks  during 

also  a  discussion  of  DOS  interfacing  conventions  and 

the  last  few  years,  publishing  a  series  of  texts  that  are 

how  to  use  the  DOS  I/O  system.  These  chapters  are  lucid 

both  well  written  and  practically  oriented.  All  too  often, 

and  cover  all  the  basics  of  DOS  interfacing.  They're  pret- 

computer-science  texts  are  neither.  They’re  incompre- 

ty  useful  in  their  own  right.  Because  the  main  thrust  of 

hensible  unless  you're  a  mathematician,  and  from  read- 

the  book  isn't  DOS  interfacing,  it's  good  that  the  author 

ing  the  book,  you'd  have  no  idea  that  the  subjects  cov- 

has  concentrated  all  the  DOS-specific  stuff  in  one  place. 

ered  had  any  practical  application.  In  fact,  the  only 

Systems  Software  Tools  starts  really  moving  in  Chap- 

thing  that's  difficult  with  many  computer-science  topics 

ter  4,  which  discusses  interrupt  processing  and  commu- 

is  understanding  the  books.  This  review  discusses  two 

nications  hardware.  In  this  and  the  next  chapter,  Big- 

welcome  exceptions  to  the  incomprehensibility  rule, 

gerstaff  develops  a  low-level,  interrupt-driven  console 

both  on  the  subject  of  operating  system  design. 

I/O  system,  discussing  such  topics  as  I/O  queues  and 
writing  interrupt  service  routines.  The  I/O  system  is  ex- 

Biggerstaff,  Ted  J.  Systems  Software  Tools.  Englewood 

ercised  with  a  terminal  emulator  program  that  works 

Cliffs,  N.J.:  Prentice-Hall,  1986. 

directly  with  the  hardware,  bypassing  DOS  entirely. 

Systems  Software  Tools  is  about  multitasking  operat- 

Chapter  6  is  a  discussion  of  concurrent  operating  sys- 

ing  systems.  Over  the  course  of  the  book,  Ted  Biggerstaff 

terns  in  general,  explaining  how  multitasking  works 

develops  a  small  multitasking  kernel  that  supports  up  to 

and  covering  most  of  the  essential  topics,  such  as  sched- 

four  concurrently  executing  processes,  each  running  in 

uling  strategies  and  interprocess  communications.  The 

its  own  window.  The  system  runs  on  an  IBM  PC,  but  the 

basic  data  structures,  such  as  task  control  blocks,  are 

book  is  not  really  targeted  at  IBM  programmers.  For  the 

developed  in  Chapter  7,  and  Chapter  8  discusses  process 

most  part,  DOS  is  used  as  an  I/O  system  rather  than  as  an 

management — how  to  get  two  programs  to  run  at  the 

operating  system.  Though  a  certain  amount  of  space  is 

same  time  and  how  to  transfer  control  from  one  to  the 

devoted  by  necessity  to  IBM-specific  topics,  it's  easy  to 

other.  Finally,,  the  last  chapter  ties  it  all  together  and 

port  both  the  concepts  and  the  code  to  a  different  envi- 

presents  a  viable  user  interface  built  around  a  simple 

ronment. 

windowing  system. 

The  book  breaks  up  its  subject  into  the  same  layers 

Biggerstaff's  operating  system,  though  it’s  pretty  nif- 

that  are  found  in  the  operating  system  itself,  organized 

ty,  does  have  a  few  flaws.  It  doesn't  do  low-level  disk  I/O 

from  the  machine  outward.  That  is,  the  earliest  chap- 

but  uses  DOS  system  calls  when  necessary.  This  ap- 

ters  talk  about  how  to  interface  to  the  actual  hardware, 

proach  is  pragmatic  because  a  primitive  disk  I/O  system 

and  the  subject  develops  gradually  to  the  user  interface, 

is  readily  available  for  most  machines,  but  it's  not  much 

presented  in  the  last  chapter. 

help  if  you  want  to  learn  how  to  put  a  disk  I/O  system 

Biggerstaff  starts  out  with  a  quick  summary  of  the  C 

together  from  scratch.  Because  all  the  code  is  written  in 
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compiler.  These  macros  define  the  proper  segment  struc¬ 
ture  for  linking  with  the  C  modules. 

Installation  is  accomplished  by  calling  function  t - init 

(Listing  One).  When  control  returns,  your  program  will 
be  executing  as  a  single  task,  and  others  may  be  executed 
at  the  same  time.  You  can  create  additional  tasks  by  call¬ 
ing  function  t_crf.  They  can  be  destroyed  by  calling  f_de/. 
See  Listing  One  for  the  calling  procedures. 

It’s  important  to  call  function  t _ term  before  returning 

to  MS-DOS.  If  you  don't,  an  interrupt  vector  will  be  left 
pointing  into  the  transient  program  area.  It  is  likely  that  a 
hard  crash  will  result  the  next  time  a  program  is  loaded 

unless  you  call  function  t _ term  to  restore  the  original 

vector. 

The  last  part  of  Listing  One  contains  a  main  function. 
This  tests  the  task  scheduler  by  creating  two  subtasks. 
Each  subtask  continually  increments  a  counter,  and  the 
program  displays  the  current  values  on  the  display. 
Though  main(  )  and  count( )  are  not  part  of  the  task  sched¬ 
uler,  they  do  serve  as  an  example  of  its  use. 

Conclusion 

Tele’s  task  scheduler  actively  participates  in  the  execu¬ 
tion  of  every  task,  but  it  is  almost  always  transparent. 
Most  tasks  can  assume  they  are  running  under  a  single¬ 
tasking  system.  They  can  take  advantage  of  services  asso¬ 
ciated  with  multitasking,  such  as  intertask  communica¬ 
tion,  without  significantly  altering  their  structure. 

An  expanded  version  of  this  code  is  available  from  me 
for  $100.  It's  available  as  a  programmer’s  tool  and  in¬ 
cludes  full  source  code  and  precompiled  libraries  for  all 
8086  memory  models,  more  detailed  documentation  than 
is  possible  here,  and  diagnostic  functions  useful  for  de¬ 
bugging  modifications. 

Further  information  is  available  from  Berry  Computer, 
P.O.  Box  966,  Jackson,  CA  95642;  (209)  223-0993. 

DDJ 

(Listings  begin  on  page  50.) 
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C,  the  system  response  times  are  slower  than  need  be, 
too.  I'm  not  sure  what  the  context-swap  time  is,  but  it’s 
probably  too  slow  for  many  real-time  applications.  On 
the  other  hand,  the  C  is  much  more  readable  than  the 
equivalent  assembler  would  be,  and  once  you  know  the 
theory,  translating  the  C  to  assembler  is  not  too  difficult. 
Finally,  the  system  presented  is  not  compatible  with 
anything.  This  isn't  necessarily  a  problem — for  exam¬ 
ple,  the  code  would  ROM  quite  nicely  if  you  want  to 
build  a  little  stand-alone  system  that  runs  on  a  single¬ 
board  computer. 

On  the  other  hand,  Systems  Software  Tools  is  a  very 
good  introduction  to  operating  system  design  in  general. 
The  system  presented  is  pretty  useful,  in  spite  of  its 
flaws,  and  you've  got  the  entire  source  code  if  you  want 
to  make  changes.  I  recommend  this  book  to  anyone 
who’s  already  a  reasonably  proficient  programmer  and 
wants  a  good  introduction  to  very-low-level  systems 
programming.  A  knowledge  of  C  and  a  little  assembler  is 
useful  but  not  essential.  The  book  is  readable  and  well 
organized,  and  all  the  subjects  covered  have  immediate 
application.  The  code  is  well  written  and  nicely  illus¬ 
trates  the  theoretical  concepts  presented  in  the  text. 
Moreover,  a  complete  program  is  presented  that  you 
could  type  into  your  machine  and  run  (you  can  also  get 
the  code  on  IBM-compatible  disk).  The  code  is  most  appli¬ 
cable  to  IBM  PC-based  machines,  but  the  operating  sys¬ 
tem  itself  is  portable  to  just  about  any  environment. 

Comer,  Douglas.  Operating  System  Design,  The  XINU  Ap¬ 
proach.  Englewood  Cliffs,  N.J.:  Prentice-Hall,  1984. 

Douglas  Comer’s  Operating  System  Design,  The  XINU 
Approach  is  a  good  complement  to  Biggerstaff’s  book. 
It's  more  advanced  and  covers  most  of  the  topics  that 
Biggerstaff  omits.  On  the  other  hand,  Comer  presents 
the  operating  system  only — he  offers  absolutely  no  utili¬ 
ties,  not  even  a  shell  or  user  interface. 

XINU,  a  stand-alone  operating  system  that  includes 
both  a  disk  I/O  system  and  file  server,  is  presented  in  its 

entirety.  As  with  Biggerstaff’s  book,  you  could  type  in 
the  code  and  have  a  complete  operating  system.  XINU 
stands  for  “Xinu  Is  Not  Unix,”  and  the  name  is  apt.  XINU  is 
a  scaled-down  Unix.  All  the  essential  parts  of  the  kernel 
are  there,  and  they  are  functionally  very  similar  to  their 
Unix  equivalents.  There’s  a  Unix-like  device-driver 
mechanism,  and  the  disk  is  organized  much  as  Unix  or¬ 
ganizes  its  own  disk.  The  code  presented  is  not  Unix 
source  code,  however;  it’s  Comer's  implementation  of 
that  code.  XINU  is  not  a  toy— it’s  a  complete  operating 
system  that  should  be  useful  in  virtually  any  application 
you  might  cook  up  (with  the  possible  exception  of  real¬ 
time  control  systems). 

XINU  was  originally  written  for  an  LSI  11/02,  but  it  con¬ 
tains  virtually  no  machine-specific  code  and  so  is  quite 
portable.  It  was  developed  on  a  larger  machine  and 
downloaded  to  the  target  machine.  There's  almost  no 
assembly  language  in  XINU;  the  overwhelming  majority 
of  the  code  is  in  C.  Its  disk  I/O  system  interfaces  to  a  Xebec 
S-1410  5V4-inch  Winchester  controller.  The  Xebec  pre¬ 
sents  a  pretty  standard  hardware  interface,  and  the  tech¬ 
niques  presented  should  port  to  most  other  controllers 
with  little  difficulty. 

Comer's  book  is  too  involved  to  dissect  chapter  by 
chapter.  Like  Biggerstaff,  he's  organized  the  chapters  in 
terms  of  functional  layers,  but  he  covers  many  more 
layers.  Comer  covers  the  basic  stuff  in  a  somewhat  cur¬ 
sory  manner  that  might  be  confusing  if  you’ve  never 
seen  any  of  the  material  before.  He  also  doesn’t  present 
as  much  theory  as  I'd  like,  limiting  himself  to  the  imple¬ 
mentation  of  a  specific  operating  system  rather  than  to 
discussing  operating  systems  in  general.  On  the  other 
hand,  XINU  is  a  powerful,  complete  operating  system 
and  it's  all  there  for  you  to  examine. 

Both  of  these  books  are  good — Biggerstaff 's  is  more  in¬ 
troductory  and  Comer's  more  complete — but  taken  to¬ 
gether  they  provide  a  good  introduction  to  operating  sys¬ 
tem  design.  I  recommend  them  highly. — Allen  Hoiuh 
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In  Search  of  a  Sine 


Iwas  recently  involved  in  a  pro¬ 
ject  for  which  I  needed  to  com¬ 
pute  sines  and  cosines  of  angles 
on  the  NS320xx  microprocessor  with 
a  floating-point  coprocessor.  I  looked 
through  several  years’  worth  of  the 
more  erudite  microcomputer  maga¬ 
zines  (including,  I  must  admit,  DDJ), 
some  mathematics  and  computer-sci¬ 
ence  textbooks,  and  the  source  code 
of  some  programs  that  included  sine 
computation  routines.  Despite  my 
searching,  though,  I  was  unable  to 
find  any  useful  algorithms  for  com¬ 
puting  mathematical  functions  in 
general  and  sines  in  particular.  I  was 
looking  for  an  algorithm  explained  in 
simple  terms,  along  with  a  reason¬ 
ably  well- commented  program  for 
carrying  it  out. 

I  did  find  several  potential  answers, 
but  for  various  reasons  none  of  them 
were  usable.  Some  of  them  were  too 
vague  or  mathematically  complicated 
for  me  to  understand  well  enough  to 
program  them.  Another  was  an  un¬ 
commented  program  for  the  8080  CPU 
in  which  the  sine  computation  algo¬ 
rithm  was  obscured  by  the  floating¬ 
point  arithmetic  routines.  One  was  an 
uncommented  program  written  in 
STOIC  (a  Forth-like,  stack-oriented  lan¬ 
guage)  that  was  impossible  to  figure 
out  well  enough  to  recode  it.  Another 
involved  exponentiation  of  e,  which 
was  computationally  impossible  for 
me. 

The  Taylor  Series 

I  finally  got  the  hints  I  needed  from 
the  Mathematical  Tables  section  of 
the  Handbook  of  Chemistry  and  Phys¬ 
ics  from  the  Chemical  Rubber  Com¬ 
pany.  There  I  found  a  Taylor  series 
formula  for  the  sine  of  an  angle.  The 
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series  can  be  expressed  as: 

s  =  a  —  (a3/3!)  +  (as/5!)  -  (a7/7!).  .  . 

where  a  is  the  angle  (in  radians),  s  is 
the  sine,  and  !  is  the  operator  for  fac¬ 
torials  (the  factorial  of  an  integer  n  is 
the  product  of  n  with  all  integers 
smaller  than  itself  and  greater  than 
1) .  Because  the  factorials  of  relatively 
small  numbers  can  be  calculated  easi¬ 
ly  (for  example,  4!  =  2X3X4  =  24), 
this  seemed  like  a  simple  enough  al¬ 
gorithm.  I  coded  it  up  in  BASIC  and 
tried  it  out  by  computing  the  sines  of 
several  angles,  starting  at  0°  or  radi¬ 
ans  and  comparing  the  results  with 
the  values  in  the  Mathematical  Ta¬ 
bles,  which  are  printed  to  five  deci¬ 
mal  places. 

It  became  obvious  that  it  was  com¬ 
putationally  faster  to  precompute  co¬ 
efficients  that  included  the  value  of  1 
divided  by  the  factorial  and  the  sign 
of  the  term.  Thus,  the  series  above 
became: 

s  =  a  -(0.166666  X  a3) 

+  (0.00833333  X  a5) 
-(0.0001984127  X  a7) .  .  . 

Working  with  this  test  program  re¬ 
vealed  that  the  number  of  terms 
needed  to  approach  the  accuracy  of 


the  five-place  tables  was  dependent 
on  the  size  of  the  angle.  For  angles  up 
to  90°,  five  terms  were  needed 
(through  a9  divided  by  9!).  This 
seemed  computationally  reasonable. 
But  to  get  up  to  120°,  seven  terms 
were  needed  (through  a13  divided  by 
13!).  At  this  point  I  realized  this  ap¬ 
proach  was  not  feasible  because  an 
algorithm  that  can’t  compute  the 
sines  of  large  angles  is  of  little  use. 

Quadrants  of  the  Circle 

The  way  out  of  this  dilemma  is  to 
consider  the  angles  in  quadrants  by 
thinking  of  the  sines  starting  at  0° 
and  progressing  around  the  circle.  As 
the  angle  increases  from  0°  to  90°, 
the  sines  go  up  from  0  to  +1.  From 
there  to  180°,  the  sines  return  to  0, 
pass  down  to  —1  at  270°,  and  then 
return  to  0  at  360° .  Thus  the  sine  of  an 
angle  between  90°  and  180°  is  equal 
to  the  sine  of  180°  minus  the  angle. 
Table  1,  page  31,  shows  a  summary  of 
all  this.  If  the  quadrant  is  determined, 
you  need  only  be  able  to  compute 
sines  from  0°  to  90°  efficiently. 

Doing  It  in  BASIC 

When  I  considered  the  quadrant  phe¬ 
nomenon,  the  uncommented  pro¬ 
grams  I  had  discovered  began  to 
make  more  sense.  One  was  particu¬ 
larly  interesting  because  it  seemed  to 
involve  only  four  coefficients.  It’s  in 
the  STOIC  floating-point-routine  file 
(CP/M  Users'  Group)  and  is  credited  to 
J.  Sachs,  1977.  Frankly,  I’m  not  sure 
I’ve  interpreted  Sachs'  approach  as 
intended,  but  the  following  does 
work. 

First,  scale  the  incoming  angle  to 
quadrants  such  that  an  angle  of  90° 
(1.570795  radians)  is  made  to  equal  1. 
If  you're  working  in  radians,  this 
means  dividing  by  1.570795;  if  you’re 
using  degrees,  divide  by  90.  Then,  if 


Dr.  Dobb 's  Journal,  December  1986 


30 

815 


the  scaled  angle  is  greater  than  4 
(360°),  subtract  4  from  it  and  repeat 
the  comparison  (and  subtraction)  un¬ 
til  it's  less  than  4.  Then  compare  with 
3  (270°)  and  1  (90°)  and  adjust  as  ap¬ 
propriate  based  on  Table  1. 

Compute  the  sine  approximation 
as: 

s  =  (Cl  X  a)  +  (C2  X  a3)  +  (C3  X  a5) 

+  (C4  X  a7) 

where  the  coefficients  are: 

Cl  =  1.570795 
C2  =  -0.645921 
C3  =  0.07948765 
C4  =  -0.004362469 

Remember  that  the  standard  Taylor 
series  approximation  has  the  input 
angle  expressed  in  radians;  these  are 
scaled  to  proportions  of  90°.  So  the 
coefficients  are  the  same  as  those  of 
the  standard  series  divided  into 
1.570795  and  raised  to  the  appropri¬ 
ate  power,  rather  than  1.  For  exam¬ 
ple,  C2  is  —1.570795  to  the  third 
power  divided  by  3!  (approximately). 

The  actual  computation,  in  BASIC,  is 
given  in  Table  2,  page  32.  Sines  calcu¬ 
lated  in  this  way  will  usually  agree 
with  the  table  values;  some  are  off  by 
1  on  the  fifth  place.  This  seems  like  a 
tolerable  error.  Runs  of  1,000  sines  of 
angles  from  0°  to  100°  in  0.1°  steps 
indicate  that  each  sine  takes  about  28 
milliseconds  to  compute  on  a  6-MHz 
NS16032  CPU. 

The  above  algorithm  can  be  used 
for  cosines  simply  by  doing  the  scal¬ 
ing  and  then  adding  1  (adding  90°,  ac¬ 
tually),  then  computing  the  sine. 
Compute  the  tangent  by  computing 
sine  and  cosine  and  then  dividing 
sine  by  cosine  (checking  for  zero  co¬ 
sine,  of  course.) 

Doing  It  in  Assembler 

The  NS320xx  assembly-language  rou¬ 
tine  (Table  3,  page  32)  is  about  210 
bytes  long,  including  the  coefficient 
constants  and  the  temporary  storage 
space.  Runs  calculating  10,000  func¬ 
tions  of  angles  from  0°  to  100°  in  0.1° 
steps  indicate  that  sines  and  cosines 
take  0.9  milliseconds  to  compute  and 
tangents  take  1.3  milliseconds  on  a  6- 
MHz  16032  CPU.  The  results,  rounded 
to  five  decimal  places,  generally 
agree  with  the  table  values;  occasion¬ 
ally  errors  of  1  in  the  fifth  place  occur 


with  sines  and  cosines.  Tangent  er¬ 
rors  are  slightly  greater;  sometimes 
errors  of  2  in  the  fifth  place  happen. 

The  binary  values  of  the  constants 
in  the  program  were  determined  by 
setting  BASIC  variables  equal  to  the 
desired  numbers  and  then  examin¬ 
ing  the  symbol  table  in  memory  with 
a  debugging  program. 

Reading  the  Listing 

The  motion  of  arguments  in  NS320xx 
instructions  is  from  left  to  right.  The 
CPU  and  the  coprocessor  each  have 
eight  registers,  numbered  R0  through 
R7.  The  instruction  MOVBF  1,R1,  for 


example,  takes  a  byte-sized  integer  1, 
converts  it  to  floating-point  format, 
and  leaves  it  in  coprocessor  register 
(CPR)  1.  DIVF  R2,R3  divides  the  oper¬ 
and  in  CPR  3  by  the  operand  in  CPR  2 
and  leaves  the  quotient  in  CPR  3. 

The  instruction  MOV.D 

0(R0 )[R6:D I,  SNTAB  may  need  some 
explanation.  The  meaning  may  not 
be  obvious  because  it  involves  an  ad- 


sine  of  0°  to  90°  =  sine  of  angle 
sine  of  90°  to  1 80°  =  sine  of  1 80°-angle 
sine  of  1 80°  to  270c  =  —sine  of  angle-1 80° 
sine  of  270°  to  360°  =  —sine  of  360°-angle 

Table  1:  Range  reduction  for  SIN(x) 
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dressing  mode  not  available  on  most 
microprocessors:  It  performs  a  32-bit 
move  from  the  address  in  RO  plus 
zero  indexed  by  (plus)  the  contents  of 
R6  multiplied  by  4  (the  length  of  the 
moved  data)  into  SNTAB.  Thus  H6  con¬ 
tains  the  entry  number  in  SNTAB — 
not  a  byte  displacement  but  rather  a 
double  word  displacement — and  RO 
contains  the  base  address  of  the  table. 

Another  possibly  confusing  instruc¬ 
tion  is  MULF  R5, SNTAB.  In  this  case, 
you  might  think  it  would  be  more  ef¬ 
ficient  to  move  the  coefficient  into  a 
register  rather  than  to  use  memory.  I 
had  previously  discovered,  however, 
that  the  use  of  CPU  registers  (address 


and/or  index)  and  a  coprocessor  regis¬ 
ter  in  the  same  instruction  often  leads 
to  chaos.  This  is  not  pointed  out  well 
in  National  Semiconductor's  docu¬ 
mentation. 

The  rest  of  the  program  is  fairly 
straightforward  and  should  be  direct¬ 


ly  applicable  to  any  CPU  that  is  compa¬ 
rable  to  the  NS320xx  in  power. 

DDJ 

Vote  for  your  favorite  feature/article. 
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APOW  =  AN  :  REM  AN  =  SCALED  ANGLE 
SINE  =  AN  X  Cl  :  REM  C'S  AS  ABOVE 
APOW  =  APOW  X  AN  :  REM  FIGURE  AN  ‘3 
APOW  =  APOW  X  AN 

SINE  =  SINE  +  APOW  X  C2  :  REM  ADD  TERM 
APOW  =  APOW  X  AN  :  REM  FIGURE  AN  *5 
APOW  =  APOW  X  AN 

SINE  =  SINE  +  APOW  X  C3  :  REM  ADD  TERM 
APOW  =  APOW  X  AN  :  REM  FIGURE  AN  "7 
APOW  =  APOW  X  AN 

SINE  =  SINE  +  APOW  X  C4  :  REM  ADD  TERM 


Table  2  :  Polynomial  approximation  in  BASIC 


Listing  One:  Computing  sine,  cosine,  and  tangent 

NS-320XX  assembler 

Sine,  cosine,  &  tangent  routines 


RadScI 

MOVF 

PI02.R2  ; Divide  by  pi/2  =  1 .57079635 

BR.S 

DoScal 

DegScI 

MOVBF 

90, R2 

Scale  for  degrees 

;  Scale  for  sin  cos,  tan 

DoScal 

DIVF 

R2,R3 

Now  90  degrees  =  1 .00 

DQuadr 

MOVBF 

4,R4 

4  =  360  degrees 

MOVBF 

1  ,R1 

1  =  90  degrees 

MOVBF 

2,R2 

2  =  180 

MOVBF 

3,R5 

3  =  270 

SnScll 

CMPF 

R3,R4 

Is  angle  >  360  degrees? 

BLT.S 

SnScl3 

go  if  less  than  360 

SUBF 

R4,R3 

else  subtract  360 

BR.S 

SnScll 

do  it  again 

SnScl3 

CMPF 

R3,R5 

>270? 

BLE.S 

SnScl5 

no,  go 

SUBF 

R4,R3 

make  minus:  ang=ang— 360 

SnScl5 

CMPF 

R3,R1 

>90? 

BLE.S 

ScnCI7 

SUBF 

R3,R2 

MOVF 

R2,R3 

ang=180-ang 

ScnCI7 

RET 

scaled  value  in  R3 

ACos 

MOVBF 

90, R2 

angle,  degrees  in  R3 

DIVF 

R2,R3 

divide  by  90 

MOVBF 

1  ,R2 

ADDF 

R2,R3 

make  angle  plus  90 

BSR 

DQuadr 

figure  quadrant 

BR.S 

DoSin 

go  do  sine,  return  from  it 

ASin 

BSR 

DegScI 

Angle  in  degrees 

Fall  through  to. . . 

;  Compute  Sine(x) 

;  Sine  = 

0  +  1 ,570795*X 

-  0.645921  *X'3 

; 

+  0.07946765*X"5  -  0.004362469*X'7 

DoSin 

ADDR 

SNTAB.R0 

get  address  of  table 

MOVQ.D 

4,R6 

init  R6 

;  Enter  with  table  addrs  in  RO,  #  terms  in  R6 

MOVF 

R3,R1 

save  angle  in  R1 

MOVF 

R1.R5 

;and  in  R5 

MOVBF 

0,R3 

;sine  starts  at  zero 

SinLp 

MOV.D 

0(R0)[R6:D], SNTAB  ;get  multiplier 

MULF 

R5,  SNTAB 

;mult  angle 

ADDF 

SNTAB, R3 

;add  to  sine 

MULF 

R1.R5 

;angle  “  n+2 

MULF 

R1.R5 

ACB.BS 

—  1  ,R6,SinLp;do  again  till  done 

RET 

;  Compute  Tan(x) 

;  Tan(x) 

Sin(x)/Cos(x) 

Alan 

MOVBF 

90, R2 

;scale  for  degrees 

DIVF 

R2.R3 

MOVF 

R3, SNTEMP 

;save  scaled  angle 

BSR 

DQuadr 

ifigure  quadrant 

BSR 

DoSin 

;  compute  sin 

MOVF 

R3.TOS 

;save  sine  on  stack 

MOVBF 

1,R3 

ADDFF 

SNTEMP, R3 

;  add  for  cosine 

BSR 

DQuadr 

ifigure  quadrant 

BSR 

DoSin 

;compute  cosine 

MOVF 

R3,R2 

;move  cosine  to  R2 

MOVF 

TOS.R3 

irecover  sine 

;  R0  now 

=  0 

CMPF 

R0,R2 

;have  zero? 

BNE.S 

ATanDv 

;no,  divide 

MOVF 

FNSM.R3 

;else  use  big  number 

RET 

ATanDv 

DIVF 

R2,R3 

;Tan  =  Sin/Cos 

RET 

FNSM 

BYTE 

0,0C0h,0DAh,45h  ;7000 

PI02 

BYTE 

0DBh,0Fh,0C9h,3Fh  ;pi/2  =  1.57079635 

SNTEMP 

BLK.D 

1 

; temporary  storage 

SNTAB 

BLK.D 

1 

;temp 

;  these  are  in  reverse  order  of  use 

BYTE  0Bh,0F3h,8Eh,0BBh  ;-0.004362469 

BYTE  6Ch,0CAh,OA2h,O3Dh  ;0.07948765 

BYTE  14h,5Bh,25h,0BFh  ; -0.645921 

BYTE  0D0h,0Fh,0C9h,3Fh  ;  1.570795 


Table  3:  Computing  TAN(x)  from  SlN(x)/COS(x) 
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ARTICLES 


Echelon’s  Z-Syste 


Richard  Conn's  public-do- 
main  ZCPR3  is  an  enhanced 
substitute  for  CP/M  2.2's  con¬ 
sole  command  processor  (CCP).  Eche¬ 
lon,  a  software  firm  headed  by  pub¬ 
lic-domain  pioneer  Frank  Gaude,  has 
combined  ZCPR3  with  Dennis 
Wright’s  ZRDOS,  a  Z80-optimized  BDOS 
replacement,  to  form  the  joint  nucle¬ 
us  of  an  8-bit  operating  system  sup¬ 
ported  by  a  cluster  of  customized 
tools,  utilities,  libraries,  and  hard¬ 
copy  manuals.  The  term  Z-System  re¬ 
fers  specifically  to  the  operating  sys¬ 
tem  itself  (ZCPR3  combined  with 
ZRDOS)  and  generically  to  Echelon's 
entire  line  of  ZCPR3  utilities  and  soft¬ 
ware  tools. 

In  this  article,  I'll  evaluate  the 
ZCPR3-ZRDOS  nucleus  of  Z-System 
from  the  viewpoint  of  an  advanced 
programmer,  stressing  its  program 
design  and  structure. 

Versions  of  Z-System 

Echelon  sells  Z-System  in  two  basic 
forms:  Joseph  Wright's  auto-install 
version,  Z-Com,  which  uses  a  host  CP/ 
M  2.2  system  to  overlay  the  CCP  and 
BDOS  with  ZCPR3  and  ZRDOS  and  then 
expands  the  host  CBIOS  to  make  room 
for  memory-resident  utilities  and 
buffers;  and  a  manual-install  or 
"hacker”  version  consisting  of  the 
source  codes  for  all  system  compo¬ 
nents  and  utilities  except  the  optional 
ZRDOS.  The  SIG/M  public-domain  ver¬ 
sion  omits  the  proprietary  ZRDOS  but 
comes  with  Conn's  SYSLIB3  and  deriv¬ 
ative  Z3LIB  and  VLIB  libraries  of  Z80 
routines  used  in  the  assembly  of  Z- 
System  components. 

Z-Com  ($119)  is  the  better  choice  for 
turnkey  systems,  inexperienced  us¬ 
ers,  or  anyone  who  wants  to  install  a 


Morris  Simon,  118  Brookhaven,  Tus¬ 
caloosa,  AL  35405 


by  Morris  Simon 


Z-System  is  an  8-bit 
operating  system  for 
Z80  systems. 


complete  Z-System  in  a  few  minutes. 
Advanced  programmers  who  will  be 
doing  major  customizations  to  Z-Sys¬ 
tem  segments  have  both  the  develop¬ 
ment  tools  and  the  assembly-lan¬ 
guage  skills  needed  to  install  the 
more  expensive  but  flexible  manual 
version  ($182.50  with  ZRDOS,  if  pur¬ 
chased  piecemeal  from  Echelon). 

The  major  difference  between  the 
two  versions  is  that  Z-Com  requires 
the  presence  of  CP/M  2.2  to  boot  it  as  a 
transient  command  file.  In  contrast, 
the  manual  installation  procedure 
completely  replaces  the  CP/M  CCP 
and  BDOS  on  the  system  tracks  with 
ZCPR3  and  ZRDOS  (if  present)  to  pro¬ 
duce  a  bootable  Z-System  disk.  In  ad¬ 
dition  to  Z-Com’s  use  of  CP/M  to  boot 
itself,  the  two  versions  differ  in  that 
Z-Com’s  system  components  are  pre¬ 
selected  and  contained  in  a  set  of  ob¬ 
ject-code  files.  With  Z-Com,  major 
changes  and  additions  can  be  tricky 
and  may  require  some  disassembly 
and  patching.  Z-Nodes,  a  remote  bul¬ 
letin-board  network  of  international 
Z-System  users,  distributes  useful 
public-domain  patch  files  to  make 
this  job  a  little  easier. 

The  manual-install  version  comes 
with  the  source  code  for  all  major 
system  components  (except  the  op¬ 
tional  proprietary  ZRDOS)  so  that  us¬ 
ers  can  modify  any  feature  of  ZCPR3 
separately  to  suit  their  needs  or  hard¬ 


ware  requirements.  Assembly  of  the 
altered  code  requires  a  good  relocata¬ 
ble  macro  assembler,  preferably  one 
that  can  assemble  Zilog  mnemonics, 
and  standard  system  alteration  and 
debugging  utilities  such  as  MOVCPM, 
SYSGEN,  and  DDT  or  their  equivalents. 
Modification  and  reassembly  of  the 
individual  utilities  may  also  require 
access  to  the  appropriate  Z-System 
source-code  libraries — SYSLIB3,  Z3LIB, 
and  VLIB. 

Components 

Each  version  uses  its  own  installation 
procedures  and  design  principles  to 
achieve  the  same  functional  result.  In 
either  case,  the  user’s  CBIOS  is  modi¬ 
fied  and  extended  by  several  optional 
memory-resident  system  segments — 
customized  packages  of  Z80  code  and 
buffer  areas.  A  complete  Z-System 
includes 

•  ZCPR3,  the  console  command 
processor 

•  either  BDOS  or  ZRDOS 

•  a  modified  CBIOS 

•  a  revised  page  zero  with  jump  ad¬ 
dresses  to  the  new  CBIOS  and  BDOS  or 
ZRDOS  and  new  buffers  (in  the  man¬ 
ual  version) 

The  modified  CBIOS  contains 

•  the  original  BIOS  codes 

•  an  initializing  routine  that  sets  Z- 
System  equates  and  addresses 

•  the  Resident  Command  Package 
(RCP)  (a  cluster  of  memory-resident 
utilities) 

•  the  Input/Output  Package  (IOP) 
(space  reserved  for  customized  I/O 
drivers) 

•the  Flow  Command  Package  (FCP) 
(equates  used  by  system  utilities  that 
permit  conditional  logic  and  flow 
states) 
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•  the  Environment  Descriptor  (Z3ENV) 
(system  equates  used  by  utilities) 

•  buffers,  stacks,  and  equates  (re¬ 
served  spaces  for  shell  operations, 
messages  shared  by  several  utilities, 
named  directories,  RAM  registers, 
and  assorted  byte  or  word  locations 
such  as  the  "wheel”  security  byte) 

Figures  1  and  2,  below,  illustrate 
memory-map  differences  for  the  two 
versions  using  sample  addresses 
from  a  Tele  Video  803  64K  RAM.  Seg¬ 
ment  sizes  and  locations  will  vary 
with  other  systems. 

The  auto-install  version  makes  Z- 
System  transportable  to  a  wide  vari¬ 
ety  of  memory  structures  because  it 
involves  less  alteration  of  the  user’s 
CBIOS  than  the  manual  version  does. 
With  Z-Com,  the  entire  Z-System 
package  is  loaded  in  front  of  the  origi¬ 
nal  CBIOS,  extending  it  and  overwrit¬ 
ing  both  the  CP/M  BDOS  and  CCP.  A 
new  jump  table  at  the  first  RAM  page 
of  the  relocated  CBIOS  intercepts  sys¬ 
tem  calls  and  redirects  them  to  Z-Sys- 
tem  segments  such  as  the  Input/Out¬ 


put  Package  or  to  the  original  CBIOS 
jump  locations.  The  system  segments 
and  buffers  are  loaded  between  the 
new  and  old  CBIOS  jump  tables.  ZRDOS 
and  the  ZCPR3  command  processor 
reside  below  this  extended  CBIOS,  at 
somewhat  lower  addresses  than  CP/ 
M's  CCP  and  BDOS  did  in  the  host 
system. 

When  I  first  started  using  Z-System, 
I  was  disturbed  by  this  loss  of  vital 
RAM  space,  as  any  serious  8-bit  user 
should  be.  I  soon  realized,  however, 
that  most  CP/M  2.2  programs  are 
written  so  tightly  that  they  seldom 
require  a  TPA  of  more  than  40K  or  so. 
This  is  a  tribute  to  8080  and  Z80  as¬ 
sembly-language  programmers  who 
can  never  afford  the  16-bit  luxury  of 
bulky  and  redundant  code — there's 
just  no  room  for  it.  Even  when  CP/M 
programs  overwrite  the  command 
processor,  they  often  are  just  using 
the  BDOS  (or  ZRDOS)  address  stored  at 
location  0006H  in  page  zero  as  a  con¬ 
venient  way  to  set  up  a  program 
stack  that  will  work  on  any  CP/M  sys¬ 
tem.  The  TPA  between  the  end  of  a 


program  and  the  end  of  its  stack  is 
often  an  empty  space  of  more  than 
20K,  whereas  the  Z-System  exten¬ 
sions  require  only  around  6K. 

The  manual-install  version  shown 
in  Figure  1  saves  a  little  more  RAM 
space  (512  bytes)  by  moving  the  CBIOS 
downward,  placing  the  external 
path  buffer  and  wheel  byte  in  page 
zero  and  relocating  the  original  BIOS 
jump  table.  If  ZRDOS  is  installed,  it  re¬ 
sides  directly  beneath  the  original 
BIOS  jump  table,  just  as  the  BDOS  does 
in  CP/M  systems.  All  ZCPR3  external 
segments  and  buffers  reside  above 
the  original  CBIOS,  except  for  an  ini¬ 
tializing  routine  poked  into  the  used 
cold-boot  loader  space. 

ZCPR3  and  Its  Extensions 

The  heart  of  either  Z-System  version 
is  Conn's  ZCPR3  command  processor 
with  its  internal  enhancements  and 
CBIOS  extensions.  ZCPR3  users  have 
many  optional  and  enhanced  inter¬ 
nal  commands,  such  as  SAVE,  GO, 
JUMP,  TYPE,  and  others,  that  are 
unavailable  in  CP/M  2.2.  Multiple  and 


FFFF 

FE00 

FDD0 

FD00 

FC00 

FBD0 

FB80 

FB00 

FA00 

F800 

F200 

EAOO 

D600 

C800 

cooo 

0100 

original  ROM  and  BIOS  buffers 

ZCPR3  external  stack 

ZCPR3  command-line  buffer 

named  directory  buffer 

external  FCB 

message  buffers 

shell  stack 

environment  descriptors 
(Z3ENV  and  TCAP) 

Flow  Command  Packages 

Input/Output  Packages 

Resident  Command  Packages 

original  BIOS  with  ZCPR3 
loader  in  cold-boot  routine 

ZRDOS  or  CP/M  BDOS 

ZCPR3  command  processor 

48K  TPA 

(48,896  bytes  free) 

page  zero  with  wheel  byte, 

New  jump  addresses,  and 
external  path  buffer 

Hexadecimal  addresses  are  system-dependent  and  optional. 

This  example  is  based  upon  a  composite  of  Conn’s  model 
in  ZCPR3:  The  Manual  and  my  own  Z-System  segments 
within  a  TeieVideo  CBIOS. 

Figure  1:  A  complete  manual-install  version 
of  Z-System 


FFFF 

FE00 

EAOO 

E400 

E200 

DA00 

D9D0 

D900 

D800 

D7FF 

D7F4 

D7D0 

D780 

D700 

D600 

D400 

C600 

BE00 


0100 


original  ROM  and  BIOS  buffers 

original  BIOS 

Input/Output  Packages 

Flow  Command  Packages 

Resident  Command  Packages 

ZCPR3  external  stack 

ZCPR3  command-line  buffer 

environment  descriptors 
(Z3ENV  and  TCAP) 

wheel  byte 

command  search  path 

external  FCB 

message  buffers 

shell  stack 

named  directory  buffer 

Z-Com  initializer/jump  table 

ZRDOS 

ZCPR3  command  processor 

48  K  TPA 

(48,384  bytes  free) 

modified  page  zero  with  new 
buffer  areas  and  jump  addresses 

Flexadecimal  addresses  are  system-dependent  and  optional. 
This  example  is  based  upon  one  of  my  own  system  images 
using  a  64K  Tele  Video  803  CBIOS. 


Figure  2:  A  complete  auto-install  (Z-Com) 
version  of  Z-System 
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;  [“Z3-Dot-Com”  is  the  auto-instail  version  of  ZCPR3 
;  alone  while  “Z-Com”  includes  ZRDOS  as  well] 

;  Z3-Dot-Com  and  Z-Com 
;  Copyright  1 985  by  Joseph  W.  Wright 

Z3ENV  SET  0DC00H 

;  No  other  equates  should  be  changed! 

;  [This  is  the  address  of  the  environment 
;  descriptor.  Addresses  and  segment  sizes  are  more 
;  critical  in  Z-Com  than  in  the  manual-install 
;  version.  Note  that  all  other  addresses  are 
;  offset  from  the  environment  descriptor.] 


;  General  equates 

false 

equ 

0 

true 

equ 

not  false 

base 

equ 

0 

i8080 

equ 

false 

[for  8080  systems] 

expath 

equ 

z3env-0ch 

[command  path] 

expaths 

equ 

5 

[5  2-byte  elements] 

z3whl 

equ 

z3env-1 

[wheel  byte  address] 

rep 

equ 

z3env+200h 

[address  of  Resident 

reps 

equ 

16 

Command  Package  and 
1 6-block  size] 

iop 

equ 

z3env+0c00h 

[address  of  Input/ 

iops 

equ 

12 

Output  Package  and 

1 2-block  size] 

[code  continues  to 

define  all  segments] 


Table  1:  Excerpt  from  Z-COM  version  of  Z3BASE.LIB.  Comments  in  square 
brackets  are  mine. 


extended  command  processing,  in¬ 
stantaneous  user  area  or  directory  se¬ 
lection,  command  path  assignment, 
and  wheel  access  control  are  some  of 
the  internal  ZCPR3  options  that  are  of¬ 
ten  found  only  on  larger  systems.  By 
skillful  assembly-language  program¬ 
ming,  Conn  has  squeezed  these  and 
other  features  into  the  original  2K 
CCP  space  in  order  to  maintain  com¬ 
patibility  with  earlier  CP/M  programs 
for  which  the  CCP  size  is  critical.  Al¬ 
though  these  enhancements  in  the 
body  of  the  command  processor  are 
definitely  valuable,  ZCPR3's  unique 
advantages  lie  in  the  external  Z-Sys- 
tem  segments. 

ZCPR3’s  modular  components  re¬ 
side  in  high  memory  for  fast  access, 
increasing  the  power  and  flexibility 
of  the  command  processor  beyond 
that  of  any  other  8-bit  operating  sys¬ 
tem  and  for  some  operations  of  larger 
ones  as  well.  These  fast  resident  utili¬ 
ties  actually  permit  users  of  tiny  8-bit, 
64K  systems  to  enjoy  the  speed  and 
efficiency  of  a  RAM  disk  for  many  rou¬ 
tine  tasks. 

The  modular  design  of  the  ZCPR3 


CBIOS  extensions  permits  users  to 
modify  any  resident  utilities,  named 
directory  structures,  flow  control 
states,  input/output  drivers,  com¬ 
mand  paths,  and  most  other  Z-System 
features  whenever  they  choose  to 
change  or  add  to  them. 

With  the  manual-install  version, 
you  can  perform  massive  alterations 
upon  any  of  these  features  simply  by 
editing  and  reassembling  one  or 
more  well-documented  source  files 
into  a  variety  of  relocatable  object- 
code  segments.  With  the  Z-Com  ver¬ 
sion,  you  may  have  to  disassemble 
some  object  code  in  order  to  tailor  the 
system  segments  to  suit  your  needs. 
When  either  object-code  package  is 
ready,  you  can  use  a  fast  loader  utili¬ 
ty  (LDR.COM)  to  reinstall  different  sys¬ 
tem  segments  instantly  to  fit  chang¬ 
ing  jobs. 

You  might,  for  example,  wish  to 
use  separate  resident  command 
packages  (RCPs)  for  word  processing 
and  assembly-language  program¬ 
ming,  with  different  resident  utilities 
in  each  one  to  reduce  disk  access 
time.  1  have  several  manuscript-edit¬ 


ing  aids  in  a  word-processing  RCP  and  ; 
a  fine  memory  editor  (MU3)  in  anoth¬ 
er  RCP  I  use  for  programming.  An 
alias  batch  command  reconfigures 
|  my  CBIOS  by  loading  one  of  these  spe- 
j  cialized  command  packages  auto¬ 
matically  each  time  I  enter  its  respec¬ 
tive  directory  area.  Because  resident 
command  packages  always  reside  in 
!  RAM,  1  can  run  any  of  these  utilities  at 
high  speed  without  modifying  any 
TP  A  code. 

Z-System’s  named  directories  are 
more  convenient  and  flexible  than 
the  Unix-style  MS-DOS  directories  I  use 
in  an  IBM-equipped  computer  labora¬ 
tory.  ZCPR3's  directories  are  based 
upon  CP/M's  user  areas,  yielding  up 
to  32  possible  directories  or  subdirec¬ 
tories  with  optional  passwords  on 
any  one  “level.”  You  need  to  expand 
the  default  named  directory  buffer  if 
you  plan  to  use  more  than  14  directo¬ 
ry  names  at  one  time. 

All  ZCPR3  directories  exist  on  the 
same  level  to  the  operating  system, 
but  you  can  create  a  Unix-style  hierar¬ 
chical  effect  by  overlaying  previous 
levels  automatically  with  the  change 
directory  (CD)  and  alias  commands. 
This  causes  a  new  named  directory 
system  to  be  loaded  into  the  CBIOS  and 
reorganizes  all  the  files  contained  in 
the  new  user  areas  you  tell  the  system 
to  "see.”  The  result  can  be  a  virtual 
hierarchy  of  dynamic  subdirectories, 
or  a  flat  passworded  subdirectory  lay¬ 
er,  or  whatever  you  wish  it  to  be.  As 
with  the  other  modular  extensions  of 
j  the  command  processor,  the  package 
j  of  directory  names  can  be  changed  by 
^  simple  editing,  and  a  special  make  di- 
rectory  (MKDIR)  utility  is  provided  just 
for  that  purpose.  I 

The  buffers  and  locations  used  by  ! 
the  various  components  of  Z-System 
must  be  initialized  at  the  time  ZCPR3 
and  ZRDOS  (if  present)  are  loaded.  In 
the  manual  version,  a  configuration 
routine  resides  in  the  CBIOS  cold-boot 
loader  area  from  which  it  assigns  all 
ZCPR3  internal  and  external  options 
as  well  as  external  buffers  and  other 
CBIOS  locations.  Changing  parame¬ 
ters,  addresses,  or  buffer  sizes  is  a 
simple  matter  of  editing  two  header 
files,  Z3HDR.LIB  and  Z3BASE.LIB,  and 
making  whatever  secondary 
changes  are  required  elsewhere,  es¬ 
pecially  when  you  have  changed  the  j 
size  of  a  segment  buffer  or  two. 

In  the  manual-install  version, 
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;  This  is  the  address  of  the  customized  Z3ENV 

Z3ENV  SET  OFEOOH 

;  These  are  external  macros  found  in  Conn’s  SYSLIB 

;  and  Z3UB  libraries 

EXT  Z3INIT,GETNDR,GETWHL,C0DEND 

EXT  COUT.CRLF, PRINT, PADC 

;  This  conditional  assembly  statement  tests  the 
;  code  for  the  address  of  an  external  Z3ENV. 

IF  Z3ENV  ne  0 

External  z3env  found. 

JP  START 

Go  to  first  instruction. 

DB  'Z3ENV 

Label  indicating  that 
this  is  a  ZCPR3  utility. 

DB  1 

Code  for  external  Z3ENV. 

Z3EADR: 

DW  Z3ENV 

Address  of  external 

START: 

Z3ENV  descriptor. 

LD  HL,(Z3EADR) 

Point  to  external 
descriptor. 

ELSE 

;  Conditional  assembly  still  functioning.  If 
;  external  Z3ENV  is  not  present,  one  must  be 
;  installed  in  utility  itself  by  calling  macros 

;  from  z3base.lib  and  sysenv.lib  during  assembly. 

MACLIB  Z3BASE.LIB 

Note  extended 

MACLIB  SYSENV.LIB 

Intel  format. 

Z3EADR: 

JP  START 

sysenv  is  a  macro  used 

SYSENV 

to  equip  utility  with 
internal  descriptor. 

START: 

LD  HL.Z3EADR 

Point  to  internal 
descriptor. 

ENDIF 

End  of  ELSE  condition. 

PUSH  HL 

Move  z3env  pointer  to 

POP  IX 

Index  Register  X. 

CALL  Z3INIT 

Initializes  Z3ENV. 

LD  HL,0 

Code  continues. 

Table  2:  Excerpt  from  FINDF24.Z80,  a  fast  find  utility  written  by  Richard 
Conn.  All  comments  are  mine. 


Z3HDR.LIB  contains  users'  options  for 
most  ZCPR3  features  and  commands 
and  Z3BASE.LIB  defines  the  locations 
of  external  segments.  In  Z-Com's  ver¬ 
sion  of  Z3BASE.LIB  (Table  1,  above), 
these  addresses  are  all  defined  as  off¬ 
sets  from  a  single  environment  de¬ 
scriptor  location  determined  by  the 
installation  process.  You  can  still 
poke  or  patch  changes  in  the  object 
code  of  Z-Com  components  if  you 
know  what  you're  doing. 

When  assembled,  the  Z3BASE.LIB 
header  file  becomes  the  first  half  of 
ZCPR3’s  environment  descriptor, 
Z3ENV,  which  gives  Z-System  a  major 
transportability  advantage  over 
other  8-bit  operating  systems.  The  de- 
j  scriptor  is  merely  a  duplex  header 
{  file  containing  default  or  user-de¬ 
fined  information  such  as  the  ad¬ 
dresses  of  all  Z-System  segments,  CRT 
j  and  printer  values,  CPU  speed,  cursor 
(  and  highlighting  controls,  and  many 
j  other  system-specific  details. 

All  Z-System  utilities  use  the  de- 
I  vantage  of  special  terminal  features 
I  such  as  graphics  characters  and  cur- 
j  sor  positioning  codes.  Neither  soft- 
j  ware  nor  hardware  differences  will 
interfere  with  transportability  of  Z- 
System  programs  as  long  as  the 
Z3ENV  pointer  is  properly  installed.  A 
special  utility,  Z3INS.COM,  can  install 
or  reinstall  the  Z3ENV  address  quickly 
in  any  object-code  files  written  for  Z- 
System  use. 

ZCPR3's  flow  control  and  multiple 
command  features  are  essential  com¬ 
ponents  of  shells  and  interactive 
;  menus.  Both  permit  users  to  con¬ 
struct  long  conditional  arguments 
that  are  useful  in  the  automation  of 
complex  tasks.  ZEX  (an  extended  com¬ 
mand  processor),  VFILER  (a  file-sweep 
scriptor 's  data  to  customize  their  op¬ 
eration  and  to  communicate  with  the 
system  segments.  In  order  to  install  a 
new  utility  inside  your  operating  sys¬ 
tem,  you  merely  place  a  pointer  to 
Z3ENV  in  the  utility's  source  code  and 
refer  all  system-dependent  routines 
to  it.  Table  2,  below,  illustrates  this 
use  of  the  environment  descriptor  in 
the  source  code  for  a  fast  file-find 
utility. 

Calls  to  the  Terminal  Capabilities 
(TCAP)  half  of  the  environment  de¬ 
scriptor  permit  the  immediate  trans¬ 
portability  of  any  software  that  uses 
terminal-specific  features  such  as 
video  graphics,  windowing,  and  pull¬ 


down  menus.  Users  can  customize 
their  programs  instantly  to  take  ad- 
utility  with  macro  options),  and 
VMENU  (an  interactive  shell  of  com¬ 
plex  user  options)  are  just  a  few  of  the 
many  Z-System  utilities  that  rely  on 
flow  control  and  multiple  command 
processing  for  their  power. 

One  of  CP/M’s  strengths  is  its  input/ 
output  redirection  capability  that 
uses  the  STAT  command  to  revise 
the  I/O  byte  at  location  0003H.  Z-Sys- 
tem  permits  you  to  retain  the  CP/M 
device-assignment  procedures  or  to 
use  its  own  more  efficient  design 
based  on  the  I/O  drivers  loaded  as  In¬ 
put/Output  Packages  (lOPs).  The  Z- 
System  approach  to  device  assign¬ 
ment  places  any  number  of  device 


drivers  into  memory,  but  only  when 
!  needed.  In  contrast,  the  CP/M  method 
restricts  the  number  and  types  of 
1  drivers  and  requires  them  to  be  per- 
|  manent  residents  of  scarce  CBIOS 
[  space,  waiting  to  be  needed.  Like  the 
other  system  segments,  the  IOP  struc¬ 
ture  is  supported  by  a  variety  of  Z- 
System  utilities  such  as  DEVICE  and 
RECORD,  which  select  and  activate  or 
deactivate  particular  drivers.  Users 
with  elaborate  hardware  configura¬ 
tions  can  benefit  most  from  the  op¬ 
tional  ZCPR3  IOP  design. 

Z-System ’s  Languages 

One  feature  of  Z-System  that  has 
caused  me  some  inconvenience  with 
both  ZCPR3  and  its  predecessor, 
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Excerpt  from  ZRDOS  CHECKSUM  routine.  Code  produces  11  bytes  and  60  or  66  clock  cycles. 

CHECKSUM: 

LD  HL.(DREC) 

LD  DE.(CHKSIZ) 

XOR  A 

SBC  HL,DE 

RET  NC 

dir  record  into  HL 
chksum  vector  to  DE 
clear  A 

compare  by  subtract 
result  placed  in  HL 
ret  from  CHECKSUM 
if  DREC  >  CHKSIZ 
else  continue 

Equivalent  excerpt  from  CP/M  2.2  CHECKSUM  routine.  Code  produces  18  bytes  and  92  or  98 
clock  cycles. 

CHECKSUM: 

LHLD  DREC 

XCHG 

LHLD  CHKSIZ 

CALL  SUBDH  - 
RNC 

Dir  record  into  HL. 

Shift  to  DE. 

Checksum  vector  to  HL. 

Compare  by  subtract. 

Return  from  CHECKSUM  if 

DREC  >  CHKSIZ  else 
continue  with  CHECKSUM. 

SUBDH; 

MOV  A,E 

SUB  L 

MOV  L,A 

MOV  A,D 

SBB  H 

MOV  H,A 

RET  ;  Return  from  SUBDH. 

Must  move  both  bytes 
of  directory  record  into 
register  A  for  double 
register  subtract  with 
carry  flag  set — diff 
is  loaded  in  HL. 

Table  3:  ZRDOS-BDOS  code  comparisons.  Comments  and  labels  are  from 
my  disassembly. 


Excerpt  from  CP/M  2.2  BDOS  SELECTDISK  routine.  Code  produces  22  bytes  and  98  or  102  clock 

cycles. 

MOVE:  ;  Necessary  in  Intel. 

INR  C 

Set  up  for  loop. 

MOVEO: 

DEC  C 

Get  zero  if  there. 

RZ 

End  loop  if  empty. 

LDAX  D 

Source  byte  to  A. 

MOV  M,A 

A  to  destination  DPB. 

INX  D 

Next  source  byte. 

INX  H 

Next  destination  byte. 

JMP  MOVEO 

Loop  until  C=0. 

SELECTDISK: 

This  subroutine  fills 
the  16-byte  disk 
parameter  block. 

LHLD  DPBADDR 

HL  points  to  source. 

XCHG 

Switch  source  to  DE. 

LXI  H.SECTPT 

HL=destination  DPB. 

MVI  C.DPBLIST 

C=sizeof  DPB. 

CALL  MOVE 

Move  it. 

SELECTDISK  continues. 

Equivalent  excerpt  from  ZRDOS  SELECTDISK  routine.  Code  produces  11  bytes  and  52  or  57 

clock  cycles. 

SELECTDISK: 

LD  HL, (DPBADDR) 

Source  to  HL. 

LD  DE.SECTPT 

Destination  to  DE. 

LD  BC.0FH 

DPB  size =16  bytes. 

LDIR 

Move  until  done. 

Resume  SELECTDISK. 

Table  4:  ZRDOS-BDOS  code  comparisons 


ZCPR2,  is  the  choice  of  mnemonics 
used  in  its  source  codes.  To  develop 
ZCPR3,  Conn  and  the  other  designers 
of  Z-System  used  Z80  assembly-lan¬ 
guage  macro  libraries,  such  as  SYS- 
LIB3,  Z3LIB,  and  VLIB,  which  were 
written  originally  in  extended  Intel 
macros  rather  than  “pure’'  Zilog 
mnemonics.  Presumably,  they  want¬ 
ed  to  make  their  source  code  accessi¬ 
ble  to  the  widest  range  of  macro  as¬ 
semblers,  including  Digital 
Research's  MAC  and  RMAC  packages. 

Until  the  past  year,  the  source  pro¬ 
grams  for  most  Z-System  utilities,  as 
well  as  the  libraries  themselves, 
were  written  only  in  extended  Intel, 
with  its  bulky  8080  macros  substitut¬ 
ing  for  more  compact  and  readable 
Z80  instructions.  I  prefer  to  code  pro¬ 
grams  in  Zilog  mnemonics,  and  it  is 
sometimes  difficult  to  translate  ex¬ 
tended  Intel  into  Zilog,  particularly 
when  the  Intel  macros  have  the  same 
names  as  Zilog  instructions.  My  solu¬ 
tion  has  been  to  have  several  differ¬ 
ent  assemblers  in  different  named  di¬ 
rectories  on  the  same  disk.  An 
interactive  menu  switches  back  and 
forth  as  needed. 

Echelon  is  correcting  this  problem  j 
(if  it  is  a  problem  for  you)  in  its  later 
software  versions  and  now  supplies 
source  code  in  Zilog  mnemonics  as 
well  as  extended  Intel.  Zilog  mne¬ 
monics  are  becoming  more  common 
in  Echelon’s  Z-Tools  collection  of  ad¬ 
vanced  system  development  soft¬ 
ware,  much  of  which  is  now  being 
sold  with  Zilog  and  HD64180  mne¬ 
monic  patches  to  permit  instant  con¬ 
versions  and  translations.  Judging 
from  recent  issues  of  the  Z-News 
newsletter,  the  Z-System  community 
is  tending  to  favor  the  newer  8-bit  "su¬ 
perchips”  such  as  the  Hitachi  HD64180 
and  the  somewhat  mythical  Zilog 
Z800,  whose  instruction  sets  are  up¬ 
ward  compatible  with  Zilog 
mnemonics. 

Advantage  of  ZSO  Code 

Z80  optimization  of  CP/M's  8080  code 
in  the  CCP  and  BDOS  is  one  of  the  ma¬ 
jor  strengths  of  Z-System.  By  using 
more  compact  Z80  codes  for  relative 
and  conditional  jumps,  block  trans¬ 
fers,  direct  loading  of  double  regis¬ 
ters,  and  double-register  arithmetic, 
the  Z-System  design  team  have  com¬ 
pressed  most  CCP  and  BDOS  routines 
tightly  enough  to  add  important  fea- 
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tures.  The  most  common  Z80  optimi¬ 
zations  in  Z-System  are  the  familiar 
relative  and  conditional  jumps,  such 
as  the  common  substitution  of  Zilog's 
DJNZ  LOOP  for  the  Intel  DEC  B-JP 
NZ,LOOP  pair  to  control  loops,  a  sav¬ 
ing  of  only  2  bytes  and  either  one  or 
four  clock  cycles  on  each  pass.  Much 
more  impressive  optimizations  are 
I  scattered  throughout  Z-System  and 
its  utilities,  however. 

In  the  ZRDOS  CHECKSUM  routine 
shown  in  the  first  part  of  Table  3, 
page  46,  for  example,  Dennis  Wright 
i  (not  to  be  confused  with  Z-Com  devel¬ 
oper  Joseph  Wright)  substitutes  a  sin¬ 
gle  2-byte,  15-cycle  Zilog  arithmetic 
instruction  for  a  cumbersome  10- 
byte,  51-cycle  Intel  subroutine 
!  ( SUBDH  in  the  second  part  of  Table  3)  ! 
to  subtract  the  contents  of  the  DE  reg-  j 
ister  pair  from  those  of  the  HL  regis¬ 
ter  pair.  Note  also  how  Wright’s  di¬ 
rect  loading  of  the  DREC  parameter 
j  into  registers  DE  eliminates  the  Intel 
j  XCHG  instruction.  Wright’s  Zilog  sub¬ 
stitutions  in  this  tiny  code  sample 
alone  save  7  bytes  and  32  clock  cycles 
each  time  they  are  used. 

The  powerful  Z80  block-compare 
and  -transfer  instructions  (LDI,  LDIR, 
CPI,  and  CPIR )  are  underused  in 
j  Conn’s  subroutine  libraries  and  in 
the  Z-System  code  produced  from 
them.  Wright,  however,  combines 
LDIR  with  direct  loads  of  double  regis¬ 
ters  to  load  the  disk  parameter  block 
in  the  ZRDOS  SELECTD1SK  routine  with 
only  11  bytes  and  52  clock  cycles  of 
code.  Digital  Research’s  comparable 
Intel  code  requires  twice  as  many 
bytes  and  cycles  to  do  the  same  thing. 
Wright’s  use  of  the  Zilog  LDIR  instruc¬ 
tion  saves  a  total  of  11  bytes  and  46 
clock  cycles,  as  you  can  see  by  com¬ 
paring  the  first  and  second  parts  of 
Table  4,  page  46. 

The  most  effective  Z-System  optimi¬ 
zations  have  less  to  do  with  Z80  fea¬ 
tures  than  with  sound  programming 
practices.  In  comparing  disassembled 
source  code  for  BDOS  and  ZRDOS,  I  no¬ 
ticed  that  most  of  Wright's  improve¬ 
ments  involved  enhanced  logic  and 
the  elimination  of  redundancy.  By 
skillful  sequencing  of  subroutines,  he 
manages  to  make  the  flow  between 
calling  programs  and  ZRDOS  system 
calls  smoother  and  more  efficient.  He 
uses  in-line  code  in  preference  to  sub¬ 
routines  yet  avoids  redundancy  by  el¬ 
egant  relative  loops. 


The  additional  space  harvested 
from  his  thoughtful  assembly-lan¬ 
guage  programming  allows  Wright 
to  add  several  valuable  routines  and 
even  four  new  system  calls  to  ZRDOS. 
The  major  alterations  in  the  CP/M  2.2 
BDOS  eliminate  the  nagging  warm- 
boot  requirement  each  time  a  disk  is 
changed  and  make  it  easier  to  use  the 
read-only  disk  status  feature.  ZRDOS 
also  permits  wheel  protection  of  indi¬ 
vidual  files  and  file  archiving.  Two 
other  useful  new  system  calls  are  in¬ 
cluded  to  add  a  warm-boot  trap  op¬ 
tion  so  that  users  can  customize  error 
messages  by  diverting  jumps  to  loca¬ 
tion  0000H. 

Following  the  release  of  ZRDOS,  sev¬ 
eral  new  utilities  have  appeared  that 
take  advantage  of  these  enhance¬ 
ments,  and  the  list  is  growing.  Most  Z- 
System  utilities  can  work  just  as  well 
under  the  CP/M  BDOS,  but  newer  ones 
such  as  AC  (archive  copy)  and  VIEW 
require  ZRDOS  instead.  Echelon  ad¬ 
vertises  a  more  powerful  version, 
ZRDOS3,  designed  specifically  for  the 
Hitachi  HD64180  and  Zilog  Z800 
boards.  I  have  not  had  an  opportuni¬ 
ty  to  study  ZRDOS3,  but  Echelon  says  it 
adds  around  50  new  system  calls  to 
handle  such  advanced  8-bit  features 
as  multitasking,  full-track  disk  buff¬ 
ering,  and  routines  for  addressing 
larger  RAMs. 

Documentation 

Conn's  book  ZCPR3:  The  Manual  is 
the  installation  bible  and  technical 
reference  for  ZCPR3  and  its  utilities, 
particularly  if  you're  installing  the 
manual-install  hacker  version.  Eche¬ 
lon  also  distributes  Z-System  User's 
Guide  by  Richard  Jacobson  and  Bruce 
Morgen,  which  is  more  appropriate 
for  novice  users  and  others  who  are 
content  with  the  Z-Com  version. 
Many  other  well-written  hard-copy 
manuals  on  special  topics  and  tools 
are  also  available  from  Echelon. 

Z-Com  comes  with  more  than  400K 
of  on-line  modular  help  files  on  all  as¬ 
pects  of  the  system,  and  each  utility  j 
has  built-in  help  screens  for  immedi¬ 
ate  access.  Echelon  and  Z-Node  opera¬ 
tors  are  never  stingy  with  source 
code.  A  few  proprietary  items,  such  as 
ZRDOS  and  some  of  the  Z-Tools,  are  dis¬ 
tributed  only  in  object-code  files,  but 
nearly  everything  else  is  available  in 
compact  assembly-language  libraries 
with  professional  documentation  and 


I  helpful  programming  suggestions.  ’ 

j  Conclusions 

The  major  advantages  of  Z-System 
are  Z80  code  optimizations,  en¬ 
hanced  transportability,  powerful 
new  user  options,  and  compatibility 
with  CP/M  2.2.  I've  never  encoun¬ 
tered  such  elegant  and  efficient  code 
in  any  other  operating  system  that 
I’ve  worked  with. 

My  favorite  components  are  the 
RAM-resident  utilities,  internal  flow 
control  with  nested  logic,  aliases  and 
multiple  commands,  named  directo¬ 
ries,  and  customized  menu  shells,  but 
these  are  just  a  few  of  Z-System  s  ad¬ 
vanced  features.  Combined  with  fast 
new  Hitachi  HD64180  boards,  Eche¬ 
lon’s  ZCPR3  and  ZRDOS  leave  very  lit¬ 
tle  to  be  desired  in  an  8-bit  operating 
system. 
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ARTICLES 


Series  32000  Gross 
Assembler 


The  National  Semiconductor 
series  32000  microprocessor 
line  includes  the  32-bit  32032 
and  the  16-bit  32016  (formerly  called 
16032)  microprocessors.  As  part  of  a 
project  to  build  a  board  using  a  32032, 
I  wrote  an  assembler  in  Software 
Toolworks'  C/80;  adaptation  to  any 
other  variant  of  C  should  be  easy. 

Although  most  people  lump  the 
68000  and  the  32016  together,  these 
processors  are  radically  different. 
The  differences  have  been  summed 
up  as  "the  68000  is  PDP-ll-like, 
whereas  the  32000  is  VAX-like.”  The 
32000  includes  bit-field,  translate, 
procedure  enter/return,  and  other 
high-level  instructions  in  its  instruc¬ 
tion  set. 

Basic  Program  Design 

This  program  works  in  a  brute-force 
fashion,  but  it  is  easy  to  understand, 
modify,  and  debug.  Each  instruc¬ 
tion's  binary  equivalent  is  stored  in  a 
string,  with  ,xs  where  operands  need 
to  be  inserted.  A  string  matcher, 
match!  ),  matches  the  opcodes 
against  lines  in  the  source  file,  keep¬ 
ing  matches  to  wildcards  in  the  buf¬ 
fer  ambig— buffer.  Each  opcode  has 
an  option  character,  opopt,  associated 
with  it  that  controls  special-case  logic 
for  some  instructions.  The  data  is  out¬ 
put  in  Intel  absolute  hex  format.  Ta¬ 
ble  1,  page  49,  shows  the  definitions 
for  the  opopt  characters  and  the  in¬ 
struction  table  format.  Table  2,  page 
49,  shows  some  examples  of  instruc¬ 
tion  formats  defined  using  the  struc¬ 
ture  in  Table  1. 

The  32000  processor,  although  al¬ 
lowing  absolute  addressing,  features 
generalized  addressing  modes  avail¬ 
able  in  almost  all  instructions.  Two's- 
complement  offsets  can  be  used  in 
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three  different  sizes — 7,  14,  or  30  bits 
long — as  needed.  Because  these  off¬ 
sets  could  refer  to  areas  not  yet  de¬ 
fined,  and  the  length  of  the  code  var¬ 
ies  with  the  offset,  three  passes  are 
necessary.  The  first  pass  gets  a  coarse 
value  of  all  symbols,  the  second  pass 
then  makes  the  variable  offsets  the 
right  length  and  corrects  the  symbol 
values,  and  the  third  pass  actually 
generates  the  code.  After  the  first 
pass,  the  symbol  table  is  sorted;  then 
in  the  second  and  third  passes,  a  bina¬ 
ry  search  is  used  to  find  entries  more 
quickly. 

Assembler  Syntax 

•  Symbols — This  assembler  limits  line 
length  to  128  characters;  symbols  can 
be  up  to  a  whole  line  long.  Labels 
must  be  followed  by  a  colon  and  can 
not  be  reused.  The  colon  must  be 
omitted  on  equates.  Values  assigned 
with  equ  can  be  redefined,  however. 

•  Pseudo-ops — org  must  be  followed 
by  a  value.  Although  the  32000  does 
not  require  word  alignment  of  code 
or  data,  it  does  make  some  operations 
faster,  so  an  even  pseudo-op  is  provid¬ 
ed  to  force  the  code  address  to  an 
even  boundary. 

Define  byte,  word,  double  (db,  dw, 
dd)  must  be  only  one  value  per  line. 
Currently,  character-string  constants 
are  not  supported. 

Numeric  constants  must  begin  with 
a  digit.  Default  radix  is  decimal,  or  the 


value  can  be  followed  with  an  h,  q,  or 
b  for  hexadecimal,  octal,  or  binary,  re¬ 
spectively.  The  code  address  is  known 
as  and  the  assembly  address 
(which  may  be  different)  as  ".. ". 

•  Opcodes — All  32000  opcodes  are  sup¬ 
ported.  The  assembly  instructions 
must  conform  to  the  NS16000  Instruc¬ 
tion  Set  Reference  Manual — for  exam¬ 
ple,  arguments  to  the  SAVE  instruction 
must  be  enclosed  in  square  brackets. 
You  can  include  multiple  instructions 
on  a  line  as  long  as  all  operands  to 
each  instruction  are  provided. 

•  Comments — Comments  begin  with 
a  semicolon  (;)  and  continue  to  the 
end  of  the  line.  Some  programmers 
have  the  bad  habit  of  omitting  the  be¬ 
ginning  *  or;.  That  won’t  work  here. 

•  Assembly-time  arithmetic — Only 

"+”,  and  "/"are  supported. 

A  look  at  the  listing  shows  it  would  be 
trivial  to  add  more  operators,  howev¬ 
er.  Formulas  are  allowed  anywhere 
a  value  is  required,  but  they  must  be 
enclosed  in  parentheses.  Within  pa¬ 
rentheses,  values  must  be  separated 
from  operators  with  spaces.  This  is 
because  the  program  uses  the  spaces 
to  tell  where  words  end,  and  math 
operators  are  considered  words. 
Spaces  are  not  needed  between  the 
parentheses  and  the  words  enclosed. 
Note  the  spaces  around  +  and  /.  An 
example  will  best  illustrate: 

((FEN  +  1)  +  (GUG  /  3)) 

Commas  also  separate  words;  in 
fact,  commas  and  spaces  are  inter¬ 
changeable,  although  human  read¬ 
ers  may  consider  commas  out  of 
place  in  some  instances. 

•  Listing — The  assembler  produces  a 

•  listing  on  the  final  pass.  This  listing  is 
sent  to  the  screen  but  can  be  redirect¬ 
ed  into  a  file  or  to  the  printer.  It  is  a 
traditional  listing,  with  address,  bytes 
of  code  or  data,  and  opcodes  and 
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#define  MAXOP149 

/*  the  opcode  binary  value  should  be  a  string  of  bits  e.g.  01 1 1  xxxxxOOOb 

the  opcode  opopt  character  is  used  to  specify  special  operands,  etc.  7 

/*  opopts  used  here  for  the  32000  are: 

blank 

nothing  special 

a 

gen 

b 

gen  short 

c 

gen  gen 

d 

00000  short 

e 

gen  gen  reg 

f 

reglist  save/enter 

g 

reglist  restore/exit 

h 

00000  gen  (sfsr) 

i 

inss/exts 

i 

movs/skps/cmps 

k 

setcfg 

1 

procreg,  gen  for  Ipr/spr 

m 

index  (operand  order) 

n 

ret/rett  —  postbyte 

0 

movm 

p 

exp  (disp  after  instruction)  7 

struct  { 

char  *onarr 

;  T  opcode  name  7 

int  ocnt; 

/*  operand  count,  negative  if  PC-relative  7 

char  *obin; 

/*  opcode  binary  value  7 

char  oopt; 

} 

/*  opcode  opopt  char  7 

Table  1:  Definitions  of  opopt  characters 


"bsr", 

-1, 

"02h", 

,  , 

"save", 

1, 

"62h", 

T, 

"sve", 

0, 

"0e2h", 

, 

"bne", 

-1, 

"lah", 

’b’, 

"addq?", 

2, 

"xxxxxxxxxOOOl  1  iib". 

’e\ 

"sgt?", 

1, 

"xxxxxOIIOOUIliib", 

’a’, 

"jump", 

1, 

"xxxxxOI  00111111 1b", 

’a’, 

"jsr", 

1, 

"xxxxxll  0011 11111b", 

’a’, 

"addl", 

2, 

"xxxxxxxxxxOOOOOOl 011111 0b" , 

’c\ 

"mulf", 

2, 

"xxxxxxxxxxl  1 0001 1011111 0b", 

’c\ 

"and?", 

2, 

"xxxxxxxxxxl  01  Oiib", 

’c\ 

"not?", 

2, 

"xxxxxxxxxxl  001  iiOl  001 1 1 0b" , 

’c\ 

Table  2:  Selected  instruction  formats  from  the  opcode  table 


comments  on  the  right. 

Table  3,  below,  shows  the  error 
messages  produced  by  the  assembler. 

Future  Enhancements 

Unless  I  get  some  32000  hardware  to 
play  with,  it's  unlikely  I'll  work  on 
this  program  further.  If  you’d  like  to 
work  on  it,  however,  some  items  on 
your  list  should  be: 

1.  Multivalue  db/dw/dd  and  charac¬ 
ter-string  constants. 

2.  Global/external  object  format  and 
linker.  The  32000  instructions  are  al¬ 
ready  relocatable;  any  absolute  val¬ 
ues  that  would  be  present  would  pre¬ 
sumably  be  entry  points  or  I/O 
addresses.  In  fact,  even  the  global/ex¬ 
ternal  isn’t  really  necessary  because 
of  the  cyp/ryp  instructions. 

3.  Cseg/dseg  pseudo-ops. 

If  you  send  your  changes  to  me,  I  ll 
be  happy  to  make  them  available  to 
others.  Anyone  wanting  a  copy  of  the 
source  code  may  send  me  $8  for  ma¬ 
terials  and  effort.  Please  specify  8- 
inch  CP/M,  5V4-inch  PC,  or  other  (in¬ 
quire)  or  3V2-inch  Atari  ST. 

For  those  lucky  people  who  are  in 
a  position  to  make  use  of  this  pro¬ 
gram,  why  not  let  readers  know 
what  you’re  doing?  Is  the  32000  real¬ 
ly  the  programmer’s  dream  some  say 
it  is?  And  for  those  who  are  in  a  posi¬ 
tion  to  do  so,  how  about  some  inex¬ 
pensive  32000  hardware — a  single- 
board  computer  perhaps — so  people 
can  get  a  hands-on  feel  for  what  the 
processor  can  do? 

Even  if  you  don’t  have  a  32000  pro¬ 
cessor  to  play  with,  you  may  be  able 
to  make  use  of  routines  from  this  pro¬ 
gram.  The  style  exemplifies  my  be¬ 
lief  that  C  should  be  written  to  be 
readable  both  by  computers  and  by 
humans.  Cryptic  C  is  bad  C. 


?  unknown  item — syntax  error 

x  unimplemented  instruction  (bad  instruction  database) 

I  no  length  modifier  (bad  instruction  database) 

or  expression  too  complex 
e  address  extensions  missing 

p  illegal  register  Ipr/spr 

[  brackets  required 

v  syntax  error  in  value 

o  unknown  arithmetic  operator 

u  undefined  symbol 


Table  3:  Error  messages 


DIM 

Vote  for  your  favorite  feature/article. 

Circle  Reader  Service  IMo.  5. 

The  listing  for  this  article  is  present¬ 
ed  in  a  machine-readable  form — Soft- 
strips  produced  by  Cauzin  Systems. 
The  strips  begin  on  page  83.  The  teyt  of 
the  listing  is  available  for  downloading 
in  the  DDJ  Electronic  Edition  on  Com¬ 
puServe.  A  disk  with  this  listing  and 
others  is  also  available — see  the  ad  on 
page  115.  The  teyt  of  the  listing  will  be 
published  neyt  month. 
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Listing  One  (Text  begins  on  page  16.) 


Listing  1  Scheduling  Algorithm 

(C)  Copyright  1986  Ken  Berry. 

All  rights  reserved. 

Copies  may  be  made  for  non-commercial,  private  use  only. 


♦define  _F  0 
♦define  _T  1 
♦define  _E  -1 

♦define  NULL  0 


/*  false  */ 

/*  true  */ 

/*  error  */ 

/*  null  pointer  *f 


typedef  char  pointer;  /*  pointer  type  */ 

typedef  char  logical;  /*  logical  type  */ 

typedef  unsigned  selector;  /*  8086  selector  type  */ 


struct  sys_parm 
{ 

union  {unsigned  sys_ 
union  {unsigned  sys_ 
union  {unsigned  sys_ 
union  {unsigned  sys_ 
♦define  sys_ax  sys_ra. 
♦define  sys_al  sys_ra. 
♦define  sys_ah  sys_ra. 
♦define  sys_bx  sys_rb. 
♦define  sys_bl  sys_rb. 
♦define  sys_bh  sys_rb. 
♦define  sys_cx  sys_rc. 
♦define  sys_cl  sys_rc. 
♦define  sys_ch  sys_rc. 
♦define  sys_dx  sys_rd. 
♦define  sys_dl  sys_rd. 
♦define  sys_dh  sys_rd.  „ 
unsigned  sys_bp;  7* 

unsigned  sys_si;  /* 

unsigned  sys_di;  /* 

unsigned  sys_sp;  /* 

unsigned  sys_cs;  /* 

unsigned  sys_ds;  /* 

unsigned  sys_ss;  /* 

unsigned  sys_es;  /* 

unsigned  sys_pf;  /* 

♦define  SYS_OF  0x0800 
♦define  SYS_DF  0x0400 
♦define  SYS_IF  0x0200 
♦define  SYS_TF  0x0100 
♦define  SYS_SF  0x0080 
♦define  SYS_ZF  0x0040 
♦define  SYS_AF  0x0010 
♦define  SYS_PF  0x0004 
♦define  SYS_CF  0x0001 

unsigned  sys_sw;  /* 

♦define  SYS_TS  0x0008 
♦define  SYS_EM  0x0004 
♦define  SYS_MP  0x0002 
♦define  SYS_PE  0x0001 

unsigned  sys_ip;  /* 

unsigned  sys_res;  /* 

): 

struct  t_xstck 

{ 

unsigned  t_xbase;  /* 

unsigned  t_xes;  /* 

unsigned  t_xbp;  /* 

unsigned  t_xdi;  /* 

unsigned  t_xsi;  /* 

unsigned  t_xdx;  /* 

unsigned  t_xcx;  /* 

unsigned  t_xbx;  /* 

unsigned  t_xax;  /* 

unsigned  t_xds;  /* 

unsigned  t_xip;  /* 

unsigned  t_xcs;  /* 

unsigned  t_xpf;  /* 

unsigned  t_retip;  /* 


/*  register  storage  block  for  8086  interface  */ 

rax;  struct  {char  sys_ral,  sysrah;)  sys_byt;}  sys_ra; 
rbx ;  struct  {char  sys_rbl,  sys_rbh;}  sys_byt;)  sys_rb; 


sys_rch;}  sys_byt; 
sys_rdh;)  sys_byt;} 


sys_rc; 

sys_rd; 


rex;  struct  {char  8ys_rcl, 
rdx;  struct  {char  sys_rdl, 
sys_rax 
sy s_byt . sys_ral 
sys_by t . sy s_rah 
sys_rbx 

sys_byt . sys_rbl 
sys_byt . sys_rbh 
sys_rcx 

sys_byt . sys_rcl 
sys_byt . sy s_rch 
sys_rdx 

sy s_byt . sys_rdl 
sys  byt.sys_rdh 

base  pointer  */ 
source  index  */ 
destination  index  */ 
stack  pointer  */ 
code  segment  */ 
data  segment  */ 
stack  segment  */ 
extra  segment  */ 

80286  processor  flags  */ 

/*  overflow  flag-  1;  lost  significance  */ 

/*  direction  flag-  1:  strings  auto-decrement  */ 
/*  interrupt  flag-  1:  enable  interrupts  */ 

/*  trap  flag-  1;  interrupt  every  instruction  */ 
/*  sign  flag-  1 :  result  negative  */ 

/*  zero  flag-  1:  result  0  */ 

/*  auxiliary  carry  flag-  1:  carry  from  bit  3  */ 
/*  parity  flag-  1:  even  number  of  l's  */ 

/*  carry  flag-  1:  carry  from  bit  8  or  16  */ 
status  word  */ 

/*  task  switch  */ 

/*  processor  extension  emulation  */ 

/*  monitor  processor  extension  */ 

/*  protection  enable  */ 
instruction  pointer  * / 
unused  */ 


application  stack  base  (overflow  detection)  */ 

es  *  / 

bp  */ 

di  */ 

si  */ 

dx  */ 

cx  *  / 

bx  V 

ax  */ 

ds  */ 

ip  */ 

/ 

/ 


Pf 

return  address  *1 


struct  t  task 
( 

char  t_type; 

♦define  T_X  0x80 
♦define  T_W  0x40 
♦define  T_P  0x20 
♦define  T_SW  0x10 
♦define  T  ATASK  0x01 
unsigned  t_wttk; 
unsigned  t_cls; 
struct  t_task  *tjpqtsk, 
struct  t_task  *t_ratsk 
struct  sys_parm  t_ps; 
unsigned  t_xtm0; 
unsigned  t_xtml; 
unsigned  t_xtm2; 
pointer  *t_axstk; 

} ; 


/*  task  type  */ 

/*  execute  queue  */ 

/*  wait  queue  */ 

/*  priority  queue  */ 

/*  secondary  wait  queue  */ 

/*  abreviated  task  */ 

/*  wait  tick  count  */ 

/*  priority  queue  index  */ 

*t_nqtsk;  /*  queue  linkage  */ 

*t_pstsk, *t_nstsk, *t_fdtsk, *t_ldtsk;  /*  family  */ 
/*  processor  status  */ 

/*  execution  time  accumulator  */ 


/*  execution  stack  pointer  */ 


extern  pointer  *sys_task;  /*  current  task  control  table  pointer  */ 

♦define  _tsk  (  (  struct  t_task  *  )  sys_task  )  /*  task  control  table  ref  */ 


♦  define  T  SCLS  4 


struct  t  scls 


unsigned  t_sfrq; 
int  t  set; 


/*  number  of  scheduling  classes  */ 

/*  scheduling  class  queue  */ 

/*  scheduling  frequency  */ 

/*  queue  length  */ 
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struct  t_task  *t_fqtsk,  *t_lqtsk;  /*  queue  header 


struct  t_schd 
( 

int  t  xct; 

struct  t_task  *t_fxtsk, 
int  t  wet; 


/*  scheduling  control  table  */ 

/*  execution  queue  length  */ 

,  *t_lxtsk;  /*  execution  queue  header  */ 
/*  wait  queue  length  */ 


struct  t_task  *t_fwtsk,  *t_lwtsk;  f*  wait  queue  header  */ 

int  t  swet;  /*  secondary  wait  queue  length  */ 

struct  t  task  *t_fswtsk,  *t_lswtsk;  /*  secondary  wait  queue  header  */ 

int  t_scTsl;  /*  scheduling  class  index  limit  */ 

struct  t _ scl s  **t_sclsp;  /*  scheduling  class  array  pointer  */ 


extern  pointer  *sys_tsch;  /*  task  scheduling  control  table  pointer  */ 
♦define  _tschd  (  (  struct  t_schd  *  )  sy3_tsch  )  /*  quick  pointer  */ 

/* 

t  krnl  /*  security  kernel  */ 

t  krnl ( ) 

/* 

This  is  the  security  kernel.  It  never  returns,  being  the  most  trusted 

software  in  the  system.  The  current  contents  in  t _ ertss  and  t _ ertsp 

are  used  to  set  the  stack  for  when  the  current  task  is  resumed.  */ 

[ 

extern  logical  t_astrm;  /*  tick  termination  flag  */ 


extern  selector  t  ertss; 


current  task  ss  storage 


extern  pointer  *t _ ertsp;  /*  current  task  sp  storage 

extern  unsigned  tmr_tkct;  /*  tick  clock  */ 


int  xtsket;  /*  task  queue  count  (at  entry)  */ 

int  ttc;  /*  task  termination  code  */ 

_tsk  ->  t_ps.sys_ss  -  t _ ertss;  /*  set  current  task  stack 

_tsk  ->  t__ps.sy8_sp  -  t  ertsp; 

while (_T)  T*  find  executable  task  */ 


xtsket  -  _tschd  ->  t_xct;  /*  save  task  count  */ 

if  {  t_astrm  )  t _ wtst(  tmr_tkct  );  /*  process  wait  tasks  */ 

if  (  xtsket  --  0  )  t _ sch();  /*  schedule  application  tasks  if  necessary  */ 

sys_task  -  _tschd  ->  t_fxtsk;  /*  set  next  task  address  */ 

if  (  sys_task  !-  _NULL  )  /*  teat  for  executable  task  available  */ 

{ 

_tschd  ->  t_xct — ;  /*  decrement  executing  task  count  */ 
tschd  ->  t_fxtsk  -  _tsk  ->  t_nqtsk;  /*  delink  task  */ 

If  (  _tschd  ->  t_fxtsk  —  _NULL  ) 

_tschd  ->  t_lxtsk  -  _NULL; 
else  _tschd  ->  t_fxtsk  ->  t  pqtsk  -  _NULL; 
tsk  ->  t_type  4-  ~T_X;  /*  Indicate  task  not  in  execution  queue  */ 

Etc  -  t _ xtsk(  sys_task  );  /*  execute  application  task  */ 

if  (  !sys_task  )  continue;  /*  test  for  task  terminated  */ 

if  (  ttc  <  0  )  t _ inxq();  /*  insert  task  into  execution  queue  */ 

else  if  (  ttc  --  0  )  t inpq();  /*  insert  task  into  priority  queue  */ 

else  t lnwq(  ttc  );  /*  insert  into  wait  queue  */ 


t  wtst  test  waiting  tasks 

t _ wtst(  tc) 

unsigned  tc; 

/* 

The  wait  queue  is  traversed.  All  tasks  with  a  wait  value  of  tc  are  executed. 
_F  is  always  returned.  */ 

[ 

while (_T)  /*  traverse  wait  queue  */ 

{ 

sys_task  -  _tschd  ->  t_fwtsk;  /*  set  current  task  pointer  */ 
if  (  !sys_task  )  break;  /*  test  for  no  waiting  tasks  */ 

_tsk  ->  t_type  4-  ~T_W;  /*  remove  task  from  wait  queue  */ 
tsk  ->  t_type  |-  T_X;  /*  indicate  task  in  execution  queue  */ 

If  (  _tsk  ->  t_wttk  >  tc  )  break;  /*  test  for  effective  end  of  list  */ 

— _tschd  ->  t_wct;  /*  decrement  waiting  task  count  */ 
tschd  ->  t_fwtsk  -  _tsk  ->  t_nqtsk;  /*  delink  from  wait  queue  */ 

If  (  _tsk  ->  t  nqtsk  —  _NULL  ) 

_tschd  ->  t_Iwtsk  -  _NULL; 
else  _tsk  ->  t  nqtsk  ->  t  pqtsk  -  _NULL; 

_tsk  ->  t_pqtsk  -  _NULL;  7*  insert  at  top  of  execution  queue  */ 

_tsk  ->  t_nqtsk  -  _tschd  ->  t_fxtsk; 

_tschd  ->  t_fxtsk  -  sys_task; 

++_tschd  ->  t_xct;  /*  increment  executable  task  count  */ 
if  (  _tschd  ->  t_lxt8k  --  NULL  ) 

_tschd  ->  t_lxtsk  -  sys_Eask; 
else  _tsk  ->  t_nqtsk  ->  t_pqtsk  -  sys_task; 

) 

return  F;  /*  return  */ 


/* 

t  sch  schedule  task 

*7~ 

t  sch() 

/* 

This  function  searches  the  priority  queues  and  links  tasks  ready  for  execution 
into  the  execution  queue.  The  return  is  always  F.  */ 

( 

struct  t _ scls  **a;  /*  priority  queue  pointer  array  pointer  */ 

struct  t_scls  *q;  /*  priority  queue  pointer  */ 

int  i,j;  /*  iteration  variables  */ 

a  -  tschd  ->  t_sclsp;  /*  set  pointer  array  address  */ 

/*  whlle(  T)  /*  nonterminating  task  */ 

(  V 

for  (  i  -  0;  i  <  _tschd  ->  tsclsl;  ++i  )  /*  traverse  queues  */ 

( 

q  -  a [ 1 ] ;  /*  set  priority  queue  pointer  */ 

for  (  j  -  0;  j++<q  ->  t_sfrq;  )  /*  schedule  tasks  from  priority  queue  */ 

[ 

if  (  q  ->  t_fqtsk  ~  _NULL  )  break;  /*  test  for  queue  empty  */ 
if  (  _tschd  ->  t_lxtsk  )  /•*  link  to  end  of  execution  queue  */ 

_t3chd  ->  t_lxtsk  ->  t_nqtsk  -  q  ->  t_fqtsk; 
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Listing  One  (Listing  continued,  text  begins  on  page  16.) 

el9e  _tschd  ->  t_fxtsk  -  q  ->  t_fqtak; 

q  ->  t_fqtsk  ->  t_type  4-  ~T_P;  /*  indicate  not  in  priority  queue  */ 
q  ->  t_fqtsk  ->  t_pqtsk  -  _tschd  ->  t_lxt3k; 

_t3chd  ->  t  lxtsk  -  q  ->  t  fqtsk; 

q  ->  t_fqtslc  -  q  ->  t  fqtslc  ->  t_nqtsk;  /*  update  queue  header  * / 
tschd  ->  t_lxtsk  ->  I  nqtsk  -  _NULL; 

If  {  q  ->  t_fqtsk  —  TiULL  ) 
q  ->  t_lqtsk  -  _NULL; 
else  q  ->  t_fqtsk  ->  t_pqtsk  -  _NULL; 
q  ->  t_sct  — ;  /*  decrement  queue  count  */ 

++  _tschd  ->  t_xct;  /*  increment  execution  queue  length  */ 

_tschd  ->  t_lxtsk  ->  t_type  |-  T_X;  /*  ind.  task  in  execution  queue  */ 

} 

} 

/*  t  rels{);  /*  return  to  bottom  of  execution  queue  */ 

IV 

return  F;  /*  return  */ 


/* 

t  inxq  insert  task  into  execution  queue 

t  inxq ( ) 

/* 

The  current  task  is  inserted  into  the  execution  queue.  F  is  always  returned. 
*/ 

{ 

tsk  ->  t_wttk  -  0;  I*  indicate  not  waiting  for  system  tick  */ 

If  (  _tschd  ->  t_lxtsk  —  _NULL  )  /*  test  for  execution  queue  empty  */ 

{ 

_tschd  ->  t_fxtsk  -  sys_task;  /*  insert  in  empty  queue  */ 

_tsk  ->  t_pqtsk  -  _NULL; 

} 

else  /*  execution  queue  not  empty  */ 

{ 

_tschd  ->  t_lxtsk  ->  t_nqtsk  -  sys_task;  /*  insert  at  end  of  queue  */ 
_tsk  ->  t_pqtsk  -  _t schd  ->  t_lxtsk; 

) 

_tsk  ->  t_nqtsk  -  _NULL;  /*  new  task  at  end  of  list  */ 

_tschd  ->  t_lxtsk  -  sys  task; 

_tschd  ->  t_xct++;  7*  increment  executable  task  count  */ 

_tschd  ->  t_lxtsk  ->  t_type  |-  T_X;  /*  indicate  task  in  execution  queue  */ 
/*  return  */ 


process  secondary  wait  queue 


This  program  executes  every  64K  system  ticks.  It  moves  the  secondary 
wait  queue  to  the  primary  wait  queue  and  changes  the  type  of  the  waiting 
tasks.  */ 

{ 

struct  t_task  *tsk;  /*  task  control  table  pointer  */ 

char  swtflg;  /*  system  state  flag  */ 

while (_T)  /*  nonterminating  task  */ 

{ 

t _ syntr(  4swtflg  );  /*  enter  system  state  */ 

for  (  tsk  -  _tschd  ->  t_fwtsk;  tsk;  tsk  -  tsk  ->  t_nqtsk  )  /*  traverse  */ 
tsk  ->  t_type  4-  ~T_SW; 

tsk  ->  t_type  |-  T_W;  /*  change  task  type  */ 

) 

_tschd  ->  t_wct  -  _tschd  ->  t_swct;  /*  append  secondary  wait  queue  */ 
_tschd  ->  t_fwtsk  -  _tschd  ->  t_fswtsk; 

_tschd  ->  t_lwtsk  -  _tschd  ->  t  lswtsk; 

_tschd  ->  t_fswtsk  -  _tschd  ->  E_lswtsk  -  _NULL;  /*  empty  sec.  queue  */ 
_tschd  ->  t _ s wet  -  0; 

t _ inwq(  OxFFFF  -  tmr  tket  );  /*  insert  self  into  wait  queue  at  end  */ 

sys_task  -  _NULL;  7*  remove  task  from  kernel  control  */ 
t_term();  /*  suspend  execution  */ 

) 

) 

/* 

t  inwq  insert  task  into  wait  queue 

*1 

t _ inwq (tc) 

unsigned  tc; 

/* 

The  current  task  is  inserted  into  the  wait  queue,  tc  is  the  number  of  system 
ticks  that  the  task  is  to  wait.  F  is  always  returned.  */ 

{ 

extern  unsigned  tmr_tkct;  /*  tick  clock  */ 
unsigned  ertk;  /*  current  tick  */ 

ertk  -  tmr_tkct;  /*  set  current  system  tick  */ 

tsk  ->  t_wttk  -  tc  +  ertk;  /*  compute  reactivation  time  */ 

If  {  tsk  ->  t_wttk  >-  ertk  )  /*  te3t  for  task  in  wait  queue  */ 

(  t  Tnwt (  S_tschd  ->  t_wct  );  /*  insert  in  wait  queue  */ 

_tsk  ->  t_type  |-  T_W; 

)else  /*  task  in  secondary  wait  queue  */ 

(  t _ inwt (  4_tschd  ->  t_swct  );  /*  insert  in  secondary  wait  queue  */ 

tsk  ->  t  type  |-  T  SW; 

/*  indicate  task  inserted  */ 


insert  into  wait  or  secondary  wait  queue 


/*  wait  queue  length  V 
struct  t_task  *frs,*lst;  /*  queue  header  */ 

) ; 

t _ inwt (  w  ) 

struct  t_wtq  *w; 


) return  _F; 

) 

/* 

t  inwt 

*T~ 

struct  t_wtq 
int  wet; 


return  _F; 

) 

/* 

t  secw 
t _ secw ( ) 
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/* 

The  t  wtq  structure  is  implicitly  contained  in  the  scheduling  control  table 
(t_scKd  structure) .  The  current  task  is  inserted  into  the  queue.  _F  is  always 
returned.  */ 

{ 

struct  t_task  *p;  /*  task  pointer  */ 

unsigned  tc;  /*  reactivation  time  */ 

tc  -  _tsk  ->  t_wttk;  /*  set  reactivation  time  * / 

++w  ->  wet;  /*  increment  queue  length  */ 

for  (  p  -  w  ->  frs;  p;  p  -  p  ->  t_nqtsk  )  /*  traverse  queue  */ 

if  (  tc  <  p  ->  t_wttk  )  /*  test  for  task  earlier  */ 

( 

_tsk  ->  t_nqtsk  -  p;  /*  insert  within  queue  */ 

_tsk  ->  t_pqtsk  -  p  ->  t_pqtsk; 
p  ->  t_pqtsk  -  sys_task; 

if  (  (  p  -  _tsk  ->  t_pqtsk  )  )  p  ->  t_nqtsk  -  sys_task; 
else  w  ->  frs  -  sys  task; 

return  _F;  7*  indicate  task  inserted  */ 

} 

) 

if  (  (  p  -  w  ->  1st  )  )  /*  test  for  wait  queue  not  empty  */ 

{ 

p  ->  t_nqtsk  -  w  ->  1st  -  sys_task;  /*  insert  at  end  of  queue  */ 

_tsk  ->  t_pqtsk  -  p; 

_tsk  ->  t_nqtsk  -  _NULL; 

) 

else  /*  wait  queue  empty  */ 

w  ->  frs  -  w  ->  1st  -  sys_task;  /*  initialize  wait  queue  */ 

_tsk  ->  t_nqt sk  -  _tsk  ->  t_pqtsk  -  _NULL; 

) 

return  _F;  /*  indicate  task  inserted  */ 


I* 

t  inpq  insert  into  priority  queue 

*7~ 

t  inpqO 
/* 

The  current  task  is  inserted  into  its  priority  queue.  _F  is  always  returned. 

*/ 

{ 

struct  t_scls  *q;  /*  priority  queue  pointer  */ 

_tsk  ->  t_wttk  -  0;  /*  indicate  not  waiting  for  tick  */ 

q  -  _tschd  ->  t_sclsp[  tsk  ->  t  els  J;  /*  set  priority  queue  address  */ 

_tsk  ->  t_pqtsk  -  q  ->  F_lqtsk;  7*  link  task  into  priority  queue  */ 
tsk  ->  t_nqtsk  -  _NULL; 

If  (  q  ->  t_lqtsk  —  NULL  )  q  ->  t_fqtsk  -  sys_task; 
else  q  ->  t_lqtsk  ->  E_nqtsk  -  sys_task; 
q  ->  t_lqtsk  -  sys_task; 

++q  ->  t_sct;  /*  increment  queue  length  */ 

_tsk  ->  t_type  |-  T_P;  /*  indicate  task  in  priority  queue  */ 
return  _F;  /*  return  */ 

) 

/* 

t  xtsk  execute  task 

*7~ 

t _ xtsk(  t  ) 

struct  t_task  *t; 

/* 

Task  t  is  executed.  The  returned  value  is  the  termination  code. 

*/ 

{ 

extern  unsigned  t_mnxtm;  /*  minimum  execution  time  */ 

extern  unsigned  t_syxtmU;  /*  system  pseudo  time  accumulator  */ 

extern  logical  t_astrm;  /*  application  termination  flag  */ 

int  ttc;  /*  return  value  storage  */ 

unsigned  atm;  /*  accumulated  time  */ 

unsigned  rtm;  /*  reference  time  */ 

int  xtra;  /*  execution  time  */ 

atm  -  0;  /*  initialize  accumulated  execution  time  */ 

while (_T)  /*  execute  task  */ 

{ 

rtm  -  t  ->  t_xtm0;  /*  set  reference  time  */ 
t_rtmark(  &t  ->  t_xtm0  );  /*  accumulate  pseudo  time  */ 

ttc  -  t _ dspap(  t  ->  t_ps.sys  ss,  t  ->  t_ps.sys_sp  );  /*  execute  task  */ 

t  ->  t_ps.sys_ss  -  t ertss;  7*  store  ss  */ 

t  ->  t_ps.sys_sp  -  t ertsp;  /*  store  sp  */ 

t_rtmark(  &t_syxtm  );  /*  accumulate  pseudo  time  */ 

if  (  (  ttc  !-  0  )  ||  !t_astrm  )  break;  /*  test  for  not  tick  termination  */ 
xtm  -  t  ->  t_xtm0  -  rtm;  /*  compute  execution  time  */ 
if  (  xtm  <  rtm  )  xtm  -  -xtm; 

atm  +-  xtm;  /*  accumulate  execution  time  */ 

if  (  atm  >-  t_mnxtm  )  break;  I*  test  for  minimum  time  satisfied  */ 

) 

return  ttc;  /*  return  */ 

) 

/* 

t  init  initialize  task  system 

*7~ 

t  init() 

/* 

This  function  initializes  the  task  system.  _F  is  the  normal  return.  _E  is 
returned  if  the  system  cannot  be  initialized.  */ 

{ 

♦define  WSTK  252  /*  t_wqupd  stack  size  */ 

extern  struct  sys_parm  sys_stat;  /*  initial  processor  status  */ 
extern  struct  t_task  *t_wqupd;  /*  secondary  wait  queue  update  task  */_ 
extern  selector  sys_dgrp;  /*  data  segment  selector  storage  */ 
extern  char  *sys_ssbs;  /*  system  stack  pointer  */ 
extern  unsigned  sys_sssz;  /*  system  stack  length  * / 
extern  char  tmr_ilck;  /*  tick  service  interlock  */ 

int  t _ secw();  /*  wait  queue  update  function  */ 

struct  t _ scl s  *cls;  /*  priority  queue  pointer  */ 

struct  t_scls  **ary;  /*  priority  queue  pointer  array  pointer  */ 

int  i;  /*  iteration  variable  */ 

char  *s;  /*  pointer  */ 

tmr _ int();  /*  initialize  system  tick  clock  */ 

sys  task  -  sys_ssbs  +  sys_sssz;  /*  set  main  task  control  table  pointer  */ 

_tslc  ->  t_xtm0  -  /*  initialize  execution  time  */ 

_tsk  ->  t_xtml  - 

_ts y.  ->  t_xtm2  -  o;  (continued  on  next  page) 
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Listing  One  (Listing  continued,  text  begins  on  page  16.) 

if(  (  sys_tsch  -  nun  aloc(  sizeof (  struct  t_schd  )  )  )  —  _NULL  )goto  errl; 
if(  (  ary  -  mm_aloc7  T_SCLS*(  aizeof(  struct  t_scls  )+2  )  )  ) 

—  _NULL  )goto  err2; 

_tsk  ->  t_pqtsk  -  /*  HULL  linkage  */ 

_tsk  ->  t_nqtsk  - 
_tsk  ->  t_ratsk  - 
_tsk  ->  t_pstsk  - 
_tsk  ->  t_nstsk  “ 

_tsk  ->  t_fdtsk  - 
_tsk  ->  t_ldtsk  -  _NULL; 

_tsk  ->  t_cls  -  0;  /*  set  priority  class  0  */ 

tsk  ->  t  wttk  -  0;  /*  indicate  not  waiting  */ 


tsk  ->  t  wttk  -  0;  /*  indicate  not  waiting  *! 

Tor(  i  -  ft,  s  -  &_t9k  ->  t_ps; 

i++<sizeof(  struct  sys_parm  );  )*s  -  0;  /*  clear  t_ps  */ 

_tsk  ->  t_ps.sys_cs  -  sys_stat . sys_cs;  /*  set  selectors  */ 

_tsk  ->  t_ps.sys_ds  - 
_tsk  ->  t_ps.sys_e8  - 
_tsk  ->  t_ps.sys_ss  -  sys  dgrp; 

_tsk  ->  t_axstk  -  NULL;  7*  NULL  execution  stack  pointer  */ 

_tschd  ->  t_xct  -  T;  /*  set  execution  task  count  */ 

_tschd  ->  t_fxtsk  -  /*  set  execution  queue  */ 

_tschd  ->  t_lxtsk  -  sys  task; 

_t8chd  ->  t_wct  -  0;  7*  indicate  idle  wait  queue  */ 

_t8chd  ->  t_fwtsk  -  /*  set  wait  queue  */ 

_tschd  ->  t_lwtsk  -  _NULL; 

_tschd  ->  tswct  -  0;  /*  indicate  empty  secondary  wait  queue  */ 

_tschd  ->  t_fswtsk  -  /*  NULL  secondary  wait  queue  */ 

_tschd  ->  t_lswtsk  -  _NULL; 

_tschd  ->  t_sclsl  -  T_SCLS;  /*  set  priority  queue  count  */ 

_tschd  ->  t_sclsp  -  ary;  /*  set  priority  queue  pointer  array  address  */ 

els  -  &ary[  T_SCLS  ];  /*  set  first  t_scls  pointer  */ 

for (  i  -  0;  i<T_SCLS;  ++i,  ++cls  )  /*  initialize  priority  queues  */ 


ary[i]  -  els; 
els  ->  t_sfrq  -  1; 

els  ->  t _ set  -  0; 

els  ->  t_fqtsk  - 
els  ->  t_lqtsk  -  _ 


/*  set  priority  queue  pointer 
/*  set  default  frequency  */ 

/*  indicate  empty  queue  */ 

/*  NULL  queue  linkage  */ 

NULL; 


t_wqupd  -  /*  create  task  to  update  wait  queue  */ 

t_crt (  t  secw,  0,  0,  WSTK,  0,  0,  0  ); 
if(  t_wqupcT —  _NULL  )goto  err3; 

t_wqupd  ->  t_wttk  -  OxFFFF;  /*  update  wait  queue  at  wraparound  time  */ 


t _ dspsyO;  / 

tmr_ilck  -  0x00;  / 

return  _F;  / 

err3;  mm_free{  ary  );  / 

err2:  mm  free(  sys_tsch  ); 

errl:  return  _E; 

) 


/*  dispatch  system  */ 

/*  enable  tick  service  */ 

/*  indicate  task  system  initialized  */ 
/*  error  nest  */ 


t  term 

*7" 

t  term() 

I* 

The  task  system  is  terminated.  All  tasks  and  storage  allocated  by  t _ init  are 

released.  The  return  is  always  F.  */ 

( 

extern  char  *sys_ssbs;  /*  system  stack  base  */ 
extern  unsigned  sys_sssz;  /*  system  stack  size  */ 
struct  t  task  *t;  /*  t_task  pointer  */ 

char  trmllg;  /*  system  state  flag  storage  */ 

tmr _ rst();  /*  reset  system  tick  clock  */ 

t _ syntr(  4trmflg  );  /*  enter  system  state  */ 

sys  task  -  sys_ssb8  +  sys_sssz;  /*  set  original  task  address  */ 
while (  (  t  -  _tsk  ->  t_fdtsk  )  )  /*  delete  all  created  tasks  */ 
t  del (  t,  _F  ) ; 
mm_Iree (  _tschd  ->  t_sclsp  ) ; 
mm_free(  sys_tsch  ); 

return  _F;  /*  normal  return  */ 

) 

I* 

t  ert  create  task 

*7 

t_crt (  xadr,  pent,  padr,  ssiz,  dsiz,  sadr,  prty  ) 

pointer  *xadr; 

unsigned  pent; 

unsigned  *padr; 

unsigned  ssiz,  dsiz; 

pointer  *sadr; 

unsigned  prty; 

/* 

A  new  task  is  created  with  execution  priority  prty.  Execution  will  begin  at 

xadr.  pent  parameters  will  be  passed  (on  the  new  task  stack) .  The  parameters 

are  in  an  array  addressed  by  padr.  The  new  task  will  have  a  stack  of  ssiz 

bytes  and  a  dynamic  memory  area  of  dsiz  bytes,  dsiz  may  be  zero  to  indicate 

that  no  dynamic  memory  is  required.  sadr  will  recieve  a  termination  code  when 
the  task  terminates.  If  sadr  is  _NULL,  an  abreviated  task  is  created.  _F  is 
returned  if  insufficient  memory  is  available.  Otherwise  the  address  of  the 
t  ftask  table  is  returned.  */ 


extern  int  t  halt();  /*  return  address 


struct  t_task  *tsk;  /*  task  control  table  pointer  (t_task)  */ 

struct  t_scls  *pq;  /*  priority  queue  pointer  */ 

struct  t_xstck  *sp;  /*  execution  stack  pointer  */ 

pointer  *ss;  /*  stack  start  */ 

unsigned  *pr;  /*  parameter  pointer  */ 

unsigned  In;  /*  task  control  table  length  */ 

J-nt  i;  /*  iteration  variable  */ 

char  *s;  /*  pointer  */ 

char  *sptr;  /*  execution  stack  pointer  */ 

logical  ert fig;  /*  system  state  flag  storage  */ 

t _ syntr (  Scrtflg  );  /*  enter  system  state  */ 

In  —  sizeof (  struct  t  task  );  /*  allocate  task  control  table  */ 

if(  (  tsk  -  mm_aloc(  Tn  )  )  —  NULL  )  goto  errl; 
ssiz  +-  sizeof (  struct  t_xstck  7;  /*  allocate  stack  */ 
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Listing  One  (Listing  continued,  text  begins  on  page  16.) 

if(  (  ss  -  tsk  ->  t_axatk  -  mm  aloc(  saiz  )  )  —  _NULL  ) goto  err2; 
tak  ->  t_type  -  T_ATASK ;  /*  indicate  abreviated  taak  control  table  */ 
tsk  ->  t_wttk  -  0;  /*  indicate  not  waiting  */ 

tsk  ->  t_ratsk  -  sys  task;  /*  task  family  linkage  */ 
tsk  ->  t_pstsk  -  _tsk  ->  t_ldtsk; 
tsk  ->  t_nstsk  - 
tsk  ->  t_fdtsk  - 
tsk  ->  t_ldtsk  -  _NULL; 
tsk  ->  t_ldtsk  -  tsk; 

If(  tsk  ->  t_pstsk  --  _NULL  )  t8k  ->  t_fdtak  -  tsk; 
else  tsk  ->  tjistsk  ->  t_nstslc  -  tsk; 
if(  prty  >  _tschd  ->  t_aclsl  )  /*  adjust  priority  */ 
prty  -  _tschd  ->  t_sclsl-l; 
tsk  ->  t_cls  -  prty;  /*  set  priority  */ 

pq  -  _tschd  ->  t_sclsp[  prty  ];  /*  set  scheduling  array  pointer  */ 

++pq  ->  t_sct;  /*  scheduling  linkage  */ 

tsk  ->  t_pqtsk  -  pq  ->  t_lqtsk; 
tsk  ->  t_nqtsk  -  NULL; 

1  f  {  tsk  ->  t_pqtsE  —  _NULL  )  pq  ->  t_fqtsk  -  tak; 
else  tsk  ->  t_pqtsk  ->  t_nqtsk  -  tsk; 
pq  ->  t  lqtsk  -  tsk; 

tsk  ->  I_xtmO  -  /*  no  execution  time  yet  */ 

tsk  ->  t_xtml  - 
tsk  ->  t_xtm2  -  0; 

pr  -  sptr  -  ss+ssiz-2*pcnt;  /*  initialize  execution  stack  &  t_ps  */ 

tsk  ->  t_ps.sys_sp  - 

sp  -  sptr  -  sizeof (  struct  t_xstck  ); 

sp  ->  t_xbp  -  ss  +  ssiz; 

sp  ->  t_xbase  -  ss; 

while (  pent —  ) *pr++  -  *padr++; 

for(  i  -  0,  s  -  fitsk  ->  t_ps;  i++  <  sizeof (  struct  sys_parm  );  )*s  -  0; 

tsk  ->  t_ps.sy8_ds  - 

tsk  ->  t_ps.sys_es  - 

tsk  ->  t_ps.sys_ss  - 

sp  ->  t_xds  - 

sp  ->  t_xes  -  _tsk  ->  t_ps.sys_ds; 

sp  ->  t_xdi  - 

sp  ->  t_xsi  - 

sp  ->  txdx  - 

sp  ->  t_x cx  - 

sp  ->  t_xbx  - 

sp  ->  t_xax  -  _NULL; 

sp  ->  t_xip  -  xadr; 

tsk  ->  t_ps.sys_cs  - 

sp  ->  txes  - 

_tsk  ->  t_ps.sys_cs; 

Isk  ->  t_ps.sys_pf  - 

sp  ->  t _ xpf  -  SYS_IF; 

tsk  ->  t_ps.sya_ip  - 
sp  ->  t_retip  -  fit _ halt; 

t _ syxit(  ficrtflg  );  /*  exit  system  state  */ 

return  tsk;  /*  return  */ 

err3:  mm_free (  tsk  ->  t_ps.sys_ss  ); 
err2:  mm_free(  tsk  ); 

errl:  t _ syxit (  ficrtflg  ); 

return  _NULL; 

) 

/* 

t  halt  terminate  task 

*7“ 

t  halt ( ) 

/* 

If  a  subtask  returns  into  its  orginal  stack,  control  will  pass  to  t _ halt. 

This  function  deletes  the  subtask  and  then  clears  the  sys_task  pointer  just 
before  returning  on  the  system  stack  (to  reenter  the  security  kernel) .  */ 

{ 

logical  haltflg;  /*  system  state  flag  storage  */ 

t _ syntrt  fihaltflg  );  /*  enter  system  state  */ 

t_rtmark(  fi_tsk  ->  t  ratsk  ->  t_xtm0  );  /*  accumulate  pseudo  time  */ 

t_del (  sys_task,  _F  J:  /*  delete  current  task  */ 

sys  task  -  _NULL;  /*  indicate  task  terminated  */ 

while (_T ) t_term( ) ;  /*  return  to  security  kernel  */ 

) 

/* 

t  del  delete  task 

*7 

t_del (  tsk,  st  ) 
struct  t_task  *tsk; 
int  st; 

/* 

Task  tsk  is  killed,  st  is  the  status  returned  to  the  calling  program. 

*1 

( 

♦define  tskf  (  (  struct  t  ftask  *  )tsk  )  /**  (t_ftask)  */ 
struct  t_task  *t;  7*  task  control  table  pointer  */ 

logical  delflg;  /*  system  state  flag  storage  */ 

t  syntr(  fidelflg  );  /*  enter  system  state  */ 

while (  (  t  -  tsk  ->  t_fdtsk  )  )t_del(  t,  st  );  /*  delete  subtasks  first  */ 

1 f (  tsk  ->  t_pstsk  )  /*  family  linkage  */ 

tsk  ->  t_pstsk  ->  t_nstsk  -  tsk  ->  t_nstsk; 
else  tsk  ->  t_ratsk  ->  t_ldt3k  -  tsk  ->  t_nstsk; 
if (  tsk  ->  t_nstsk  ) 

tsk  ->  t_nstsk  ->  t_pstsk  -  tsk  ->  t_pstsk; 
else  tsk  ->  t_ratsk  ->  t_fdtsk  -  tsk  ->  t  pstsk; 
if(  tBk  ->  t_pqtsk  )  /*  queue  linkage  *7 

tsk  ->  t_pqtsk  ->  t_nqtsk  -  tsk  ->  t_nqtsk; 
else  if(  (  tsk  ->  t_type&T_P  ) 

&&  {  _tschd  ->  t  sclsp[  tsk  ->  t_cls  ]  ->  t_fqtsk  --  tsk  )  ) 

_tschd  ->  t_scTsp[  tsk  ->  t_cls  ]  ->  t_fqtsk  -  tsk  ->  t_nqtsk; 
else  if(  (  tsk  ->  t_type&T_W  )  &&  (  _tschd  ->  t_fwtsk  — -  tsk  )  ) 

_tschd  ->  t_fwtsk  -  tsk  ->  t_nqtsk; 
else  if(  (  tsk  ->  t_typefiT_SW  )  &&  (  _tschd  ->  t_fswtsk  —  tsk  )  ) 

_tschd  ->  t  fswtsk  -  tsk  ->  t_nqtsk; 
else  if(  (  tsk  ->  t_typefiT_X  )  fifi  (  _tschd  ->  tfxtak  —  tsk  )  ) 

_tschd  ->  t_fxtsk  -  tsk  ->  t_nqtsk; 
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if(  tsk  ->  t_nqtsk  )tsk  ->  t_nqtsk  ->  t_pqtsk  -  tsk  ->  t_pqtak; 
else  if<  (  tsk  ->  t_typetT_P  ) 

fifi  (  _tschd  ->  t  sclspt  tsk  ->  t  els  ]  ->  t  lqtsk  —  tsk  )  ) 
_tschd  ->  t_8clsp(tsk  ->  t_clsT  ->  t_lqtsE  -  tsk  ->  t_pqtsk; 
else  if(  (  tsk  ->  t_type&T_W  )  &&  (  _tschd  ->  t_fwtsk  —  tsk  )  ) 
tschd  ->  t  lwtsk  -  tsk  ->  t_pqtsk; 
else  if(  (  tslc  ->  t_type&T_SW  )  &&  (  _tschd  ->  t_fswtsk  —  tsk  )  ) 
_tschd  ->  t_lswtsk  -  tsk  ->  t_pqtsk; 
else  if(  (  tsk  ->  t_type&T_X  )  &&  (  _tschd  ->  t_fxtsk  —  tsk  )  ) 
_tschd  ->  t_lxtsk  -  tsk  ->  t_pqtsk; 
t  -  sys_task;  /*  save  current  t_task  pointer  */ 

sys_task  -  tsk  ->  t_ratsk;  /*  set  ancestor  task  */ 
mm_free (  tsk  ->  t_ps.sys_ss  );  /*  free  stack  */ 


mm_free(  tsk  );  /• 

sys_task  -  t;  /* 

t _ syxit (  sdelflg  );  /’ 

return  F;  /* 


free  t_task  table  */ 
restore  current  task  pointer  */ 
exit  system  state  */ 
return  */ 


/* 

mm  aloe  memory  allocation 

*/ 

mm_aloc (In) 
unsigned  In; 

/* 

In  bytes  are  allocated  from  the  heap.  The  address  of  the  first  byte  is 
returned.  If  there  is  not  enough  available  memory  to  satisfy  the  request, 
_NULL  is  returned.  */ 

{ 

return  malloc(ln);  /*  allocate  storage  */ 

) 


/* 

mm_free  memory  deallocation 

*/ 

mm_free  (st) 
char  *st; 

/* 

st  is  the  address  returned  by  a  previous  call  to  function  mm_free.  The  storage 
previously  allocated  is  made  available  for  future  use.  The  normal  return  is 
_F.  E  is  returned  if  st  does  not  point  to  an  area  previously  allocated  by 
mm_aToc .  * / 

( 

return  free(st);  /*  deallocate  storage  */ 

) 


/* 

main  test  program 

*/ 

main ( ) 

/* 

This  function  serves  to  te3t  the  task  scheduler.  Two  tasks  are  created,  each 
of  which  Increments  a  variable.  The  original  task  continually  displays  the 
counts,  as  well  as  its  own  iteration  number.  Depressing  any  key  will  cause  a 
return  to  MS-DOS.  */ 


{ 


) 


int  Ctrl,  ctr2,  ctr3;  /*  counters  */ 

int  count ();  /*  counting  subroutine  */ 

int  param[  2  J;  /*  parameter  array  */ 

printf ("tasktest  (C)  1986  Ken  Berry-  All  Rights  Reserved\n") ; 

printf("Tele  task  scheduler:  1986  September  2  version  (DDJ  mod)\n\n"); 

t _ init();  /*  initialize  task  scheduler  */ 

Ctrl  -  ctr2  -  ctr3  -  0;  /*  initialize  counters  */ 
param[  0  ]  -  Cctrl;  /*  create  first  task  */ 
paramt  1  ]  -  1; 

t_crt (  count,  2,  fiparam,  256,  0,  0,  0); 
param[  0  )  -  4ctr2;  /*  create  second  task  * / 
pa ram (  1  j  -  2; 

t  ert (  count,  2,  &param,  256,  0,  0,  0); 

wKile (  !kbhit()  )  /*  loop  until  key  depressed  */ 

{ 

++ctr3;  /*  increment  main  loop  count  */ 

printf ("main  -  %d,  task  1  -  %d,  task  2  -  %d\n",  ctr3,  Ctrl,  ctr2  ); 


) 

getch  ( ) ; 

t _ term()  ; 

return  F; 


I*  discard  termination  character  */ 
/*  terminate  task  scheduler  */ 

/*  return  to  MS-DOS  *1 


count (ctr, inc) 
int  *ctr, inc; 

( 

while (_T) 

( 

*ctr  +-  inc; 

} 

) 


/*  infinite  loop  */ 
/*  update  counter  */ 


End  Listing  One 


Listing  Two 

Listing  2-  System  Definitions 
(C)  Copyright  1986  Ken  Berry. 

All  rights  reserved. 

Copies  may  be  made  for  non-commercial,  private  use  only. 


sys_parm 

struc 

;  register  storage  block 

rax 

dw  ? 

;  ax 

(general  register 

A) 

rbx 

dw  ? 

;  bx 

(general  register 

B) 

rex 

dw  ? 

;  cx 

(general  register 

C) 

rdx 

dw  ? 

;  dx 

(general  register 

D) 

rbp 

dw  ? 

;  bp 

(base  pointer) 

rsi 

dw  ? 

;  si 

(source  index) 

rdi 

dw  ? 

;  di 

(destination  index) 
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rsp 

dw  2 

;;  sp  (stack  pointer) 

res 

dw  2 

;;  cs  (code  segment) 

rds 

dw  2 

;;  ds  (data  segment) 

rss 

dw  2 

;;  ss  (stack  segment) 

res 

dw  2 

;;  es  (extra  segment) 

rpf 

dw  2 

;;  pf  (processor  flags) 

rsw 

dw  2 

;;  sw  (status  word) 

rip 

dw  2 

;;  ip  (instruction  pointer) 

rres 

dw  2 

: ;  unused 

sysjparm 

ends 

t_task 

t_type 

t_wttk 

t_cls 

t_pqtsk 

t_nqt  sk 

t_ratsk 

t_pstsk 

t_nstsk 

t_fdtsk 

t_ldtsk 

t_ps 

t_xtmO 

t_xtml 

t_xtm2 

t_axstk 

t  task 


struc 

;;  task  control  table 

db 

2 

; ;  task  type 

dw 

2 

; ;  wait  tick  count 

dw 

2 

;;  priority  queue  index 

dw 

2 

;;  prior  t_task  pointer 

dw 

2 

;;  next  t_task  pointer 

dw 

2 

;;  ancestor  t  task  pointer 

dw 

2 

;;  prior  sibling  t_task  pointer 

dw 

2 

;;  next  sibling  t_task  pointer 

dw 

2 

;;  first  desendant  t_task  pointer 

dw 

? 

;;  last  desendant  t_task  pointer 

db 

type 

sys  parm  dup  (2)  ;;  processor  status 

dw 

2 

;;  *  execution  time  accumulator 

dw 

2 

■  ■  * 

dw 

2 

; ;  * 

dw  2 
ends 

; ;  application  stack  pointer 

T_ATSK  equ  Olh 

T_X  equ  8  Oh 

T_W  equ  4  Oh 

T_P  equ  2  Oh 

t_SW  equ  lOh 


abreviated  task 
execute  wueue 
wait  queue 
priority  queue 
secondary  wait  queue 


t_scls  struc 

t_sfrq  dw  2 

t_sct  dw  2 

t_fqtsk  dw  2 

t_lqtsk  dw  2 

t  scls  ends 


scheduling  class  queue 
scheduling  frequency 
queue  length 
first  task  in  queue 
last  task  in  queue 


t_schd  struc 

t_xct  dw  2 

t_fxt sk  dw  2 

t_lxtsk  dw  2 

t_wct  dw  2 

t_fwtsk  dw  2 

t_lwtsk  dw  2 

t_swct  dw  2 

t_fswtsk  dw  2 

t_lswtsk  dw  2 

t_sclsl  dw  2 

t_sclsp  dw  2 

t  schd  ends 


scheduling  control  table 
execution  queue  length 
first  task  in  execution  queue 
last  task  in  execution  queue 
wait  queue  length 
first  t^sk  in  wait  queue 
last  task  in  wait  queue 
secondary . wait  queue  length 
first  task  in  secondary  wait  queue 
last  task  in  secondary  wait  queue 
scheduling  class  index  limit 
scheduling  class  array  pointer 


t_calln  struc 

t_nbp  dw  2 

t_nret  dw  2 

t_npO  dw  2 

t_npl  dw  2 

t_np2  dw  2 

t_np3  dw  2 

t_np4  dw  2 

t_np5  dw  2 

t_np6  dw  2 

t_np7  dw  2 

t  calln  ends 


near  function  call 
base  pointer  storage 
return  address 
parameter  0 
parameter  1 
parameter  2 
parameter  3 
parameter  4 
parameter  5 
parameter  6 
parameter  7 


t_xtsk  struc 

t_xbase  dw  2 

t_xes  dw  2 

t_xbp  dw  2 

t_xdi  dw  2 

t_xsi  dw  2 

t_xdx  dw  2 

t_xcx  dw  2 

t_xbx  dw  2 

t_xax  dw  2 

t_xds  dw  2 

t_xip  dw  2 

t _ xcs  dw  2 

t_xpf  dw  2 

t_retip  dw  2 

t  xtsk  ends 


execution  stack 

_base  (for  stack  overflow  detection) 

es 

bp 

di 

si 

dx 


ds 

ip 


Pi 

return  ip 


retn  macro  s 

ifnb  <s> 

db  0C2h 
db  high  s 
db  low  s 

else 

db  0C3h 

endif 


endm 


near  return 

pop  ip  &  adjust  sp 
*  adjustment  value 


pop  ip  only 


retf  macro  s 

ifnb  <s> 

db  OCCh 
db  high  s 
db  low  s 

else 

db  OCBh 

endif 

endm 


;;  far  return 

;;  pop  ip,  cs  £  adjust  sp 
: ;  *  adjustment  value 
. .  * 

; ;  pop  ip,  cs  only 


ilck  macro  reg, flag 

xchg  reg, flag  ;;  capture  token 
endm 

iowait  macro 

nop  ;;  I/O  delay 

endm 
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LiStillQ  TWO  (Listing  continued,  text  begins  on  page  16.) 

ays  entr 

macro  flag 

;  enter  system  function 

ifndef 

sys  ilck 

extrn  sys  ilck:byte 

endif 

mov  al# OFFh  ; 

;  **  system  task  interlock 

ilck  al, sys  ilck 

; ;  *  * 

mov  flag,al  ; 

endm 

;  save  asynchronous  status 

sys  exit 

macro  flag  ; 

;  exit  from  system  function 

local  exitl, exit2 

ifndef 

sys  ilck 

extrn  sys  ilck: byte 

endif 

ifndef 

t  astrm 

extrn  t  astrm: byte 

endif 

ifndef 

t  term 

extrn  t  term: near 

endif 

test  byte  ptr  t 

astrm, OFFh  ;;  *  test  for  application  terminated 

jnz  exitl 

.  * 

mov  byte  ptr  sys 

ilck, 0  ;;  exit  system  state 

jmp  short  exit2 

; ;  continue  application  task 

exitl : 

test  flag, OFFH 

;  **  test  for  more  stacked  system  tasks 

jnz  exit2 

•  *  * 

call  t  term 

;  terminate  application  task 

exit2 : 

;  macro  exit 

endm 

sys  sync 

macro  flag  ; 

;  synchronize  system  resource 

ifndef 

t  sync 

extrn  t  sync:near 

endif 

lea  bx,flag  ; 

;  set  flag  offset 

call  t_sync 
endm 

;  suspend  task  until  token  obtained 

sys  sstk 

macro 

local  sstkl 

;  conditionally  establish  system  stack 

ifndef 

t  sstk 

extrn  t  sstk:near 

endif 

or  al,al 

;  *  test  for  system  task  interrupted 

jnz  sstkl 

;  * 

call  t  sstk 

;  establish  system  stack 

sstkl : 

push  ds 

;  **  set  es  -  ds 

pop  es 
endm 

•  *  * 

sys  sctx 

macro 

;  save  processor  context 

push  bx 

:  protect  bx 

push  cx 

;  protect  cx 

push  dx 

;  protect  dx 

push  si 

;  protect  si 

push  di 

;  protect  di 

push  bp 

;  protect  bp 

push  es 

;  protect  es 

cld 

;  clear  direction  flag 

sys_sstk 

endm 

;  conditionally  establish  system  stack 

sys  rctx  macro 

;  restore  processor  context  (except  ds) 

pop  es 

;  restore  es 

pop  bp 

;  restore  bp 

pop  di 

;  restore  di 

pop  si 

;  restore  si 

pop  dx 

:  restore  dx 

pop  cx 

;  restore  cx 

pop  bx 

;  restore  bx 

pop  ax 
endm 

;  restore  ax 

sys  rctx 

macro 

;  restore  processor  context 

sys  rctx 

;  restore  context  (except  d3) 

pop  ds 
endm 

;  restore  ds 

sys_ient 

macro  flag 
push  ds 

;  protect  ds 

push  ax 

;  protect  ax 

mov  ax, dgroup 

;  *  establish  data  addressability 

mov  ds,ax 

;  * 

sys  entr  flag 

;  enter  system  state 

sti 

;  interrupts  on 

sys_sctx 

endm 

;  save  processor  context 

sys  iret 

macro  flag 
local  iretl 

ifndef 

t  astrm 

extrn  t  astrm: byte 

endif 

cli 

;  interrupts  off 

test  byte  ptr  t 

astrm, OFFh  ;;  *  test  for  application  not  terminated 

jz  iretl 

;  * 

test  flag, OFFh 

;  **  test  for  system  state  interrupted 

jnz  iretl 

.  *  * 

sti 

;  interrupts  on 

retn 

;  return  to  task  management 

iretl : 

sys  rctx 

;  restore  processor  context 

iret 

endm 

;  resume  interrupted  task 

dseg 

macro 

dgroup 

group  data 

data 

segment  word  public  'data' 
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assume  ds: dgroup, es  : dgroup, ss :dgroup 
endm 


endds 

macro 

data 

ends 

endm 

pseg 

macro 

pgroup 

group  prog 

prog 

segment  byte  public  'prog 

assume  cs: pgroup 

endm 

endps 

macro 

prog 

ends 

endm 

End  Listing  Two 


Listing  Three 


Listing  3  Scheduling  Algorithm  (Assembly  Subroutines) 

(C)  Copyright  1986  Ken  Berry. 

All  rights  reserved. 

Copies  may  be  made  for  non- commercial,  private  use  only. 


include  tele. mac  ;  system  definitions  (listing  2) 

extrn  t_astrm:byte  ;  application  task  termination  flag 
extrn  t_rtmark : near  ;  update  pseudo  time  accumulator 
extrn  t _ krnlrnear  ;  security  kernel 


sys_task 

sys_tsch 

sys_ilck 

sys_asbs 

sys_dgrp 

sys_ssbs 

sys_sssz 

sys_sstp 

sys_stat 

t_mnxtm 

t_rels 

t_spnd 

t_syxtm 

t_term 

t_wait 

t_wqupd 

t _ crtss 

t _ crtsp 

t _ dspap 

t _ dspsy 

t _ sstk  ; 

t _ syntr 

t _ syxit 


equ  500 
equ  1024 


k  ;  current  task  pointer 
h  ;  task  scheduling  table  pointer 
k  ;  system  task  interlock 
s  ;  application  stack  base 
p  ;  data  segment  storage 
s  ;  system  stack  base 
z  ;  system  stack  size 
p  ;  system  stack  top 
t  ;  original  register  block 
;  minimum  execution  time 
;  release 
;  suspend 

:  system  pseudo  time  accumulator 
;  reschedule 
;  wait 

;  wait  queue  update  task  pointer 
s  ;  current  task  ss  storage 
p  ;  current  task  sp  storage 
p  ;  dispatch  application 
y  ;  dispatch  system 
;  establish  system  stack 
r  ;  enter  system  state 
t  ;  exit  system  state 

;  minimum  execution  time 
;  system  stack  size 


t _ crtss 

t _ crtsp 

sys_stat 

3ys_dgrp 

sys_task 

sys_tsch 

sys_asbs 

sys_ssbs 

sys_sssz 

sys_sstp 

sys_ilck 

t_wqupd 

t_syxtm 


dw  0  ;  dx  storage 

dw  0  ;  ss  storage 

dw  0  ;  sp  storage 

dw  0  ;  current  task  ss  storage 

dw  0  ;  current  task  sp  storage 

db  type  sys_parm  dup  (0)  ;  original  register  block 

dw  0  ;  data  segment  storage 

dw  0  ;  current  task  pointer 

dw  0  :  task  scheduling  table  pointer 

dw  0  ;  application  stack  base 

dw  stkbs  ;  system  stack  base 

dw  STKLN  ;  system  stack  length 

dw  STKLN  ;  system  stack  top 

db  OFFh  ;  system  task  interlock 

dw  0  ;  wait  queue  update  task  pointer 

dw  3  dup  (0)  ;  system  pseudo  time  accumulator 

dw  MINXTM  ;  minimum  execution  time 

db  STKLN  dup  (0)  ;  system  stack 

db  type  t_task  dup  (0)  ;  main  task  control  table 


t _ dspap (ss, sp) 

selector  ss; 
unsigned  sp; 

ss  and  sp  are  placed  in  the  stack  registers.  Then  the  other  registers  are 
restored  from  the  new  stack.  Control  passes  to  the  restored  task.  The  return 
address  is  left  at  the  top  of  the  system  stack.  Therefore  the  restored  task 

may  use  the  system  stack  to  return  to  the  caller  of  t dspap.  ax  may  contain  a 

return  code  in  this  case. 

t _ dspap  proc  near 

push  bp  ;  protect  bp 

mov  bp,sp  ;  establish  parameter  addressability 

mov  ax, [bp] . t_np0  ;  set  application  stack 
mov  bx, [bp] .t_npl 
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Listing  Three 

(Listing  continued,  text  begins  on  page  16.) 

mov  sys  astp. 

3p  ;  store  current  top  of  system  stack 

cli 

mov  as, ax 

mov  sp,bx 

mov  bp,  sp 

;  enable  interrupts 

or  [bp] .t  xpf 

0200h 

pop  sys  asbs 

sti 

sys  rctx 

;  restore  context 

cli 

;  interrupts  off 

mov  byte  ptr 

sys  ilck,0  ;  exit  system  state 

mov  byte  ptr 

t  astrm, 0  ;  initialize  application  interval 

pop  ds 

;  restore  ds 

iret 

;  execute  task 

t  dspap  endp 

comment  ~ 

t  terro()  F 

t  spnd (tp)  tp 

t  wait (tp)  tp 

unsigned  tp; 

t_rels{)  _E 

All  of  these  functions 

are  similar.  The  processor  registers  are  stored  on 

the  stack,  which  is 

then  adjusted  to  match  the  pattern  for  interrupt 

returns.  Finally  the  system  stack  is  established.  The  functions  differ  in 

the  code  returned  to 

the  caller  of  function  t  dspap.  t  dspap  restores 

the  registers  and  returns  control  to  the  caller  of  these  functions.  The 

returned  value  is  shown  with  the  appropriate  call  above,  tp  is  only  used 

with  t  spnd  and  t  wait. 

It  is  the  number  of  system  ticks  to  wait  before 

executing  the  task  a 

gain,  t  wait  functions  like  t  spnd,  except  that  t  rels 

is  invoked  immediately. 

~ 

t  term  proc  near 

call  t  trmap  ;  protect  registers 

xor  ax, ax 

?  return  F 

ret 

t  term  endp 

t  spnd  proc  near 

mov  spdss, ss 

;  store  stack  pointers 

mov  spdsp, sp 

call  t  trmap  ;  protect  registers 

mov  es, spdss 

;  return  tick  count 

mov  si, spdsp 

mov  ax, word  ptr  es:[si+2] 

push  ds 

;  3et  es  -  ds 

pop  es 

ret 

;  return 

t_spnd  endp 

t  wait  proc  near 

push  bp 

;  protect  bp 

mov  bp, sp 

;  establish  stack  addressability 

mov  ax, [bp] . 

npO  ;  suspend  task 

push  ax 

call  t  spnd 

mov  sp,  bp 

;  unload  stack 

pop  bp 

;  restore  bp 

t  rels  proc  near 

call  t  trmap  ;  protect  registers 

xor  ax, ax 

;  return  E 

dec  ax 

ret 

t  rels  endp 

t_wait  endp 

comment  ~ 

t _ dspsy  () 

A  call  to  function  t  trmap  is  made  so  that  after  the  registers  are  stored  in 

the  application  stack 

(and  the  system  stack  is  made  current),  control  passes 

to  function  t  krnl. 

the  system  security  kernel.  Control  will  return  from 

t _ dspsy  when  the  calling  task  is  resumed.  Nothing  is  returned. 

t  dspsy  proc  near 

mov  ax, offset 

pgroup:t  krnl  ;  branch  to  system 

push  ax 

sub  sys  sstp. 

2  ;  adjust  system  stack  (for  "pop  bp"  in  t _ sstk) 

comment  ~ 

t _ trmap  ( ) 

The  machine  registers 

are  stored  on  the  application  stack.  Then  the  system 

stack  is  made  current. 

The  return  address  from  the  call  to  t  trmap  is  put  on 

the  system  stack  before 

returning  to  it.  Nothing  is  returned. 

t  trmap  proc  near 

mov  byte  ptr 

sys  ilck,0FFh  ;  force  system  state 

mov  tmrdx,  dx 

;  save  dx 

pop  dx 

;  set  return  address  (from  t  trmap) 

push  cs 

;  protect  cs 

pushf 

;  protect  flags 

push  ds 

;  protect  ds 

push  ax 

;  protect  ax 

push  bx 

;  protect  bx 

push  cx 

;  protect  cx 

push  tmrdx 

;  protect  dx 

push  si 

;  protect  si 

push  di 

;  protect  di 

push  bp 

;  protect  bp 

(continued  on  page  64) 
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Listing  Thr©©  (Listing  continued,  text  begins  on  page  16.) 

push  es 

protect  es 

push  dx 

restore  return  address  to  stack 

mov  bp, sp  ; 

establish  stack  addressability 

mov  ax, (bp) .t  xip  ;  adjust  stack  for  interrupt  return 

xchg  ax, (bp) ,t_xpf 
mov  (bp) . t_xip, ax 

comment  - 

t  sstk() 

The  current  application  stack  pointers  are  stored.  Then  the  system  stack  is 

established  as  the  current 

stack.  The  return  address  from  the  call  is  placed 

on  the  system  stack  before 

returning  into  it.  Nothing  is  returned. 

t  sstk 

proc  near 

pop  dx  ; 

unload  return  address 

push  sys  asbs 

protect  stack  protection  reference 

mov  bx, ss  ; 

mov  cx,sp 

set  application  stack  registers 

mov  ax, sys  ssbs 
cli 

;  set  system  stack 

mov  sys_asbs,ax 
push  ds 

pop  ss 

mov  sp, sys_sstp 
sti 

pop  bp 

restore  bp 

mov  t  crtss,bx 

;  store  current  ss 

mov  t  crtsp,cx 

;  store  current  bp 

push  dx-  ; 

ret 

return  to  caller 

t  sstk 

endp 

t  trmap 

endp 

t _ dspsy 

endp 

comment  ~ 

t  sync (fig) 

char  *flg 

A  wait  loop  will  be  entered  until  the  required  resource  i.i  available.  This  is 

indicated 

by  fig  containing  0x00.  OxFF  is  stored  to  prevent  any  other  tasks 

from  acquiring  the  resource.  The  resource  is  released  by  resetting  fig  to 

0x00. 

t_sync 

proc  near 
push  bp 

protect  bp 

mov  bp, sp 

establish  stack  addressability 

mov  bx, (bp) . t_np0  ;  set  pointer  to  resource  flag 

syncl : 

mov  al, OFFh 

interlock  token 

ilck  al,<byte  pt 

r  [bx]> 

or  al,al 
jz  sync2 

test  for  token  acquired 

xor  ax, ax 
inc  ax 

wait  for  1  system  tick 

push  ax 
call  t  spnd 
mov  sp,bp 
jmp  syncl 

continue 

sync2 : 

pop  bp  ; 

restore  bp 

call  t  rels 

release  task 

ret 

return 

t  sync 

endp 

comment  ~ 

t  syntr(flg) 

char  *flg 

This  function  expands  the 

sys_entr  macro  for  use  by  c  functions . 

t _ syntr 

proc  near 
push  bp 

protect  bp 

mov  bp, sp  ; 

establish  stack  addressability 

mov  bx, (bp) . t_np0  ;  set  flag  address 

sys  entr  <byte  ptr  (bx]>  ;  enter  system  state 

pop  bp 

restore  bp 

ret 

return 

t _ syntr 

endp 

comment  - 

t  syxit(flg) 

char  *flg 

This  function  expands  the 

sys  exit  macro  for  use  by  c  functions. 

t _ syxit 

proc  near 
push  bp 

protect  bp 

mov  bp, sp  ; 

establish  stack  addressability 

mov  bx, (bp) . t_np0  ;  set  flag  address 

sys  exit  <byte  ptr  [bx)>  ;  exit  system  state 

pop  bp 

restore  bp 

ret  ; 

return 

t _ syxit 

endp 

endps 

End  Listing  Three 

end 
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LiStlnQ  FOUr  (Listing  continued,  text  begins  on  page  16.) 

Listing  4 

High  Resolution  Clock 

(C)  Copyright  1986  Ken  Berry. 

All  right 

reserved. 

Copies  may  be  made  for  non- 

commercial,  private  use  only. 

include  tele. mac 

;  system  defintions  (listing  2) 

extrn  t  syxtm:word  ;  system  execution  time  accumulator 

extrn  sys  dgrp:word  ;  data  segment  storage 

extrn  sys_stat : word  ;  original  register  block 

public  t  tick  ; 

system  tick  interrupt  service 

public  t  astrm  ; 

application  task  termination  flag 

public  tmr  dspl 

physical  display  pointer 

public  tmr  dvsr 

timer  period 

public  tmr  ilck 

tick  service  reentrant  interlock 

public  tmr  sync 

synchronization  function  address 

public  tmr  tkct 

tick  clock 

public  tmr  xtm  ; 

tick  service  execution  time 

public  tmr  clr 

reset  time  base  generation 

public  tmr  int 

timer  initialization  function 

public  tmr  rst 

timer  termination  function 

public  tmr  sts 

read  timer  status 

public  tmr  tmr 

restart  hardware  timer 

public  t  rdclk  ; 

read  high  resolution  clock 

public  t  rtactg 

psuedo  time  accumulator  pointer 

public  t  rtraark 

mark  execution  interval 

public  t  rdclk 

read  real  time  clock 

public  td  ref  ;  clock  update  tick  reference  count 

public  td  tct  ;  clock  tick  timer 

public  td  set  ; 

set  time  of  day  clock 

public  td  upd  ; 

update  time  of  day  clock 

public  w  cdspl 

physical  display  update  function 

public  w _ sync  ; 

physical  display  synchronization 

RLCINT 

equ  8 Oh 

relocated  alternate  time  base  interrupt 

TMRINT 

equ  8  ; 

hardware  timer  interrupt 

TMRPRT 

equ  4  Oh 

timer  (8253)  port 

TMRPRD 

equ  19912 

timer  period  (60  Hz  rate) 

; TMRPRD 

equ  9956 

timer  period  (120  Hz  rate) 

INTPRT 

equ  20h 

interrupt  controller  (8259)  port 

TMRMSK 

equ  Olh  ; 

hardware  timer  interrupt  mask 

INTEOI 

equ  2 Oh  ; 

interrupt  termination  value 

DSPCT 

equ  1 

60  Hz  interrupt  rate 

; DSPCT 

equ  2 

120  Hz  interrupt  rate 

IDVO 

equ  3 

tmr  idvO  divisor 

ISKPO 

equ  77  6 

tmr  ict  correction  value 

ISKP1 

equ  11  ; 

tmr  idvl  correction  value 

ISKP2 

equ  38  ; 

tmr_idv2  correction  value 

dseg 

tmr  tkct 

dw  0 

interrupt  counter 

tmr  dct 

db  0 

display  counter 

tmr  ict 

dw  0  ; 

tick  clock  (for  time  base  generation) 

tmr  dvsr 

dw  TMRPRD 

1/2  timer  period 

t  astrm 

db  OFFh 

application  task  termination  flag 

tmrflg 

db  OFFh 

system  state  flag  (t  tick) 

tmr  ilck 

db  0 

tick  service  reentrant  interlock 

tmr  idvO 

db  0 

clock  time  base  generator 

tmr  idvl 

db  0 

primary  alternate  time  base  generator 

tmr  idv2 

db  0 

secondary  alternate  time  base  generator 

tmr  dspl 

dw  0 

console  display  w  pwdw  pointer 

t  rtactg 

dw  0 

psuedo  time  accumulator  pointer 

t  rtrfct 

dw  0 

real  time  reference  count 

t  rttick 

dw  0 

tick  clock  phase 

tmr  xtra 

dw  3  dup  (0) 

tick  service  psuedo  time  accumulator 

tmrpxtm 

dw  0 

prior  psuedo  time  accumulator  pointer 

tmr  sync 

dw  offset  pgroup 

:w  sync  ;  synchronization  function  pointer 

td  ref 

dw  0 

clock  update  tick  reference  count 

td_tct 

dw  0  ; 

clock  tick  timer 

endds 

pseg 

comment  - 

t _ tick 

system  tick  service 

t _ tickW 

Control  only  comes  here  in 

response  to  an  interrupt  from  the  system  clock. 

This  function  serves  three 

purposes.  It  maintains  the  system  clock,  which 

provides 

the  current  date 

and  time  for  both  system  and  application  uses.  It 

also  performs  an  update  of  the  first  physical  display.  And  finally  it 

terminates  the  execution  interval  for  the  current  application  task. 

t _ tick 

proc  far 

;  reentrant  lockout 

assume  ss : nothing, d3 : nothing, es : nothing 

sti  ; 

interrupts  on 

push  ds 

protect  ds 

push  ax 

protect  ax 

mov  ax, dgroup 

establish  data  addressability 

mov  ds,ax 

assume  d3: dgroup 

mov  al, INTEOI  ; 

terminate  interrupt 

out  INTPRT, al 

ilck  al,tmr  ilck 

;  test  for  not  reentrant  call 

or  al,al 

jz  tick 

pop  ax  ; 

restore  ax 

(continued  on  page  74) 
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Listing  Four  (Listing  continued,  text  begins  on  page  16.) 

pop  ds 

restore  ds 

iret 

return  from  interrupt 

;  system 

interlock 

tick: 

mov  t  astrm, OFFh 

;  terminate  application  task 

3ys_entr  tmrflg 

enter  system  state 

;  set  machine  environment 

sys  sc  tx  ; 
push  bp  ; 
mov  bp,  sp  ; 
lea  ax, tmr  xtm  ; 

save  processor  context 
protect  bp 
mark  stack  location 
accumulate  psuedo  time 

push  ax 

call  t  rtmark 

mov  sp,bp 

mov  tmrpxtm,  ax  ; 

store  prior  pointer 

;  real  time  system  processing 

inc  tmr_dct 
mov  al,DSPCT 
xor  al,tmr  dct 
jnz  tick4 
mov  tmr  dct, al 

remove  display  harmonics 

push  tmr  dspl 

display  physical  window 

call  w  cdspl 
mov  sp,  bp 

restore  stack  pointer 

inc  tmr  ict  ; 

increment  interrupt  counter 

inc  tmr_tkct 

increment  tick  clock 

;  time  base  generation 

mov  ax,ISKP0 
xor  ax, tmr  ict 

long  term  time  base  correction 

jnz  tickl 
mov  tmr_ict,  ax 
call  tick5 

update  system  tick  clock 

tickl: 

inc  tmr_idvO 
mov  al,IDV0 
xor  al,tmr  idvO 

generate  clock  time  base 

jnz  tick3 
mov  tmr_idvO,  al 
call  tick5 

update  system  tick  clock 

inc  tmr  idvl 
mov  al, ISKP1 
xor  al,tmr  idvl 

primary  alternate  time  base  correction 

jnz  tick2 
mov  tmr  idvl,al 

int  RLCINT 

update  alternate  time  base 

inc  tmr  idv2 
mov  al, ISKP2 

secondary  alternate  time  base  correction 

xor  al,tmr  idv2 

jnz  tick2 
mov  tmr  idv2,al 

int  RLCINT 

update  alternate  time  base 

tick2 : 

int  RLCINT 

update  alternate  time  base 

;  terminate  interrupt  service 

tick3 : 

push  tmrpxtm 
call  t  rtmark 

restore  original  psuedo  time  accumulator 

mov  sp,bp 

pop  bp 

restore  bp 

test  tmrflg, OFFh 
jnz  tick4 

;  test  for  interrupted  system  task 

xor  ax, ax 

terminate  task 

mov  tmr  ilck,al 

enable  reentrance 

retn 

near  return  to  system  task  management 

tick4 : 

sys  rctx 

restore  processor  context 

cli 

interrupts  off 

mov  tmr  ilck,0  ; 

enable  reentrance 

pop  ds  ; 

restore  ds 

iret 

return  to  interrupted  task 

;  update 

system  tick  counter 

tick5 : 

mov  ax,td  tct 

test  for  no  overflow 

inc  ax 

cmp  ax,td_ref 
jne  ticks 
call  td  upd 

update  clock 

xor  ax, ax  ; 

mov  td  ref, ax 

reset  tick  counter 

mov  td  tct, ax 

tick6 : 

inc  td  tct 

increment  tick  counter 

retn 

return 

t  tick 

endp 

comment 

tmr  int 

initialize  timer 

tmr _ int ( ) 

All  data 

areas  necessary  for  clock  maintenance  are  initialized.  The  hardware 

timer  is 

programmed  for  the  appropriate  rate  and  its  interrupt  vector  is  made 

to  point 

to  sys  tmr.  The  o 

riginal  vector  is  relocated  and  will  be  used  by 

sys_tmr  as  the  alternate  time  base. 

tmr  int 

proc  near 

call  tmr  dsi  ; 

diable  interrupts 
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mov  ax,dgroup  ; 

set  data  segment 

raov  sys  dgrp, ax 

mov  ax,cs 

set  code  segment 

lea  si, ays  atat 

raov  [ si] . res, ax 

cli 

interrupts  off 

mov  tmr  ilck,0FFt 

;  lockout-  t  tick 

mov  bx, tmr  sync 

test  for  no  synchronization  function 

test  bx,bx 

jz  into 

lea  bx, tmr  sync 

synchronize  timer  interrupt 

call  [bx] 

jmp  short  inti  ; 

continue 

intO:  call  tmr  tmr  ; 

start  timer 

inti:  call  t  rdclk 

set  real  time  clock  phase 

mov  t  rttick, ax 

mov  t  rtrfct,ax 

set  reference  count 

mov  t  rtactg, offset  dgroupit  syxtra  ;  initialize  time  accumulator 

call  td  set 

set  current  time 

sti 

interrupts  on 

xor  ax, ax  ; 

form  0 

push  ds  ; 

protect  ds 

mov  ds,ax 

relocate  original  interrupt  vector 

mov  di,ax 

cli 

mov  ax, [ di+4 *TMRINT ) 

raov  [ di  +  4  *RLCINT 

,  ax 

mov  ax, [di+4*TMRIHT+2J 

mov  [di+4*RLCINT+2] , ax 

mov  ax, offset  pgroup:t  tick  ;  set  interrupt  service 

raov  [ di+4 ‘TMRINT 

,ax 

raov  ax,cs 

mov  [di+4*TMRINT+2] ,  ax 

sti  ; 

interrupts  on 

pop  d  s 

restore  ds 

call  tmr  eni  ; 

enable  interrupts 

ret  ; 

return 

tmr _ int  endp 

comment  ~ 

tmr _ clr  reset  time  base  generation 

tmr _ clr() 

The  time  base  adjustment  variables  are  reset.  This  function  is  to  be  called  by 

td  set  when  the  time  of  day  is  initially  set  from  a  continuous  clock.  Nothing 

is  returned. 

tmr  clr  proc  near 

xor  ax, ax 

zero  time  base  generation  variables 

mov  tmr  idv0,al 

mov  tmr  idvl,  al 

raov  tmr  idv2,al 

ret 

return 

tmr _ clr  endp 

comment  ~ 

tmr _ rst  reset  timer 

tmr _ rst  () 

The  original  interrupt  service  routine  is  restored  and  the  hardware  clock  is 

reprogrammed.  However,  the 

original  hardware  values  are  not  available  in  this 

edition.  Therefore  the  original  system  state  cannot  always  be  restored. 

tmr  rst  proc  near 

mov  tmr  ilck,0FFh  ;  lock  out  interrupt  service 

push  ds 

protect  ds 

xor  ax, ax 

restore  original  interrupt  vector 

raov  ds,ax 

mov  di,ax 

call  tmr  dsi  ; 

disable  timer  interrupt 

cli 

interrupts  off 

mov  ax,  [ di+4 *RLCINT] 

mov  [ di  +  4  *TMRINT 

,ax 

mov  ax, [di+4  *RLCINT+2] 

mov  [ di+4*TMRINT+2 ] ,  ax 

pop  ds  ; 

restore  ds 

xor  bx,bx 

restart  hardware  timer 

call  tmr  str 

sti 

interrupts  on 

call  tmr  eni  ; 

enable  timer  interrupt 

ret  ; 

return 

tmr _ rst  endp 

comment  - 

tmr _ tmr  restart  hardware  timer 

tmr _ tmr \\ 

Channel  0  of  an  8253  timer 

is  initialized  to  mode  3.  The  count  in  bx  is  then 

programmed. 

tmr  tmr  proc  near 

restart  timer 

mov  bx,tmr  dvsr 

set  tele  system  tick  period 

tmr  str  proc  near 

set  timer  period 

mov  al,20  ; 

reset  8253  (mode  0,  count  >-  8,192) 

out  TMRPRT+3 ,  al 

(>  6.8  msec] 

iowait 

out  TMRPRT, al 

mov  al,36h 

initialize  8253  (mode  3,  both  bytes) 

iowait 

76 

840 


Dr.  Dobb’s  Journal,  December  1986 


out  TMRPRT+3, al 
mov  al,bl 
iowait 

out  TMRPRT, al 
mov  al,bh 
iowait 

out  TMRPRT, a 1 
ret 

return 

tmr  str 

endp 

tmr _ tmr 

endp 

comment  ~ 

tmr  sts 

read  timer  status 

tmr _ sts  () 

The  returned  value  Is  the 

current  count  in  the  timer. 

tmr  sts 

proc  near 

;  read  timer  status 

mov  a  1,0  Oh 
out  TMRPRT+3,  al 

;  set  read  mode 

nop 

;  allow  timer  chip  to  recover 

in  al, TMRPRT 
mov  ah,al 
in  al, TMRPRT 
xchg  ah,al 

;  read  count 

ret 

?  return 

tmr _ sts 

endp 

comment  - 
tmr _ dsl 

disable  interrupt 

tmr _ dsi  () 

The  timer 

interrupt  is  disabled  at  the  8259  interrupt  controller. 

tmr  dsi 

proc  near 

cli 

;  interrupts  off 

in  al, INTPRT+1 
or  al, TMRMSK 
iowait 

out  INTPRT+1,  al 

;  disable  timer  interrupt 

sti 

;  interrupts  on 

ret 

;  return 

tmr _ dsi 

endp 

comment  ~ 
tmr _ eni 

enable  interrupt 

tmr _ eni  () 

The  timer 

interrupt  is  enabled  at  the  8259  interrupt  controller. 

tmr  eni 

proc  near 

cli 

;  interrupts  off 

in  al, INTPRT+1 

;  enable  timer  interrupt 

and  al, not  TMRMSK 

iowait 

out  INTPRT+1,  al 

sti 

;  interrupts  on 

ret 

;  return 

tmr  eni 

endp 

comment  ~ 
t_rdclk 

read  real  time  clock 

t_rdclk ( ) 

The  current  value  of  the 

real  time  clock  is  read  and  returned. 

DMAREG 

equ  0 

;  refresh  address  DMA  register 

t  rdclk 

proc  near 

rclclkO: 

mov  dx, DMAREG 

;  set  DMA  register  address 

call  t  rdclk 

;  read  time 

mov  bx, ax 

;  store  time 

call  t  rdclk 

;  read  time  again 

cmp  ah, bh 

;  test  for  interruption 

jne  rdclkO 
ret 

;  return 

t_rdclk 

endp 

t  rdclk 

proc  near 

cli 

;  interrupts  off 

in  al,dx 
mov  ah,al 
iowait 
in  al,dx 

;  read  time 

xchg  al,ah 
sti 

;  interrupts  on 

ret 

;  return 

t  rdclk 

endp 

comment 
t  rtmark 

mark  execution  interval 

t  rtmark (np) 

pointer 

np; 

The  number  of  refreshes 

since  the  last  call  to  t  rtmark  is  accumulated.  Then 

the  reference  count  is  reset,  np  points  to  the  area  that  will  accumulate  the 
number  of  refreshes  to  the  next  call.  The  returned  value  is  the  original 

accumulator  pointer. 

t_rtmark 

proc  near 
push  bp 

;  protect  bp 

mov  bp, sp 

;  establish  parameter  addressability 

(continued  on  page  80  J 
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Listing  Four  (Listing  continued,  text  begins  on  page  16.) 

call  tmr  dsi  ;  disable  timer  interrupt 
call  t_r3clk  ;  read  real  time  clock 
mov  bx, ax  ;  protect  current  count 

xchg  bx,t_rtrfct  ;  update  reference  count 
sub  ax,bx  ;  compute  execution  interval 

jnc  markl  ;  test  for  no  overflow 

neg  ax  ;  adjust  count 

markl:  mov  bx,t  rtactg  ;  accumulate  execution  time 

add  ax, [Ex] 
mov  [bx],ax 
jnc  markxit 
add  word  ptr  [bx+2],l 
Inc  markxit 
lnc  word  ptr  [bx+4] 

markxit:  mov  ax,bx  ;  return  orginal  pointer 

mov  bx, [bp].t  npO  ;  set  new  accumulator  pointer 
mov  t_rtactg,Bx 

call  tmr _ eni  ;  enable  timer  interrupt 

pop  bp  ;  restore  bp 

ret  ;  return 

t_rtmark  endp 


comment  - 

w _ cdspl  display  physical  buffer 

w _ cdspl (pw) 

struct  w_phys  *pw; 

Physical  window  pw  is  displayed.  This  function  is  called  by  the  system  tick 
clock  interrupt  service  function.  Nothing  is  returned. 


w _ cdspl  proc  near 

ret 

w _ cdspl  endp 

comment  - 
w _ sync 


synchronize  interrupt  to  display 


The  system  tick  clock  timer  is  adjusted  so  that  w _ dsply  executes  just  prior 

to  the  vertical  blanking  interval.  Nothing  is  returned. 


w sync  proc  near 

call  tmr _ tmr  ;  start  timer 

w sync  endp 


comment  ~ 
td  set 


set  time  of  day  clock 


The  clock  is  set  to  the  current  time.  Nothing  is  returned. 


td set  proc  near 

ret 

td set  endp 

comment  - 
td _ upd 


update  clock 


td _ upd  ( ) 

The  clock  is  updated  based  on  the  number  of  ticks  since  it  was  last  updated. 
The  normal  return  (ax)  is  _F.  _E  is  returned  if  the  call  was  locked  out. 


td upd  proc  near 

ret 

td upd  endp 


End  Listings 
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Listing  One  (Text  begins  on  page  104.) 

Listing  One 

General  string  comparison  routine  for  8086 
by  Ray  Duncan,  June.  1986 

Call  with:  DS:SI  -  address  of  stringl 

DX  -  length  of  stringl 
ES:DI  -  address  of  string2 
BX  -  length  of  string2 

Returns:  Z  and  S  flags  set  appropriately: 

Z  -  True  if  strings  are  equal 

or 

Z  -  False  if  strings  are  not  equal,  and 

S  -  True  if  stringl  <  string2 

S  -  False  if  stringl  >  string2 


sanpl: 


sanp2 : 
stranp 


proc 

mov 

cmp 

ja 

mov 


near 
cx,  hx 
dx,  bx 
scmpl 
cx,  dx 


repz  cmpsb 
jz  scmp 2 

ret 

sub  dx,bx 

ret 

endp 


Listing  Two 


set  length  to  canpare 
use  shorter  of  two  lengths 


now  corrpare  strings 
jump,  strings  equal  so  far 
return,  strings  not  equal,  Z-False 
compare  original  string  lengths 
return  with  S  and  Z  flags  set 

End  Listing  One 


Listing  Two 

General  string  comparison  routine  for  68000 
by  Rick  Wilton,  June  1986 

Call  with:  A0  -  address  of  stringl 

DO  -  length  of  stringl 

A1  -  address  of  string2 

D1  -  length  of  string2 

Returns:  D3  -  flag  (-1,0,1) 

-1  if  stringl  <  string2 
0  if  stringl  -  string2 
1  if  stringl  >  string2 


stranp 

move.b 

dl,d2 

;  set  d2  -  shorter  length 
;  d2  :-  length2 

anp.b 

d0,dl 

blt.s 

stranpl 

;  branch  if  length2  <  lengthl 

move.b 

d0,d2 

;  d2  :-  lengthl 

strcnpl 

subq.w 

•l,d2 

fcmi  .s 

stranp3 

;  branch  if  string  length-K) 

strcmp2 

anpm.b 

(aO) +,  (al)  + 

;  compare  strings 

dbne 

d2,strcmp2 

bne.s 

strcmp4 

;  branch  if  strings  unequal 

strcnp3 

anp.b 

d0,dl 

bne.s 

stranp4 

;  branch  if  lengths  unequal 

moveq 

rts 

10, d3 

;  stringl  -  string2,  return 

0 

stranp4 

fcml  .s 

stranp5 

;  branch  if  dl  <  dO 

moveq 

rts 

f-1, d3 

?  stringl  <  6tring2,  return 

-1 

stranp5 

moveq 

rts 

•l,d3 

;  stringl  >  string2,  return 

1 

End  Listing  Two 
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Listing  Three 

Title  EXEC  program  using  undocumented  MS-DOS  Interrupt  2EH 


This  little  demonstration  program  illustrates  the  undocumented 
MS-DOS  Int  2EH  route  to  the  ccmmand  interpreter  in  CCMMAND. CCM. 

In  this  example  we  just  pass  the  ccmmand  tail  of  the  line  that 
loaded  the  EXEC2E  program. 

by  David  Gwlllim  -  20  June  1986 

Appears  to  work  on  all  current  versions  of  MS-DOS  (2.X-3.1) 

Adapted  frcm  Turbo  Pascal  program  written  by  Russ  Nelson,  Potsdam,  NY. 


cseg 

segment 

org  100H 

assume 

cs : cseg, ds : nothing 

begin: 

jmp 

start 

db 

20  dup  ('STACK  ') 

stack 

equ 

$ 

stkseg 

dw 

0 

__xptr 

dw 

0 

msgl 

db 

'Beginning  DOS  Int 

;  force  assembler  to  provide 
;  CS  overrides  in  the  right  places 


;  save  SS  register 
;  save  SP  register 


Listing  Three 

(Listing  continued,  text  begins  on  page  104.) 


msg2  db 

'Terminating  DOS  Int 

2 Eh  Exec', 13, 10,  '$' 

start:  push 

cs 

/make  our  local  data  addressable 

pop 

ds 

mov 

dx, offset  msgl 

; display  sign-on  message 

mov 

ah,  9 

int 

21h 

mov 

sp, offset  stack 

; reset  SP  to  our  own  internal  stack 

mov 

bx, offset  cs: endcode 

;Get  the  offset  of  the  end  of  our  code 

shr 

bx,  1 

; divide  by  16  to  get  paragraphs 

shr 

bx,  1 

shr 

bx,  1 

shr 

bx,  1 

inc 

bx 

; round  paragraphs  up 

mov 

ah, 4ah 

; shrink  down  this  COM  program's 

int 

21h 

/memory  allocation  to  what's  needed 

mov 

stxseg,ss 

/save  our  current  SS  reg 

mov 

stkptr,  sp 

/  and  SP  reg  values 

mov 

si, 80h 

/let  DS:SI  point  to  the  ccmmand 

/to  be  executed 

int 

2  eh 

/undocumented  DOS  exec  interrupt 

/  any  error  code  is  now  in  AX 

mov 

ss,  stkseg 

/Restore  SS  and  SP  registers 

mov 

sp, stkptr 

push 

cs 

/restore  local  addressing 

pop 

ds 

mov 

dx, offset  msg2 

/say  we're  done 

mov 

ah,  9 

int 

21h 

mov 

ax, 4cC0h 

/exit  to  DOS 

int 

21h 

endcode  equ 

$ 

cseg  ends 

end 

begin 

End  Listing  Three 

Listing  Four 


Listing  Four 


The  following  little  program  can  set  an  environment  variable 
whose  name  is  the  first  command  line  argument,  and  whose  new 
value  is  the  second  command  line  argument.  For  example,  to 
set  environment  variable  XYZ  to  a  value  of  HELLO,  you  would 
run  this  program  using  the  command  SETVAR  XYZ  HELLO. 

The  ‘PURPOSE*  of  this  piece  of  code  is  to  illustrate  an  un¬ 
documented  DOS  interrupt  entry  point  (2Eh)  that  will  execute 
*ANY*  DOS  conmand  ‘WITHOUT*  having  to  load  another  copy  of 
COMMAND.COM.  Not  only  is  it  faster,  but  it  is  the  ONLY  way 
to  set  an  environment  variable  (short  of  peeking  and  poking 
around  into  memory) .  You  ‘CAN'T*  set  an  environment  variable 
with  the  ccmmand  exec ( "COMMAND . COM" ,  " / CSETXYZ=HELLO" )  because 
when  the  second  copy  of  CCMMAND.COM  is  loaded,  it  gets  its 
very  own  environment  (a  duplicate  of  the  parent's).  Although 
the  SET  ccmmand  WILL  modify  that  duplicate  copy,  it  won't 
modify  the  parent's! 

When  I  said  that  interrupt  2Eh  can  be  used  to  execute  ‘ANY* 

DOS  corrmand,  I  meant  just  that!  You  can  leave  off  the  filename 
extension  (as  you  normally  do  at  the  conmand  line),  and  it  will 
perform  the  normal  search  for  CCM,  EXE,  and  BAT  files  to  execute, 
or  even  execute  built-in  coirmands  as  we've  seen  above. 


Enjoy! 

Dan  Lewis,  owner 
Key  Software  Products 
440  Ninth  Avenue 
Menlo  Park,  CA  94025 
(415)  364-9847 

P.S.-  This  ‘IS*  an  undocumented 
NO  idea  if  3.xx  etc  support  it! 


feature"  of  DOS  2.xx.  I  have 


•include  <stdio.h> 

main  (argc,  argv) 
int  argc  ; 
char  *argv[]  ; 


Set_Var (argv(l] ,  argv [2])  ; 


Set_Var (variable,  value) 
char  ‘variable,  ‘value  ; 
{ 

char  setbfr[100] 
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_ 1 6-BIT 

Listing  Four 

(Listing  continued,  text  begins  on  page  104.' 

/*  Build  the  command  line:  “SET  <var>-<value>"  */ 

strcpy (setbfr,  "SET  ")  ; 
strcat (setbfr,  variable)  ; 
strcat (setbfr,  "-")  ; 
strcat (setbfr,  value)  ; 

/*  Now  use  INT  2Eh  to  execute  it!  */ 

Execute_String (setbfr)  ; 


/* - */ 

/*  The  really  interesting  stuff  starts  here....  */ 
/. - ./ 


Execute_String (s) 
char  *s; 

{ 

long  vec22,  vec23,  vec24  ; 
long  Get_Vec (vector)  ; 
static  char  bfr[81); 


/*  Concatenate  a  carriage  return  onto  end  of  command  line  */ 

strcpy (bfr  +  l,s)  ; 

*bfr  -  strlen(bfr  +  1)  ; 
strcat (bfr  +  l,"\r")  ; 

/*  preserve  cntrl-break,  terminate,  and  critical  error  vectors  */ 
vec22  -  Get_Vec (0x22)  ; 
vec23  -  Get_Vec (0x23)  ; 
vec24  -  Get_Vec (0x24)  ; 


Release_Memory  ()  ; 
Elxec  (bfr)  ; 


/*  necessary!  */ 

/*  execute  command  */ 


/*  reset  cntrl-break,  terminate,  and  critical  error  vectors  */ 
Set_Vec  (0x22,  vec22)  ; 

Set_Vec (0x23, vec23)  ; 

Set  Vec (0x24,  vec24)  ; 

) 


;  preserve  ds,  bp,  ss,  &  sp 

push  ds 

push  bp 

mov  cs:WORD  save_ss,  ss 

mov  cs:WRD  save_sp,  sp 

;  ds:si  ->CR/NULL-terminated  command  line  string 

mov  si,  [bp+4] 

int  2 Eh 

;  restore  preserved  registers 
mov  ss, cs:WORD  save  ss 

mov  sp,  cs:WORD  save  sp 


16-BIT 


Listing  Five 


(Listing  continued,  text  begins  on  page  104.) 


main  () 

( 

FILE  *f; 
int  reset; 


puts  ("Begin  test  -  opening  file  TEST. XX" 
f  -  fopen  ("test. xx",  "w"); 
if  (f  =  NULL) 

abort  ("open  failed"); 
reset  -  setstdio  (stdout,  f); 
fprintf  (stderr,  "invoking  LS\n");  / 

if  (forklp  ("ls.exe",  "Is",  NULL))  (  / 

restdio  (stdout,  f,  reset);  /* 


/*  stdout  <-  f  */ 

/*  can't  write  to  stdout  */ 
/*  run  LS  */ 

*  clean  up  if  cant  exec  V 


abort  ("exec  failed"); 


(void)  wait  ();  /*  wait  t 
restdio  (stdout,  f,  reset);  /*  stdout 
fclose  (f ) ; 

puts  ("Test  completed  -  LS  results  in  TEST. XX") 


/*  wait  til  LS  done  V 
/*  stdout  <-  original  value  V 


End  Listing  Five 


Listing  Six 


Listing  6  for  November  86  16-Bit  Column  in  DDJ 


Wildcard  filename  expansion  for  MS-DOS  2.00  and  later. 
By:  Randy  Langer,  MicroSphere  Technology 


ifndef  model 
model  equ 


;  if  default  model  (both  small) 

;  0  -  small  code,  small  data 
;  1  -  large  code,  small  data 
;  2  -  small  code,  large  data 
;  3  -  large  code,  large  data 


codeseg  segment  byte  public  'code' 
assume  cs:codeseg 

public  wildcard_ 

if  model  and  1 


save  frame  pointer 
point  to  our  stack 


model  and  2 


save_ss:dw 
save_sp:dw 
save_ds : dw 
save_bp:dw 


Rolease_Memory  () 


if  (Release  ()) 

< 

puts ("Release  Memory  Failure\n")  ; 
exit (1)  ; 


ax,cs 
ax, OOlOh 
es,ax 
bx,ds 
bx, lOOOh 
bx,ax 
ah, 4 Ah 
21h 
ax,  0 
R  Rtn 


ds 

ds,  [bp+6] 


bx, [bp+4] 
al, [bx] 
al,  al 
rtn  null 


bx 

dx, [bp+4] 
dx,  2 
ah, 26 
21h 

bx, [bp+4] 
cl, [bx+1] 
ah,  79 

byte  ptr  [bx] , 1 

not_lst 

byte  ptr  [bx] 

ah 


save  DS  if  large  data 

and  get  segment  of  struct  ptr 


get  offset  of  struct  ptr 
get  flag  byte 
see  if  high  bit  set 
if  so,  no  more  to  find 
save  reg  used  by  DOS  call 
get  current  DTA  addr 
do  it 

save  DTA  segment 
restore  ES 

save  for  later  restoration 
save  addr  of  old  DTA 

get  ptr  to  user's  struct 
point  past  flag  bytes 
set  "new"  DTA  addr 

get  entry  pointer  again 
set  search  attributes 
set  token  for  search  next 
if  this  is  really  search  next 
branch 

else,  set  flag 

and  set  token  for  search  first 
get  offset  to  filespec 


long  Get_Vec (vector)  /*  Uses  DOS  function  35h  to  fetch  an  interrupt  vctr  */ 
unsigned  vector  ; 


do  the  search 
get  addr  of  old  DTA 
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ifndef 

model 

; 

if  default  model  (both  small) 

model 

equ 

0 

0  -  small  code,  small  data 

1  -  large  code,  small  data 

2  -  small  code,  large  data 

endif 

3  -  large  code,  large  data 

codeseg 

segment  byte  public  'code 

assume 

cs : codeseg 

public 

wildcard_ 

if 

model 

and  1 

wildcard 

proc  far 

else 

wildcard 

proc  near 

endif 

push 

bp 

save  frame  pointer 

mov 

bp,  sp 

point  to  our  stack 

if 

model 

and  2 

push 

ds 

save  DS  if  large  data 

mov 

ds, [bp+6]  ; 

and  get  segment  of  struct  ptr 

endif 

mov 

bx, [bp+4 ] 

get  offset  of  struct  ptr 

mov 

al, [bx] 

get  flag  byte 

or 

al,al 

see  if  high  bit  set 

js 

rtn  null  ; 

if  so,  no  more  to  find 

push 

es 

save  reg  used  by  DOS  call 

mov 

ah,  4  7 

get  current  DTA  addr 

int 

21h 

do  it 

mov 

ax,es 

save  DTA  segment 

pop 

es  ; 

restore  ES 

push 

ds 

save  for  later  restoration 

push 

ax 

save  addr  of  old  DTA 

push 

bx 

mov 

dx, [bp+4] 

get  ptr  to  user's  struct 

add 

dx,  2 

point  past  flag  bytes 

mov 

ah,  2  6 

set  "new"  DTA  addr 

int 

21h 

mov 

bx, [bp+4] 

get  entry  pointer  again 

mov 

cl, [bx+1] 

set  search  attributes 

mov 

ah,  7  9 

set  token  for  search  next 

test 

byte  ptr  [bx] , 1  ; 

if  this  is  really  search  next 

jnz 

not  1st  ; 

branch 

inc 

byte  ptr  [bx] 

else,  set  flag 

dec 

ah 

and  set  token  for  search  first 

not  1st 

mov 

dx, [bx+45] 

get  offset  to  filespec 

if 

model 

and  2 

mov 

ds, [bx+47] 

endif 

int 

21h 

do  the  search 

pop 

dx 

get  addr  of  old  DTA 

pop 

ds 
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16-BIT 

Listing  Six  (Listing  continued,  text  begins  on  page  104.) 

push 

ax 

;  save  return  code  from  search 

char 

att  sel; 

mov 

ah, 26 

;  restore  DTA  ptr 

char 

tempdata [21]  ;  /*  don't  mess 

int 

21h 

pop 

ax 

;  restore  return  code 

char 

long 

long 

char 

char 

f_atts; 

pop 

ds 

;  get  back  segment  of  user  struct 

mov 

or 

jz 

mov 

bx, [bp+4 
ax,  ax 
rtn  name 
byte  ptr 

;  and  its  offest 
;  see  if  search  successful 
;  branch  if  so 
[bx],128  ;  else,  say  no  more 

filesize; 
filename [13]  ; 

‘filespec; 

xor 

ax,  ax 

;  return  null  ptr 

)  W_CARD; 

mov 

wild_end: 

dx,  ax 

;  in  case  of  large  data 

char  ‘wildcard (); 

End  Listing  Seven 

Listing  Eight 

pop 

ds 

endif 

Listing  8  for  November  1986  16-Bit  Column  in  DDJ 

pop 

bp 

;  restore  frame  pointer 

ret 

;  and  return 

/* 

rtn  name : 

*  WILDTEST.C  Program 

to  demonstrate  use  of  WILDCARD. ASM 

mov 

dx,  ds 

;  in  case  of  large  data  model 

*  by  Randy  Langer,  MicroSphere  Technology. 

mov 

ax,  32 

;  offset  to  file  name 

* 

add 

ax,bx 

;  add  to  struct  base 

*/ 

jrap 

wild  end 

;  and  exit 

♦include  "stdio.h" 

wildcard 

endp 

♦include  "wildcard .h" 

codeseg  ends 

end 

End  Listing  Six 

main(argc,  argv) 

Listing  Seven 

int  argc; 

STR  argv [ ] ; 

{ 

Listing  7  for 

November  86 

16-Bit  Column  in  DD'J: 

W  CARD  y; 

STR  s; 

/* 

while ( — argc) 

WILDCARD 

H  for  use 

with  WILDCARD. ASH 

y.filespec  -  *++argv; 

by  Randy 

Langer,  Microsphere  Technology 

y.att_sel  -  0x10; 

y  •  flag 

0; 

V 

while (s 

-  wildcard (&y) ) 
printf ("%s\n",  s) ; 

typedef  struct 

) 

) 

char  flag; 

End  Listings 
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_ STRUCTURED  PROGRAMMING 

Listing  One  (Text  begins  on  page  108.) 


Listing  1.  Contents  of  Turbo  Pascal  included  ProcParm.INC  file. 

{  ProcParm.INC  Version  1.1 

See  ProcParm. PAS  for  an  explanation. 

Author:  Mike  Babulic  CompuServe  ID:  72307,314  FIDO:  134/1 
3627  Charleswood  Dr.  N.W. 

Calgary,  Alberta, 

CANADA 
T2L  2C7 


] 


86/05/07 


A(J]  Tempo; 

I  I  +  1; 

J  :-  J  -  1 
END;  (*  IF  •) 

UNTIL  I  >  J; 

IF  Left  <  J  THEN  Sort (Left,  J); 

IF  I  <  Right  THEN  Sort (I, Right ) ; 
END;  (*  Sort  •) 


BEGIN 

Sort (FIRST,  LAST) 
END;  (*  Quicksort  *) 


( * - Use  the  ProcParm  Procedure 

($1  PROCPARM.INC) 

PROCEDURE  Dummy 1 (VAR  A  :  Vector;  P  :  INTEGER); 
BEGIN 

Cal 1_P r o cP a rra ; 


procedure  Call_ProcParra; 


begin 

Inline 

($89/ $EC/  ( 

$5D/  { 

$8B/$66/ $02/  { 

$87/$66/$04/  ( 

$89/$66/$02  { 


) 

end; 

Listing  Two 


MOV 
POP 
SS :MOV 


SS:XCHG  SP, [BP+4]  ) 
SS :MOV  (BP+2 ] , SP  ) 


» 

Procedure  Ptr) 

End  Listing  One 


END;  (*  Duranyl  •) 


PROCEDURE  Sort 1 (VAR  A 
BEGIN 

Dummy  1  (A,  P) ; 

END;  (*  Sortl  *) 


Vector;  P  :  INTEGER); 


SP, BP  ;Drop  down  one  level 

BP  ) 

SP,  [BP+2]  .-Exchange  Return  Addr  t 


Listing  2.  Contents  of  file  ProcPar.QK. 


C - 


—  Use  Procparm. qk 


*) 


( 


ProcPara.QK 


Version  1.0 


86/04/22 


PROCEDURE  Dummy 2 (VAR  A  :  Vector;  P 


INTEGER) ; 


Author:  Mike  Babulic  CompuServe  ID:  72307,314  FIDO:  134/1 
3827  Charleswood  Dr.  N.W. 

Calgary,  Alberta, 

CANADA 
T2L  2C7 

Inline ( 

$8B/$66/$02/ 

$87/ $66/ $04/ 

$89/ $66/ $02/ 

$89/ $EC/ 


) 


$5D/ 

$C3 


(  SS :MOV  SP, [BP+2] 

(  SS:XCHG  SP, [BP+4]  ) 
{  SS :MOV  [BP+2 ] , SP  ) 
{  MOV  SP,  BP 


.-Exchange  Return  Addr  6 
Procedure  Ptr) 


POP  BP 
RET 


.-Standard  Turbo  Return 
(if  no  Parameters) ) 

.-Near  Return  ) 

End  Listing  Two 


Listing  Three 


BEGIN 

($1  PROCPARM. QK) 
END;  (*  Dmtmy2  •) 


PROCEDURE  Sort2 (VAR  A  :  Vector;  P  :  INTEGER) ; 

BEGIN 

Dummy2 (A,  P) 

END;  (•  Sort2  •) 

(• -  Create_Array  - *) 

PROCEDURE  Create_Array (VAR  A  :  Vector;  Start,  Finish  :  INTEGER); 

(*  Create  a  reverse  sorted  array  *) 

VAR  I  :  INTEGER; 

BEGIN 

FOR  I  :-  Start  TO  Finish  DO 
A[I]  Finish  +1-1 
END;  (*  Create_Array  *) 


Listing  3.  Turbo  Pascal  demo  program  for  procedural  parameters. 

program  proc_param_derao; 

CONST  FIRST  -  1; 

LAST  -  1000; 

TYPE  Vector  -  ARRAY  [FIRST .. LAST]  OF  INTEGER; 

VAR  A  :  Vector; 

I,  Start,  Finish  :  INTEGER; 

(# - Shell_Sort - *) 


(• -  Display_Array  - *) 

PROCEDURE  Display_Array (VAR  A  :  Vector;  Start,  Finish  :  INTEGER); 

VAR  I  :  INTEGER; 

Dummy  :  CHAR; 

BEGIN 

WRITE ('Press  <CR>  to  view  array  members  ');  READ LN (Dummy) ;  WRITE LN, 
FOR  I  Start  TO  Finish  DO 
WRITE (A [ I ] : 8) ; 

WRITELN;  WRITELN; 

END;  (*  Display_Array  *) 


PROCEDURE  Shell_Sort (VAR  A  :  Vector) ; 

VAR  I,  J,  Offset,  Skip,  Tempo,  NData  :  INTEGER; 

In_Order  :  BOOLEAN; 

BEGIN 

NDATA  LAST  -  FIRST  +  1; 

Skip  NDATA; 

WHILE  Skip  >  1  DO  BEGIN 
Skip  Skip  DIV  2; 

REPEAT 

In_Order  :-  TRUE; 

FOR  J  :-  FIRST  TO  LAST  -  Skip  DO  BEGIN 
I  :-  J  +  Skip; 

IF  A[ J]  >  A [ I ]  THEN  BEGIN 
In_Order  :-  FALSE; 

Tempo  :  -  A [ I ] ; 

A [ I ]  :-A[J]; 

A [ J ]  : -  Tempo 
END;  (*  IF  *) 

END;  (*  FOR  •) 

UNTIL  In_Order ; 

END;  (*  WHILE  *) 

END;  (*  Shell_Sort  *) 

(* - - - Quicksort - *) 

PROCEDURE  Quicksort (VAR  A  :  Vector); 

PROCEDURE  Sort (Left,  Right  :  INTEGER) ; 

VAR  I,  J, 

Pivot,  Tempo  :  INTEGER; 


I  Left;  J  Right; 

Pivot  A [(Left  +  Right)  DIV  2); 
REPEAT 

WHILE  A[I]  <  Pivot  DO  I  :-  I  +  1; 
WHILE  Pivot  <  A [ J]  DO  J  J  -  1; 
IF  I  <-  J  THEN  BEGIN 

Tempo  A[I]; 

A[I]  :-  A [ J] ; 


(* - Show_Time - *) 

PROCEDURE  Show_Time; 

(*  Procedure  to  dislplay  time  *) 

TYPE  REGTYPE  -  record 

AX, BX, CX, DX, BP, 

DI,SI,DS,ED,  FLAGS  :  INTEGER 
END; 

TIME_REC  -  RECORD 

HOUR,  MIN,  SEC,  HSEC  :  BYTE 
END; 


VAR  REGISTER  :  REGTYPE; 

AH  :  BYTE; 

TIME  :  TIM£_REC; 

BEGIN 

AH  :-  $2C; 

WITH  REGISTER,  TIME  DO  BEGIN 
AX:-  AH  SHL  8; 

MS DOS (REGISTER) ; 

HOUR  Hi (CX) ; 

MIN  Lo(CX); 

SEC  Hi (DX) ; 

HSEC  :-  Lo(DX); 

WRITELN ('  at  '.HOUR, *  :  ',MIN, *  :  *,SEC, ' . *,HSEC) ; 
END; 

END;  (*  ShOW_Time  *) 


BEGIN 

ClrScr; 

WRITELN ( 'Array  has  index  range  of  ', FIRST, '  to  '.LAST); 

WRITE ('Enter  Index  of  first  element  to  view  ');  READ LN (Start ) ;  WRITELN; 
WRITE ( ' Enter  index  of  last  element  to  view  ');  READ LN (Finish) ;  WRITELN; 
IF  Start  <  FIRST  THEN  Start  FIRST; 

IF  (Finish  >  LAST)  THEN  Finish  :-  LAST; 

IF  Finish  <  Start  THEN  Finish  Start  +  (LAST  -  FIRST  +  1)  DIV  10; 
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WRITEIN ( 'Using  ProcParra  Procedure  ');  WRITEIN;  WRITELN; 

Create  Array (A,  FIRST,  LAST); 

MODULE  InnerWorking; 

WRITELN ( 'Using  Shell  Sort*); 

IMPORT  sqrt; 

WRITE ('Start  ');  Show  Time; 

Sortl (A, Of a (Shell  Sort)); 

EXPORT  Regression,  Slope,  Intercept,  R2; 

WRITE ('Finish');  Show  Time; 

VAR  Sum,  SuraX,  SumXX,  SuraY,  SumYY,  SumXY,  (*  Stat  summation  •) 

Display_Array (A, Start,  Finish) ; 

MeanX,  MeanY,  SdevX,  SdevY  :  REAL; 

Create  Array (A,  FIRST,  LAST); 

WRITELN ('Using  Quicksort'); 

PROCEDURE  Regression (VAR  X,  Y  i  ARRAY  OF  REAL;  (•  input  *) 

WRITE ('Start  •);  Show  Time; 

N,  LowerBound  :  CARDINAL  (*  input  •)); 

Sortl (A, Of a (QuickSortf)  ; 

WRITE ('Finish');  Show  Time; 

(•  Procedure  to  process  arrays  X  and  Y  *) 

Display  Array (A, Start,  Finiah) ; 

VAR  i  :  CARDINAL; 

Xs,  Ys  ;  REAL; 

WRITELN ('Using  ProcParra. QK  ');  WRITELN;  WRITELN; 

BEGIN 

Create  Array (A,  FIRST,  LAST); 

(*  Loop  for  stat  summation  *) 

WRITELN ( 'Using  Shell  Sort'); 

FOR  i  0  TO  N-LowerBound  DO 

WRITE ('Start  ');  Show  Tima; 

Xs  X[i] ;  Ys  Y[i); 

Sort2 (A, Of s (Shell  SorE)); 

Sum  : -  Sura  +  1.0; 

WRITE ('Finish');  Show  Time; 

SuraX  SuraX  +  Xs; 

Display_Array (A, Start,  Finish) ; 

SumY  SuraY  +•  Ys; 

SumXX  SumXX  +  Xs  •  Xs; 

Create  Array (A,  FIRST,  LAST); 

SumYY  SumYY  +  Ys  *  Ys; 

WRITE!* ruling  Quicksort'); 

SumXY  SumXY  +  Xs  •  Ys; 

WRITE ('Start  ');  Show  Time; 

Sort2 (A, Of • (Quicksort) ) ; 

(•  Calculate  intermediate  results  *) 

WRITE ( 'Finish' ) ;  Show  Time; 

Display_Array(A, Start, Finish) ; 

MeanY  s-  SuraY  /  Sum; 

EKD'  End  Listing  Three 

SdevX  s-  sqrt ((SumXX  -  SuraX  *  SuraX  /  Sum) /(Sura  -  1.0)); 

SdevY  sqrt {(SumYY  -  SumY  •  SumY  /  Sum) /(Sum  -  1.0)); 

END  Regression; 

Listing  Four 

PROCEDURE  Slope ()  :  REAL; 

{*  Function  that  returns  the  slope  of  the  best  fit  line  *) 

Listing  4.  Definition  and  implementation  modules  for  BestFit  library  which 

BEGIN 

uses  a  local  model  InnerWorking. 

IF  Sura  >  1.0  THEN 

DEFINITION  MODULE  BestFit; 

RETURN  (SumXY  -  MeanX  *  MeanY  •  Sum)  /  (SdevX  *  SdevX  *  (Sura  -  1.0)) 

ELSE  RETURN  0.0  (•  default  value  for  insufficient  data  •) 

END; 

EXPORT  QUALIFIED  Regression,  Slope,  Intercept,  R2; 

END  Slope; 

PROCEDURE  Regression (VAR  X,  Y  :  ARRAY  OF  REAL;  (*  input  *) 

PROCEDURE  Intercept ()  :  REAL; 

N,  LowerBound  :  CARDINAL  (•  input  *)); 

(*  Function  that  returns  the  intercept  of  the  best  fit  line  *) 

(*  Procedure  to  process  arrays  X  and  Y  *) 

BEGIN 

IF  Sura  >1.0  THEN 

PROCEDURE  Slope ()  ;  REAL; 

(*  Function  that  returns  the  slope  of  the  best  fit  line  *) 

PROCEDURE  Intercept ()  :  REAL; 

RETURN  MeanY  -  Slope ()  *  MeanX 

ELSE  RETURN  0.0  (•  default  value  for  insufficient  data  *) 

END; 

END  Intercept; 

<*  Function  that  returns  the  intercept  of  the  best  fit  line  *) 

PROCEDURE  R2()  :  REAL; 

PROCEDURE  R2()  :  REAL; 

(•  Function  that  returns  the  goodness  of  the  best  fit  line  *) 

(•  Function  that  returns  the  goodness  of  the  best  fit  line  *) 

VAR  R  j  REAL; 

END  BestFit. 

BEGIN 

IF  Sum  >  1.0  THEN 

IMPLEMENTATION  MODULE  BestFit; 

R  SdevX  /  SdevY  *  Slope (); 

FROM  MathLibO  IMPORT  sgrt; 

return  r  •  r  (continued  on  page  99) 
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(Listing  continued,  text  begins  on  page  108.) 

ELSE  RETURN  0.0  (•  default  value  for  insufficient  data  *) 

END; 

END  R 2; 

BEGIN 

(*  Initilaize  inner  module  by  setting  stat  summation  equal  to  zero  *) 

Sum  0.0;  SumXY  : -  0.0; 

SumX  0.0;  SumXX  0.0; 

SumY  0.0;  SuraYY  0.0; 

END  InnerWorking; 

end  BestFit.  End  Listing  Four 

Listing  Five 

Listing  5.  Turbo  Pascal  program  to  demosntrate  the  first  method  for 
external  menu  storage. 

program  test_raethodl ; 

(*  Program  to  test  first  method  for  external  menu  storage  *) 

TYPE 

STRING14  -  STRING! 14 ); 

STRING80  -  STRING [80]; 

Screen_Image  -  ARRAY  (0..24]  OF  STRING80; 

VAR  Shift_Row,  Shift_Col,  Sc  re  en_Line_Count  :  INTEGER; 

Screen  Line  :  Screen_Iraage; 

MenuFiTe  s  STRING14; 

PROCEDURE  Read_Menu(Menu_Filenarae  ;  STRING14 ; 

VAR  Shift_Row,  Shift_Col, 

Screen_Line_Count  :  INTEGER; 

VAR  Screen_Line  :  Screen  Image) ; 

(*  Procedure  to  read  menu  image  from  text  fiTe.  If  file  is  *) 

{*  nonexistant  the  program  will  halt.  *) 

CONST  MAX_SYMBOL  -  255; 

TYPE  CharSet  -  Set  OF  CHAR; 

Symbol_Table  -  ARRAY  [0. . MAX_SYMBOL]  OF  INTEGER; 


VAR  FileVar  :  TEXT; 

Line  :  STRING80; 

Table  :  Symbol_Table; 

I,  K,  Error_Code  ;  INTEGER; 

Symbol  Char  :  CHAR; 

OperatIon_Set  :  CharSet; 

Duplicate  :  BOOLEAN; 

C - *) 

PROCEDURE  INC (VAR  A  :  INTEGER); 

(*  Increment  integer  by  one  *) 

BEGIN 

A  A  +  1 
END;  (•  INC  *) 

(* - *) 


PROCEDURE  Upcase_Str (VAR  S  :  STRING80 ) ; 

(»  Convert  string  to  upercase  *) 

VAR  I  :  INTEGER; 

BEGIN 

FOR  I  1  TO  Length (S)  DO 
S[I]  Upcase (S[I) ) ; 

END;  (*  Upcase_Str  *) 

- *) 


FUNCTION  Extract  Number (Line  :  STRING80 ;  Skip  :  INTEGER; 

VAR  ErrorCode  :  INTEGER)  :  INTEGER; 

{*  Function  to  extract  an  integer  from  a  text  line  *) 

VAR  J  ;  INTEGER; 

BEGIN 

IF  Skip  >  0  THEN  Delete (Line, 1, Skip);  (*  Remove  chars  from  string  *) 
(*  Remove  blanks  *) 

WHILE  Line! 1J  -  '  '  DO 
Delete (Line,  1,1); 

(*  END  WHILE  *) 

Line  Line(l)  +  Line [2]  +  Line (3); 

VAL (Line, J, Error_Code) ; 

Extract_Number  : —  J 
END;  (*  Extract_Nuraber  *) 


PROCEDURE  Build_Screen (Line  :  STRING80; 

VAR  Screen_Line_Count  ;  INTEGER; 
VAR  Screen_Line  :  Screen_Iraage) ; 

VAR  J  :  INTEGER; 

Ch  :  CHAR; 

BEGIN 

IF  Length (Line)  >  0  THEN  BEGIN 

FOR  J  1  TO  Length (Line)  DO  BEGIN 
Ch  Line [ J] ; 

IF  Ch  IN  Operation_Set  THEN 

Line [ J]  CHR (Table (ORD (Ch) ]) ; 

END;  (*  FOR  *) 

Screen_Line[Screen_LJne_CountJ  i-  Line; 

INC (Screen_Line_Count) ; 

END; 

END;  (*  Build_Screen  •) 
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BEGIN 

Assign (FileVar,  Menu_Filenarae) ; 

Reset (FileVar) ; 

IF  ( IOResult  -  0) 

THEN  BEGIN 

Operation  Set  ( ' 1 ' , '0 ' , ' ♦ 1 , ' $' , ' % ' , '* ' , ' 4 ' , • /' , ' \' , ' I  1 , '-1 , ] ; 
(*  Initialize  screen  line  strings  •) 

FOR  I  0  TO  24  DO 

Screen  Line(IJ  : “  ''; 

(*  Initialize  symbol  table  entries  *) 

FOR  I  0  TO  MAX_SYMBOL  DO 
Tabled]  I; 

(*  Read  first  line  •) 

READ LN( FileVar,  Line); 

Upcase_Str (Line) ; 

WHILE  (NOT  Eof (FileVar) )  AND  (Line  <>  'START')  DO  BEGIN 
IF  Line[l]  IN  Operation_aet 
THEN  BEGIN 

Symbol_Char  Line[l]; 

K  ORD(Syrobol_Char) ; 

Table [K]  Extract_Number (Line, l,Error_code) ; 

IF  (Error_Code  >  0)  OR 

(NOT  (Table (K]  IN  [0..255]))  THEN 
Table [K )  Ord ('*'); 

END; 

(*  Read  next  line  *) 

READLN (FileVar,  Line); 

END;  (•  WHILE  *) 

Screen_Line_Count  0; 

Shift_Col  0; 

Shift_Row  0; 

(*  Read  next  line  that  may  contain  row/column  offset  *) 

FOR  I  1  TO  2  DO  BEGIN 
READLN (FileVar,  Line); 

Upcase_Str (Line)  ; 

IF  Pos ( ' SHIFTROW' ,  Line )  >  0  THEN  BEGIN 

Shift_Row  Extract_Number (Line, 8, Error_Code) ; 

IF  Error_Code  >  0  THEN  Shift  Row  0; 

END 

ELSE  IF  Pos ('SHIFTCOL', Line)  >  0  THEN  BEGIN 

Shift_Col  Extract_Number (Line, 8, Error_Code) ; 

IF  Error_Code  >  0  THEN  Shift  Col  0; 

END 

ELSE  Build_Screen (Line, Screen  Line  Count, Screen  Line); 

END;  (*  FOR  *)“ 

WHILE  NOT  EOF (FileVar)  AND  (Screen  Line  Count  <  25)  DO  BEGIN 
READLN (FileVar,  Line); 

Build_Screen(Line,Screen_Line_Count,Screen_Line) ; 

END;  (*  WHILE  •) 

Close (FileVar) ; 

END 

ELSE  Halt; 

END;  (•  Read_Menu  *) 


(' - *) 

PROCEDURE  DISP_STR(S  :  STRING80 ;  Row,  Col  :  INTEGER); 

(*  Procedure  to  write  a  string  to  the  screen  memory  •) 

TYPE  SCREEN80  -  ARRAY  (1 .  . 25,  1 . . 80,  1 . . 2]  OF  CHAR; 

VAR  MONODISP  :  SCREEN80  Absolute  $BOOO:0000; 

COLODISP  :  SCREEN80  Absolute  $B800:0000; 

I,  J.  Mode  :  INTEGER; 

BEGIN 

J  Length (S); 

Mode  MEM [$0040 :$0049] ; 

IF  Mode  IN  [2.  .3]  THEN 
FOR  I  1  TO  J  DO 

COLODISP [Row,  Col  +  1-1,1]  S|Z); 

IF  Mode  -  7  THEN 

FOR  I  1  TO  J  DO 

MONODISP [ Row, Col  +  I  -1,1]  S [ I] ; 

END; 

1* - *) 


PROCEDURE  Show_Menu (VAR  Shift_Row,  Shift_Col,  Screen_Line_Count  :  INTEGER; 
VAR  Screen_Line  :  Screen_Image) ;“ 

VAR  I  :  INTEGER; 

BEGIN 

FOR  I  : -  0  TO  Screen_Line_Count  DO 

DISP_STR (Screen_Line [ I ] , (I+Shift_Row+l) , (l+Shift_Col) ) ; 

END;  (*  Show_Menu  •) 

BEGIN 

ClrScr; 

WRITE( 'Enter  filename  ');  READLN (MenuFile) ;  WRITELN; 

Read_Menu (MenuFile,  Shift_Row,  Shift_Col, 

Screen_Line_Count,  Screen_Line); 

Show_Menu (Shift_Row,  Shi ft_Col, Screen  Line  Count,  Screen  Line); 

REPEAT  UNTIL  KeyPressed; 

END. 

End  Listing  Five 

Listing  Six 

Listing  6.  Turbo  Pascal  program  to  deraosntrate  the  second  method  for 
external  menu  storage. 

program  test_raethod2; 

(*  Program  to  test  the  second  method  for  external  menu  storage  *) 

TYPE 

STRING14  -  STRING] 14]; 

LSTRING  -  STRING [255]; 

Screen_Image  -  ARRAY  [0..24]  OF  LSTRING; 


VAR  Shift_Row,  Shift_Col,  Screen_Line_Count  :  INTEGER; 

Screen  Line  :  Screen_Image; 

MenuFile  :  STRING14 ; 

PROCEDURE  Read_Menu (Menu_Filename  :  STRING14 ; 

VAR  Shift_Row,  Shift_Col, 

Screen_Line_Count  :  INTEGER; 

VAR  Screen_Line  :  Screen  Image) ; 

(*  Procedure  to  read  menu  image  from  text  file.  If  file  is  *) 
(*  nonexistant  the  program  will  halt.  *) 

CONST  MAXSYMBOL  -  255; 

TYPE  CharSet  -  Set  OF  CHAR; 

Symbol_Table  -  ARRAY  [0. .MAX_SYMBOL]  OF  INTEGER; 


VAR  FileVar  :  TEXT; 

Line  :  LSTRING; 

Table  :  Symbol  Table; 

I,  K,  Error_CoHe, 

Upper_Left_Corner,  Upper_Right_Corner,  Lower  Left_Corner, 
Lower_Right_Corner,  Horizontal_Line,  VerticaI_Line, 
Cro8s_Bar,  Left_Tee,  Right_Tee, 

Up_Tee,  Down  Tee, 

Le?t  Edge,  Rlght_Edge, 

Vertrcal_Frames,  Horizontal_Frames,  Frame_Code, 

Number  :  INTEGER; 

Symbol_Char  :  CHAR; 

(* - *) 

PROCEDURE  INC (VAR  A  :  INTEGER); 

(•  Increment  integer  by  one  *) 

BEGIN 

A  A  +  1 
END;  (*  INC  *) 

(. - •) 


PROCEDURE  Upcase_Str (VAR  S  :  LSTRING); 
(*  Convert  string  to  upercase  *) 

VAR  I  :  INTEGER; 

BEGIN 

FOR  I  1  TO  Length (S)  DO 
S [ I ]  Upcase (S [ I] )  ; 

END;  (*  Upcase_Str  *) 


(* - ') 

FUNCTION  Ext ract_Number (Line  :  LSTRING;  Skip  :  INTEGER)  :  INTEGER; 
(*  Function  to  extract  an  integer  from  a  text  line  *) 

VAR  J,  SUM  :  INTEGER; 

BEGIN 


IF  Skip  >  0  THEN  Delete (Line, 1, Skip) ;  (*  Remove  chars  from  string  *) 
(*  Remove  blanks  *) 

WHILE  Line[l]  -  '  '  DO 
Delete(Line,l,l); 

(*  END  WHILE  •) 

SUM  0; 

J  1; 

WHILE  (J  <-  Length (Line) )  AND  (Line[J]  IN  [ ■ 0 ' -  - • 9 ' ] )  DO  BEGIN 
SUM  10  *  SUM  +  ORD (Line [J])  -  ORD('O'); 

INC ( J) 

END; 

Extract_Number  SUM 
END;  (*  Extract_Number  *) 


(* - *) 

FUNCTION  Get  Char_Code (S  :  LSTRING)  :  INTEGER; 

(*  Function  Eo  interpret  frame  symbol  and  return  its  ASCII  code  *) 
VAR  I,  ASCII_Code  :  INTEGER; 

BEGIN 


IF  S 

-  1 

'ULC1 

1  THEN 

ASCII  Code 

Upper  Left  Corner 

ELSE 

IF 

S 

- 

•URC' 

THEN 

ASCII 

Code 

;  - 

Upper_Right_Corner 

ELSE 

IF 

s 

- 

•llc* 

THEN 

ASCII' 

"Code 

:  - 

Lower~Left_Corner 

ELSE 

IF 

s 

- 

'  LRC ' 

THEN 

ASCII' 

"Code 

;  - 

Lower_Right_Corner 

ELSE 

IF 

s 

- 

'HLN' 

THEN 

ASCII' 

"Code 

:  - 

Horizontal  Line 

ELSE 

IF 

s 

- 

'  VLN ' 

THEN 

ASCII" 

Code 

:  - 

Vertical  Line 

ELSE 

IF 

s 

- 

'  CRS ' 

THEN 

ascii' 

Code 

:  - 

Cross_Bar 

ELSE 

IF 

s 

- 

'  LFT ' 

THEN 

ascii" 

'Code 

Left  Tee 

ELSE 

IF 

s 

- 

•rtt* 

THEN 

ascii' 

"Code 

:  — 

Right  Tee 

ELSE 

IF 

s 

- 

'UPT' 

THEN 

ascii" 

Code 

:  - 

Up_Tee 

ELSE 

IF 

s 

- 

•dnt' 

THEN 

ascii" 

"Code 

Down_Tee 

ELSE 

ASCII 

_Code  :■ 

-  ORD  ( 

•-');  1 

f*  error 

value  return  'A'  *) 

Get_Char_Code  ASCII_Code; 
END;  {*  Get_Char_Code  *) 


I* - *) 

PROCEDURE  Build_Screen (Line  :  LSTRING; 

VAR  Screen_Line_Count  ;  INTEGER; 

VAR  Screen_Line  ;  Screen_Image) ; 

VAR  I,  J,  K,  Long,  Count  :  INTEGER; 

Ch,  Symbol  :  CHAR; 

Build_Line,  Sub_String  :  LSTRING; 


BEGIN 

IF  Length (Line)  >  0  THEN  BEGIN 
J  s-  1; 

Long  Length (Line) ; 
Build_Line  "; 

Count  0; 

WHILE  J  <-  Long  DO  BEGIN 
Ch  UpCase (Line [J] ); 
CASE  Ch  OF 

'§'  :  BEGIN 
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Listing  Six  (Listing  continued,  text  begins  on  page  108.) 

Sub_String  11 ; 

FOR  I  1  TO  3  DO 

Sub_String  Sub_String  +  Line[J+I); 

J  J  +  3;  (*  advance  character  pointer  •) 

Symbol  C HR (Get  Char_Code (Sub_String) ) ; 

Build_Line  BuiId_Line  +  Symbol; 

INC (Count) ; 

END; 

'D'  t  BEGIN  (*  Duplicate  a  frame  character  *) 

Sub_String  Line[J+l]  +  Line[J+2)  +  Line[J+3]; 

J  t-  J  +  4;  (•  advance  character  pointer  *) 

Symbol  CHR (Get_Char_Code (Sub  String)); 

Sub_String  Line(J]  +  Line [ J+T ] ; 

J  J  +  1; 

K  Extract_Number (Sub_String, 0) ; 

IF  (K  >  0)  THEN  BEGIN 
Count  Count  +  K; 

FOR  I  1  TO  K  DO 

Build_Line  Build_Line  +  Symbol; 

END;  (•  IF  •) 

END; 

'S'  ;  BEGIN  (*  Skip  #  column  poaitions  *) 

Sub_String  Line[J+l]  +  Line(J+2]; 

J  J  +  2;  (•  advance  character  pointer  *) 

K  Extract_Number (Sub_String, 0) ; 

IF  (K  >  0)  THEN  BEGIN 
Count  Count  +  K; 

FOR  I  1  TO  K  DO 

Build_Line  Build_Line  +  '  '; 

END;  (*  IF*) 

END; 

""  :  BEGIN  (•  Display  text  •) 

INC ( J) ; 

WHILE  (Line [ J]  O  * |')  and  (J  <-  Long)  DO  BEGIN 
Build_Line  Build_Line  +  Line[J]; 

INC ( J) ;  INC (Count)  ” 

END;  (*  WHILE  •) 

Count  COunt  -  1; 

END; 

'#'  ;  BEGIN 

Sub_String  Line(J+l)  +  Line[J+2]; 

J  J  +  2;  (•  advance  character  pointer  •) 

K  Extract_Number (Sub_String, 0) ; 

IF  (K  <  Right  Edge)  AND  (Count  <  K)  THEN  BEGIN 
FOR  I  I  TO  K  -  Count  DO 

Build_Lina  Build_Line  +  '  '; 

Count  K; 

END;  (•  IF  *) 

END; 

'V*  :  BEGIN  (*  Draw  vertical  edges  •) 

Build_Line  CHR (Vertical_Line) ; 

FOR  I-:-  Left_Edge+l  TO  Right_Edge-l  DO 
Build_Line  Build_Line  +  1  '; 

Build_Line  Build_Line  +  CHR (Vertical_Line) ; 

END;  “ 

'H'  :  BEGIN  (*  Draw  horizontal  edge  *) 

Symbol  CHR (Horizontal_Line) ; 

FOR  I  Left_Edge+l  TO  Right_Edge-l  DO 
Build_Line  Build_Line  +  Symbol; 

END; 

END;  (*  CASE  *) 

INC ( J) ; 

WHILE  Line ( J)  -  '  '  DO  INC(J); 

END;  (*  FOR  *) 

Screen_Line(Screen_Line_Count]  Build_Line; 

INC  (Screen_Line_Count)  ; 

END; 

END;  (*  Build  Screen  *) 

BEGIN 

Assign (FileVar,  Menu_Filename) ; 

(*SI-«)  Reset (FileVar) ;  (*$I+*) 

IF  ( IOResult  -  0) 

THEN  BEGIN 

(*  Initialize  screen  line  strings  •) 

FOR  I  0  TO  24  DO 

Screen_Line (I )  '•; 

Left_Edge  1 ; 

Right_Edge  80; 

Vertical_Frames  : -  2; 

Horizontal_Frames  2; 

{*  Read  first  line  •) 

READLN (FileVar,  Line); 

Upcase_Str (Line)  ; 

WHILE  (NOT  Eof (FileVar) )  AND  (Line  <>  'START')  DO  BEGIN 
Symbol_Char  Line[l]; 

K  ORD (Syrabol_Char)  ; 

IF  Syrabol_Char  IN  [ 'R' , 'L', *H' , 'V' ]  THEN  BEGIN 
Number  Extract  Number (Line, 1) ; 

IF  (Error_Code  -  ”5)  THEN 
CASE  Symbol  Char  OF 

'R'  :  RTght_Edge  Number; 

'L'  ;  Left_Edge  Number; 

'H'  :  IF  (Number  IN  (1 . .21)  THEN 

Horizontal_Fraraes  Number; 

•V'  :  IF  (Number  IN  (1..2J)  THEN 

Vertical_Franve8  Number; 

END;  (*  CASE  *) 

END;  (*  IF  •) 

(*  Read  next  line  •) 

READLN (FileVar,  Line); 

END;  (*  WHILE  •) 

(*  Check  edges  *) 

IF  (Right_Edge  -  Left_Edge)  <-  4  THEN  BEGIN 
Left_Edge  1; 

Right_Edge  80; 

END;  (•  IF  *) 

Frame  Code  10  •  Horizontal_Frames  +  Vertical_Frames; 

(•  Select  frame  type  *) 

CASE  Frame_Code  OF 
11  :  BEGIN 

Upper_Left_Corner  218; 

Upper_Right_Corner  191; 

Lower _Left_Corner  192; 

Lower2Right_Comer  217; 

Horizontal  Line  196; 

Vertical_Llne  179; 

Cross_Bar  197; 


Left_Tec  195; 

Right_Tee  180; 
UpTee  193; 
Down_Tee  194; 

END; 

12  :  BEGIN 


Upper_Left_Corner  214; 
Upper_Right_Corner  183; 

Lower_Left_Corner  211; 
Lower_Right_Corner  189; 

Horizontal  Line  196; 
Vertical_Llne  186; 


Cross_Bar  215 

Left_Tee  199; 

Right_Tee  182, 
Up_Tee  208; 
Down_Tee  210; 

END; 

21  :  BEGIN 


Upper_Left_Comer  ; -  213; 
Upper_Right_Corner  184; 

Lower_Left_Comer  212; 
Lower~Right_Corner  190; 

Horizontal  Line  205; 


Vertical_Llne  179; 

Cro8S_Bar  216; 

Left_Tee  198; 

Right_Tee  181; 

Up_Tee  207; 

Down_Tee  209; 

END; 

22  :  BEGIN 

Upper_Left_Comer  201; 

Upper_Right_Corner  187; 

Lower_Left_Corner  200; 

Lower_Right_Corner  188; 

Horizontal  Line  205; 

Vertical_Llne  186; 

Cross_Bar  206; 

Left_Tee  204; 

Right_Tee  185; 

Up_Tee  202; 

Down_Tee  203; 

END; 

END;  (*  CASE  •) 

Screen_Line_Count  0; 

Shif t_Col  0; 

Shift~Row  0; 

(*  Read  next  line  that  may  contain  row/column  offset  •) 

FOR  I  1  TO  2  DO  BEGIN 
READLN (FileVar,  Line); 

Upcase_Str (Line) ; 

IF  Pos ( 'SHIFTROW' , Line)  >  0  THEN  BEGIN 
Shift_Row  Extract_Number (Line, 8) ; 

IF  Error_Code  >  0  THEN  Shift  Row  0; 

END  “ 

ELSE  IF  Pos ('SHIFTCOL', Line)  >  0  THEN  BECIN 
Shift_Col  Extract_Number (Line, 8) ; 

IF  Error_Code  >  0  THEN  Shift  Col  0; 

END  “ 

ELSE  Build_Screen (Line, Screen  Line  Count, Screen  Line); 

END;  (•  FOR  *) 

WHILE  NOT  EOF (FileVar)  AND  (Screen  Line  Count  <  25)  DO  BEGIN 
READLN (FileVar,  Line); 

Build_Screen < Line, Screen  Line  Count, Screen  Line) ; 

END;  (•  WHILE  •) 

Screen_Line_Count  Screen  Line  Count  -  1; 

Close (FileVar) ; 

END 

ELSE  BEGIN 

WRITE  rC~G); 

Halt; 

END; 

END;  (•  Read_Menu  •) 

I* - *) 

PROCEDURE  DISP_STR (S  :  LSTRING;  Row,  Col  :  INTEGER); 

(•  Procedure  to  write  a  string  to  the  screen  memory  •) 

TYPE  SCREEN80  -  ARRAY  (1 . .25, 1 . . 80, 1 . . 2]  OF  CHAR; 

VAR  MONODISP  :  SCREEN80  Absolute  $BOOO:0000; 

COLODISP  :  SCREEN80  Absolute  $B800:0000; 

I,  J,  Mode  :  INTEGER; 

BEGIN 

J  Length (S); 

Mode  MEM ( $0040 : $0049] ; 

IF  Mode  IN  (2.  .3)  THEN 
FOR  I  1  TO  J  DO 

COLODISP [Row, Col  +1-1,1]  S[IJ; 

IF  Mode  -  7  THEN 

FOR  I  1  TO  J  DO 

MOHCDISP [Row, Col  +1-1,1]  : —  S [ I ] ; 

END;  (•  DISP_STR  *) 

(* - *) 

PROCEDURE  Show_Menu (VAR  Shift_Row,  Shift_Col,  Screen_Line_Count  :  INTEGER; 
VAR  Screen_Lino  :  Screen_Image)  ;” 

VAR  I  :  INTEGER; 

BEGIN 

FOR  I  0  TO  Sc reen_Line  Count  DO 

DISP_STR(Screen_Line[I] , (I+Shift_Row+l) , (l+Shift_Col) ); 

END;  (•  Show_Menu  *) 

I* - *) 

BEGIN  (* - MAIN - *) 

ClrScr; 

WRITE('Enter  filename  ');  READLN (MenuFile) ;  WRITELN; 

Read_Menu (MenuFile,  Shift_Row,  Shift_Col, 

Screen_Line_Count,  Screen_Line) ; 

ShowMenu (Shift_Row,  Shift_Col, Screen_Line_Count,  Screen_Line) ; 

REPEAT  UNTIL  KeyPressed; 

end.  End  Listings 
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Critical  Error  Handling 

n  the  July  1986  16-Bit  Toolbox  col¬ 
umn,  I  quoted  a  letter  stating  that 
Computer  Innovations'  C  compiler, 
Version  1.31,  has  been  placed  in  the 
public  domain.  This  was  and  is  com¬ 
pletely  incorrect,  and  although  a  re¬ 
traction  has  already  been  printed 
elsewhere  in  DDJ,  I  wish  to  apologize 
to  Computer  Innovations  for  publish¬ 
ing  this  letter  without  checking  the 
facts — major  league  stupidity  on  my 
part. 

Comparing  Strings 

As  the  October  column  included  two 
listings  of  8086  string  searching  rou¬ 
tines,  I  thought  I'd  continue  the  trend 
this  month  with  8086-  and  68000- 
based  string  comparison  routines 
(Listings  One  and  Two,  page  86). 
These  procedures  work  very  much 
like  the  strcmp  library  function  in  C 
does  and  return  flags  indicating 
whether  the  first  string  is  less  than, 
equal  to,  or  greater  than  the  second 
string.  The  routines  are  not  com¬ 
pletely  symmetrical  but  do  indicate 
how  the  8086's  special  string  instruc¬ 
tions  can  provide  a  considerable 
space  and  speed  advantage  over  the 
68000’s  in  some  situations. 

Chauging  the  Master 
Environment 

The  October  1986  16-Bit  Toolbox  col¬ 
umn  included  a  brief  introduction  to 
environment  blocks  under  MS-DOS, 
and  at  that  time  I  promised  to  discuss 
several  different  ways  to  change  the 
master  environment  block  from  an 
executing  program.  After  consider¬ 
ing  the  matter  further,  I  have  decid¬ 
ed  to  break  that  promise,  and  this 
month  I  will  present  only  one  meth- 

by  Ray  Duncan 

od  (which  1  feel  to  be  the  safest  and 
most  portable). 

MS-DOS  has  an  undocumented  en¬ 
try  point,  software  interrupt  2eh, 
which  is  called  with  registers  ds:si 


pointing  to  a  command  string  in  the 
form  of  a  count  byte,  followed  by  AS¬ 
CII  text,  followed  by  a  carriage  return 
(which  is  not  included  in  the  count). 
This  entry  point  appears  to  be  a  sort 
of  back  door  to  the  command  inter¬ 
preter  buried  in  COMMAND.COM,  and 
if  you  pass  it  a  string  of  the  form  set 
name = parameter,  you  will  find  that 
the  system's  master  environment 
block  will  be  modified  rather  than 
just  your  program’s  local  environ¬ 
ment  block. 

Although  int  2eh  is  not  discussed  in 
any  Microsoft  reference  or  docu¬ 
mentation  I  have  seen  (even  the  OEM 
adaptation  guide  or  the  new  MS-DOS 
Technical  Reference  Encyclopedia ),  it 
seems  to  be  present  and  work  the 
same  way  in  all  PC-DOS/MS-DOS  ver¬ 
sions  2.0  through  3.2.  Because  Micro¬ 
soft  is  now  clearly  focusing  its  operat¬ 
ing  system  efforts  on  80286-based 
protected  mode  versions  of  DOS,  I  sus¬ 
pect  that  the  8086/88-based  versions  2 
and  3  of  DOS  are  going  to  become  fair¬ 
ly  static  (except  perhaps  for  bug 
fixes).  Therefore,  it  should  be  safe  to 
build  calls  to  int  2eh  into  your  applica¬ 
tion  software  for  these  DOS  versions. 

I  have  two  listings  this  month  to  il¬ 
lustrate  the  use  of  int  2eh.  The  first 
(Listing  Three,  page  86)  is  from  David 
Gwillim  in  Los  Angeles  and  is  in  the 
form  of  a  small  macro  assembler  COM 
program.  David  has  contributed 
many  other  interesting  and  useful 
utilities  to  bulletin  boards  in  the  Los 
Angeles  area.  The  second  example 
(Listing  Four,  page  88)  is  from  Dan 
Lewis  of  Key  Software  Products,  in 
Menlo  Park,  California,  who  contrib¬ 
uted  a  (DeSmet)  C  routine  called  Set 
_Var  that  demonstrates  use  of  the  un¬ 
documented  int  2eh  function  to 


change  the  master  environment 
block.  Dan  is  an  associate  professor  of 
computer  science  at  Santa  Clara 
University. 

File  Handles 

Ross  Nelson  of  San  Jose  writes:  "I  have 
been  following  the  file  handles/redi¬ 
rection  letters  in  your  column,  and  I 
have  an  observation  that  you  may 
find  interesting.  Although  it  seems 
like  the  DUP  and  FDUP  functions  (int 
21h,  functions  45h  and  46h,  respective¬ 
ly)  are  tailor-made  for  redirection 
(and  I  wouldn’t  be  surprised  if  that  is 
the  approach  Unix  uses),  that  is  not 
the  method  MS-DOS  uses  internally.  I 
have  included  the  C  code  for  a  routine 
called  STD.C  that  emulates  the  method 
COMMAND.COM  uses  to  do  redirection 
(at  least,  this  method  was  used  in  MS- 
DOS,  Version  3.0,  last  time  I  checked). 

"MS-DOS  apparently  keeps  a  set  of 
actual’  handles  deep  in  the  bowels  of 
the  operating  system,  with  reference 
counts  and  so  on.  Each  ‘task’  gets  its 
own  set  of  ‘virtual’  handles,  which  al¬ 
ways  begin  with  handle  0.  The  virtu- 
al-to-actual  translation  table  is  held  in 
the  program  segment  prefix  for  each 
task.  The  code  I  am  supplying  was 
written  before  I  saw  your  May  col¬ 
umn,  which  pointed  out  that  the  ta¬ 
ble  doesn't  have  to  reside  there  be¬ 
cause  there  is  a  pointer  and  a  count  in 
the  PSP  that  points  to  the  actual  table. 
Anyway,  when  you  issue  a  redirec¬ 
tion  command  to  COMMAND.COM,  it 
doesn’t  bother  with  DUP  and  FDUP,  it 
just  mucks  with  the  virtual-to-actual 
table  in  the  PSP  of  the  task  that  will 
run  with  redirection.” 

Ross'  program  accompanies  this 
month's  column  as  Listing  Five,  page 
91. 

File-name  Wildcards 

Randy  Langer,  of  MicroSphere  Tech¬ 
nology  in  Chico,  California,  writes:  "I 
am  sending  you  an  assembly-lan¬ 
guage  C  function  [Listing  Six,  page  92] 
that  performs  wildcard  file-name  ex¬ 
pansion  under  MS-DOS  2.x.  Adapted 
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from  the  documentation  presented 
by  Peter  Norton  [The  Programmer's 
Guide  to  the  IBM  PC  (Redmond, 
Wash.:  Microsoft  Press,  19851],  this 
function  supplies  a  solution  to  a  com¬ 
mon  problem  in  writing  operating 
system  utilities. 

"To  use  this  function,  the  user  first 
defines  a  structure  as  typedefe d  in 
wildcard. h  [Listing  Seven,  page  94], 
Then,  for  each  filespec  to  be  expand¬ 
ed,  the  user  copies  a  pointer  to  the 
filespec  into  the  structure  and  initial¬ 
izes  the  flag  member  to  0.  There¬ 
upon,  the  user  repeatedly  calls  wild- 
cardf),  passing  a  pointer  to  the 
structure  defined  for  this  purpose. 
The  function  call  will  either  return  a 
pointer  to  the  structure’s  filename 
member  or  NULL  if  no  more  match¬ 
ing  file  names  exist.  The  example 
shown  in  wildtest.c  [Listing  Eight, 
page  94]  will  clarify  this. 

"Assuming  the  function  returns 
the  file-name  pointer,  other  data  re¬ 
garding  the  file  are  also  available 
from  the  call.  The  structure  member 
f—atts  contains  the  attributes’  of  the 
file  (read-only,  subdirectory,  and  so 
on;  see  Norton,  page  116).  The  mem¬ 
ber  datetime  contains  the  file's  time/ 
date  stamp  in  a  format  that  is  compa- 
table  with  the  Aztec  C  time  library 
functions.  The  filesize  member  con¬ 
tains  what  its  name  suggests.  The  fi¬ 
nal  member,  tempdata,  contains  link 
data  for  subsequent  search  ne\t  calls, 
so  keep  yer  mitts  offa  it. 

“It  should  be  noted  that  the  re¬ 
turned  file  name  does  not  include  the 
drive/path  involved;  this  must  be  di¬ 
vined  from  the  file  spec.  The  algo¬ 
rithm  in  wildtest.c  shows  a  method 
for  doing  this.” 

New  Books  to  Buy 

Strauss,  Edmund.  Inside  the  80286. 
New  York:  Brady  Communications 
Co.,  1986. 

Edmund  Strauss  is  a  senior  applica¬ 
tion  marketing  engineer  for  the  80286 
microprocessor  and  clearly  knows  his 
stuff.  This  book  is  a  very  lucid  presen¬ 
tation  of  the  special  features  of  the 
80286,  including  its  additional  regis¬ 
ters  and  instructions,  protected  virtu¬ 
al-addressing  modes,  task  switching, 
and  privilege  levels.  The  book  in¬ 
cludes  many  excellent  diagrams  and 
several  lengthy  and  well-commented 
assembly-language  programming  ex¬ 
amples,  and  it  even  finishes  up  with 


Dr.  Dobb’s  Journal,  December  1986 


16-BIT 

(continued  from  page  105) 

schematics  and  instructions  to  build 
your  own  small  80286-based  system — 
highly  recommended. 

Concurrent  DOS 

Henry  Velick  of  Monsey,  New  York, 
writes:  “After  reading  your  July  col¬ 
umn,  and  Mr.  Mullan’s  contributions 
in  particular,  here  are  a  few  thoughts 
to  add  to  the  raging  Concurrent  PC- 
DOS  controversy.  The  first  is  a  ques¬ 
tion:  how  many  useful  (usable,  well- 
used,  common,  and  so  on)  PC 
programs  will  support  a  dumb  ASCII 
terminal?  Answer:  not  too  many.  As 
far  as  I  know,  most  of  the  big-selling 
business  programs,  such  as  Lotus  1-2- 
3,  dBASE  III,  Microsoft  Word,  and 
Crosstalk,  are  inextricably  tied  to  the 
PC  keyboard  and  display  adapters. 
How  useful,  then,  can  a  multiuser 
system  be  that  supports  only  one  key¬ 
board/display,  no  matter  how  many 
dumb  terminals  it  might  support? 

"There  is,  by  the  way,  a  reasonable 
alternative.  A  small  company  in  New 
York  state,  called  ANEX  Technology, 
has  some  hardware/software  prod¬ 
ucts  that  allow  up  to  four  users  on  a 
PC  or  PC/XT  and  up  to  eight  on  a  PC/ 
AT.  Unlike  with  Concurrent  PC-DOS, 
each  user  has  full  use  of  a  genuine  PC 
keyboard  (or  aftermarket  equivalent) 
and  a  real  PC  display  (MDA,  CGA,  Her¬ 
cules,  Tecmar,  and  so  on).  Very  few 
programs  cannot  run  on  this  system. 
Those  that  can't  require  certain  hard¬ 
wired  memory  locations  to  be  avail¬ 
able — most  of  these  are  games.  But  I 
have  seen  an  XT  with  four  monitors 
simultaneously  running  1-2-3,  a  BA- 
SICA  graphics  demo,  WordStar,  and  a 
screen-oriented  data-entry  program 
with  very  little  degradation  of  per¬ 
formance — very  impressive. 

“ANEX’s  products  are  called  MPC-4 
and  MPC-8  for  the  PC  and  AT,  respec¬ 
tively.  There  is  also  a  new  low-end 
version  called  PC-ANEX  that  supports 
only  two  users.  And  although  cer¬ 
tainly  more  expensive  than  a  copy  of 
Concurrent  PC-DOS,  they  are  also  a 
good  deal  cheaper  than  the  addition¬ 
al  PCs.  No,  I  don't  work  for  ANEX.’’ 
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Turbo  Pascal  Procedural  Parameters,  Local  Modules  in  Modula-2 


In  this  issue,  I  will  discuss  imple¬ 
menting  procedural  parameters 
in  Turbo  Pascal,  local  modules  in  Mo¬ 
dula-2,  and  two  methods  for  modify¬ 
ing  menus  of  an  application  program 
without  editing  it. 

Procedural  Parameters 

Turbo  Pascal  does  not  support  proce¬ 
dural  parameters.  Procedural  pa¬ 
rameters  enable  programmers  to 
write  applications  that  can  easily  em¬ 
ploy  alternate  methods.  For  exam¬ 
ple,  a  program  sorting  several  re¬ 
cords  can  examine  the  size  of  the 
data  and  determine  which  sorting 
method  to  use.  If  there  are  few  re¬ 
cords,  a  bubble  sort  is  applied;  for  a 
moderate  number  of  records,  the 
Shell-Metzner  sorting  method  is 
used;  and  for  a  large  data  set,  quick¬ 
sort  is  employed. 

Mike  Babulic,  of  Calgary,  Canada, 
has  implemented  procedural  param¬ 
eters;  he  offers  three  versions  that  dif¬ 
fer  in  speed  and  reliance  on  Pascal 
and  machine  language.  You  can 
download  them  from  the  Borland  SIG 
on  CompuServe,  where  they  are 
stored  as  an  archive  file.  You  will 
need  the  DEARC. PAS  utility,  available 
in  the  same  SIG,  to  unpack  all  Mike’s 
files. 

The  archive  file  contains  six  files: 

1.  ProcParm.PAS — Mike's  documen¬ 
tation  with  his  example  program. 

2.  ProcParm.lNC — Contains  the  call 
—ProcParm  procedure. 

3.  ProcParm. QK — In-line  code  to  be 
used  instead  of  the  call— ProcParm 
procedure.  Quicker  execution,  but 
larger  programs. 


by  Namir  Clement 
Shammas 

4.  ProcParm.BIN — The  third  (and  best) 
alternative,  an  externally  assembled 
binary  file.  It  is  noted  for  fastest  exe¬ 
cution  speed  because  of  less  stack  ma¬ 
nipulation  and  the  least  code  added 


to  the  program  (12  bytes!). 

5.  ProcParm. P — This  is  the  "glue’' 
that  you  include  in  a  program  so  it 
can  use  ProcParm.BIN. 

6.  ProcParm. ASM — The  source  code 
for  ProcParm.BIN. 

The  source  code  accompanying  this 
column  (Listings  One  and  Two,  page 
96)  includes  that  for  the  first  two 
methods  only. 

The  three  versions  to  implement 
procedural  parameters  are: 

1.  The  call— ProcParm  procedure — 
This  procedure  is  written  in  Turbo 
Pascal  with  no  in-line  code.  When 
call— ProcParm  is  called  by  a  proce¬ 
dure  or  function,  it  causes  a  short 
jump  to  the  procedure  whose  offset 
is  the  last  parameter  of  the  calling 
procedure.  This  is  done  by  swapping 
the  last  parameter,  a  pointer  to  a  pro¬ 
cedure,  and  the  return  address  of  the 
calling  routine  on  the  stack. 

Using  call— ProcParm,  procedures 
are  passed  as  parameters  to  other 
procedures.  This  is  accomplished  by 
defining  a  dummy  procedure  or 
function  with  exactly  the  same  argu¬ 
ments  as  the  procedure  to  be  passed, 
except  that  a  final  added  integer-type 
parameter  is  also  defined.  When  the 
calling  procedure  invokes  the  dum¬ 
my  procedure,  it  passes  the  offset  of 
the  procedure  to  be  executed  in  this 
last  parameter.  The  Ofs  function  is 
frequently  used  for  this  purpose. 

ProcParm  returns  to  the  routine 
specified  by  the  last  parameter  of  the 
dummy  routine,  and  the  stack  will 
look  exactly  the  same  as  if  the  "re¬ 
turned  to”  procedure  had  been 
called  by  the  procedure  that  called 


the  dummy  one. 

2.  The  in-line  code  method  (Proc¬ 
Parm. QK) — You  can  include  the  Proc¬ 
Parm. QK  file  in  your  dummy  proce¬ 
dure  instead  of  calling  the  ProcParm 
procedure.  This  speeds  up  a  program 
because  fewer  8088  instructions  are 
executed  for  jumping  to  the  passed 
procedure.  Be  aware,  however,  that 
the  cost  of  this  speed  is  a  larger 
program. 

The  ProcPtr  type  need  not  be  de¬ 
clared  if  you  use  ProcParm. QK — the 
integer  type  is  employed  instead. 

3.  ProcParm.BIN  and  ProcParm. P — 
The  ProcParm. P  file  is  included  in 
your  program  to  allow  it  to  use  the 
contents  of  the  ProcParm.BIN  file.  As 
in  the  previous  two  methods,  a  dum¬ 
my  procedure  is  created  with  the  pro¬ 
cedure  to  be  run  as  the  last  parameter. 
This  is  where  the  similarity  ends. 

ProcParm. P  allows  you  to  call  FAR 
procedures  and  functions  that  lie  out¬ 
side  the  body  of  the  program.  In  addi¬ 
tion,  it  allows  your  programs  to  call 
procedures  and  functions  in  the  body 
of  your  Turbo  program  ( NEAR  calls). 

You  can  also  make  a  FAR  call  with 
an  offset.  This  is  useful  if  you  have  set 
aside  an  area  of  storage  for  a  group  of 
procedures  or  functions.  The  method 
used  is  quite  a  bit  slower  than  the  stan¬ 
dard  FAR  call.  If  speed  is  important, 
you  should  save  the  address  of  each 
procedure  in  a  variable  and  use  the 
regular  FAR  call.  Mike  has  included  a 
function  to  make  life  easier  for  you. 

One  problem  with  the  FAR  calls  that 
Mike  hasn’t  been  able  to  solve  yet  is 
that  you  can’t  make  them  from  inside 
the  Turbo  environment.  You  have  to 
create  a  .COM  file  and  execute  that.  If 
anyone  comes  up  with  a  workable  so¬ 
lution,  please  let  Mike  know. 

Listing  Three,  page  96,  shows  an  ex¬ 
ample  I  wrote  using  the  first  two 
methods.  The  program  creates  an  or¬ 
dered  array  of  integers  and  reverses 
their  order.  In  each  method  I  have 
used  the  Shell  sort  and  quicksort  tech- 
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I  niques.  The  sample  program  also  in¬ 
corporates  a  routine  to  report  the 
time  at  the  beginning  and  end  of  a 
sorting  method.  This  should  give  you 
a  feel  for  the  speed  of  each  of  Mike's 
routines. 

Local  Modules  in  Modula-2 

The  Modula-2  language  supports  lo¬ 
cal  modules,  a  valuable  feature  that 
,  has  received  little  attention.  Local 
modules  are  modules  that  are  nested 
inside  others.  Their  interface  with 
the  parent  module  is  established  us¬ 
ing  import  and  export  lists.  The  inter¬ 
face  of  local  modules  is  very  strict — 
for  example,  if  the  local  module 
needs  to  write  a  string  to  the  screen,  it 
must  explicitly  import  the  Write- 
String  procedure  from  the  parent 
module.  This  clearly  differs  from  the 
interface  of  ordinary  Modula-2  pro¬ 
cedures.  The  export  lists  contains  all 
I  the  items  exported  by  the  local 
module. 

The  advantages  of  local  modules 
j  are  twofold.  First,  the  variables  used 
j  in  local  modules  are  static;  their  val- 
I  ues  are  retained  between  calls  to  the 
[  local  modules.  The  second  advantage 
is  that  local  modules  can  initialize 
their  static  variables.  This  is  done 
;  once,  the  first  time  the  local  module 
is  called. 

The  advantage  of  using  local  mod¬ 
ules,  especially  within  library  mod¬ 
ules,  is  to  hide  some  details  concern¬ 
ing  intermediate  variables  involved 
in  certain  calculations.  One  example, 
often  mentioned  in  Modula-2  text¬ 
books,  is  the  generation  of  random 
numbers.  The  local  module  responsi-  | 
ble  for  returning  a  random  number 
is  assigned  the  task  of  initializing  the 
seed  value.  Its  value  is  preserved  by  a 
local  static  variable  between  calls  to 
the  local  module. 

Listing  Four,  page  97,  shows  an  ex¬ 
ample  of  using  a  local  module  inside 
a  library  module.  The  library  module 
BestFit  provides  routines  for  a  linear 
regression  between  two  arrays,  X 
and  V.  The  module  exports  functions 
that  return  the  slope,  intercept,  and 
coefficient  of  determination  statis¬ 
tics.  The  local  module  InnerWorking 
initializes  the  statistical  summations, 
contains  the  Regression  procedure  to 
update  them  with  data,  and  calcu¬ 
lates  intermediate  results.  The  vari¬ 
ables  within  the  local  module  are 
both  static  and  invisible  to  an  applica- 
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tion  program  employing  module 
BestFit.  This  gives  more  of  a  black¬ 
box  effect,  in  which  intermediate 
data  is  retained  by  the  library  mod¬ 
ule  and  the  final  results  are  passed 
back  to  the  calling  application. 

Local  modules  and  their  static  vari¬ 
ables  can  be  used  in  a  variety  of  other 
applications.  A  library  module,  for  ex¬ 
ample,  manipulates  a  stack  of  items 
and  protects  it  from  corruption.  Pro¬ 
cedures  and  functions  are  used  to 
push,  pop,  rotate,  and  swap  data 
items  in  the  stack.  The  application 
program  performs  data  transfer  with 
static  variables  in  the  library  module. 

Modifying  Menus  Without 
Program  Editing 

Menus  are  employed  in  "friendly” 
application  programs.  Aesthetically 
appealing  menus  are  placed  in  sin¬ 
gle-  or  double-line  frames  using  ex¬ 
tended  ASCII  characters.  Normally, 
these  programs  contain  the  code  for 
the  menus.  This  means  that  if  you 
want  to  alter  the  menu  text,  you  must 
edit  and  recompile  the  source  code. 
An  alternative  method  is  to  store  the 
menu  text  in  a  separate  file.  At  run 
time,  the  application  program  reads 
the  menu  files.  Thus,  you  can  modify 
the  menu  text  with  an  editor,  leaving 
the  compiled  application  program 
intact.  This  method  was  chosen  by 
the  developers  of  the  Macintosh, 
who  call  the  files  containing  the 
menu  data  "resource  files.” 

I’ll  get  you  started  by  introducing 
two  ways  to  store  menu  information 
in  a  separate  file.  Each  method  offers 
a  type  of  "menu  builder”  that  reads  a 
different  structure  for  the  menu  text. 

The  first  approach  is  the  simpler 
one.  It  is  based  on  the  idea  that  most 
text  editors  cannot  insert  and  display 
extended  ASCII  characters.  The  solu¬ 
tion  lies  in  the  following  steps: 

1.  Type  a  text  that  resembles  the 
framed  menu  text,  such  that  the 
frame  characters  are  substituted 
with  displayable  characters  (for  ex¬ 
ample,  the  bar,  hyphen,  underscore, 
plus  sign,  and  so  on). 

2.  Construct  a  list  that  maps  the 
above  displayable  characters  with 
the  ASCII  code  number  of  the  frame 
characters. 

Listing  Five,  page  99,  shows  a  pro¬ 
gram  that  implements  this  method. 


]  The  procedure  Build— Screen  reads  j 
the  menu  text  file,  which  contains  the 
mapping  list  discussed  above  (one 
item  per  line).  The  character  set  used 
is  The  map- 

|  ping  list  is  delimited  by  the  keyword 
START,  which  can  be  followed  by  two 
j  menu-frame  shift  coordinators. 

I  SHIFTCOL  <number>  and  SHIFTROW 
<number>  tell  the  menu  builder 
that  the  menu  frame  is  displaced  by 
the  specified  number  of  columns  and 
rows,  respectively.  The  shift  declara-  I 
tions  can  appear  in  any  order  and  are 
optional,  with  default  values  of  0.  The 
next  lines  contain  the  menu  text.  The  1 
menu  builder  scans  each  line,  one 
character  at  a  time,  and  translates  any 
character  found  in  the  mapping  list. 
Procedure  Show— Menu  displays  the 
translated  strings  that  form  the  menu, 
showing  the  sought  frame  characters. 
Procedure  DISP-STR  is  used  to  write  to 
|  the  screen  of  an  IBM  PC  directly  for 
fast  display. 

The  structure  of  the  menu  text  file 
is  simple  and  gives  you  a  good  idea  of 
what  the  menu  looks  like.  I  he  sizes  of 
the  menu  text  files  are  larger  than 
those  of  the  next  method,  in  which 
the  menu  text  is  compressed.  The  sec¬ 
ond  technique  uses  a  menu  interpret¬ 
er/builder  because  the  menu  text 
contains  display  commands.  Listing 
Six,  page  100,  shows  a  test  program 
using  this  method.  The  structure  of 
the  menu  text  file  is  as  follows: 

1.  Frame  parameters — Can  contain 
any  of  the  following  directives  (each 
is  composed  of  a  single  letter  fol¬ 
lowed  by  a  number): 

•  L — Left-edge  shift  to  specify  the  col¬ 
umn  position  of  the  left  edge  of  the 
menu  frame.  Its  value  ranges  be¬ 
tween  1  (default)  and  that  of  the  right 
edge  minus  4. 

•B — Right-edge  shift  to  specify  the 
column  position  of  the  right  edge  of 
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the  menu  frame.  Its  value  ranges  be¬ 
tween  that  of  the  left  edge  plus  4  and 
80  (the  default). 

•H — Specifies  either  1  or  2  as  the 
number  of  lines  in  the  horizontal 
menu-frame  edges. 

•  V — Specifies  either  1  or  2  as  the 
number  of  lines  in  the  vertical  menu- 
frame  edges. 

2.  START  delimiter — Used  because 
the  above  parameters  are  optional 
and  can  appear  in  any  sequence;  it  is 
used  to  delimit  this  set  of  parameters 
from  the  optional  column  and  row 
shift  parameters. 

3.  Column/row  shift  parameters — 
Use  the  keywords  SHIFTCOL  or  SHIFT- 
ROW,  followed  by  the  corresponding 
magnitude.  Give  the  column  and  row 
distance  between  the  upper-left  cor¬ 
ners  of  both  the  physical  screen  and 
the  menu  frame. 

4.  Menu-building  commands — Pro¬ 
vide  the  following  symbols  and  char¬ 
acters  used  in  building  the  desired 
menu  and  its  frame: 

•  @  <3-char  code> — Used  to  specify 
a  single  extended  ASCII-coded  charac¬ 
ter.  Function  Get— Char— .Code  docu¬ 
ments  the  three-letter  codes  of  vari¬ 
ous  parts  of  the  menu  frame.  For 
example,  ULC  represents  the  upper- 
left  corner. 

•  D<3-char  code>  <2-digit  repeat  fac¬ 
tor  > — Used  to  duplicate  a  frame 
character.  The  three-character  codes 
are  used  to  specify  the  frame  charac¬ 
ter,  and  two  subsequent  digits  specify 
the  number  of  times  the  character  is 
duplicated. 

•  S<2-digit> — Used  to  skip  the  num¬ 
ber  of  columns  specified  by  the  two 
digits. 

•  Double  quote — Used  to  signal  that  a 
menu  text  follows.  A  bar  symbol  is 
used  optionally  to  delimit  the  text. 

•  #<2-digit> — Used  to  jump  to  the 
column  position  specified  by  the 
two-digit  number. 

•  V — Used  to  draw  the  left  and  right 
vertical  frame  edges  with  spaces  in 
between. 

•H — Used  to  draw  a  horizontal  line 
between  the  left  and  right  edges. 

The  procedures  DISP-STR  and  Show 
—Menu  are  used  as  in  the  first  method 
to  display  the  menu  in  question 
quickly. 


Tables  1  and  2,  below,  show  menu 
text  files  that  display  the  same 
framed  menu  using  the  first  and  sec¬ 
ond  methods,  respectively.  The  text 
in  Table  2  is  terser  and  more  cryptic 
and  thus  is  recommended  for  fre¬ 
quent  use.  For  casual  users,  I  recom¬ 
mend  the  first  method. 

Because  the  two  methods  are  not 
language  or  hardware  dependent, 
they  can  be  implemented  easily  in 
other  languages.  For  programmers 
who  work  with  multiple  languages 
and  translate  programs,  this  ap¬ 
proach  is  attractive  because  the  text 
files  are  reused  without  any  change. 


/201 

<-  Upper-left  corner 

\1 87 

<-  Upper-right  corner 

&200 

<-  Lower-left  comer 

%188 

<-  Lower-right  comer 

$204 

<-  Left  tee 

@185 

<-  Right  tee 

‘202 

<~  Upper  tee 

1203 

<-  Lower  tee 

-205 

<-  Horizontal  line 

1186 

START 

<-  Vertical  line 

/ - , - ! - \ 

l  I  l 

I  I  I 

!  MAIN  MENU  I  [Q]uit  I 
!  I  [Esc]ape  l 

$ - — * - @ 

I  1)  Prepare  data  ! 


2)  Calculate  results 


3)  Print  results 


Table  1:  Contents  of  a  menu  text  fie  using  the  first  menu-creation  method. 
Comments  have  been  added  to  the  coded  symbols. 


With  menu-intensive  applications  it  is 
more  feasible  to  translate  the  menu 
builders. 
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H2 

V2 

L01 

R56 

START 

@ULC  DHLN36  @DNT  DHLN17  @URC 
@VLN  S36  @VLN  SI  7  @VLN 

@VLN  S08  "M  A I  N  M  E  N  Ul  S09  @VLN  "  [QJuiti  S08  @VLN 
@VLN  S36  @VLN  '  [Escjape  I  @VLN 
@VLN  DHLN36  @UPT  DHLN17  @VLN 
@VLN  '  1 )  Prepare  data  I  #54  @VLN 

V 

@VLN  "  3)  Calculate  results  I  #54  @VLN 

V 

@VLN  "  3)  Print  results  I  #54  @VLN 
@LLC  DHLN54  @LRC 


Table  2:  Contents  of  a  menu  text  file  using  the  second  method.  The  menu 
displayed  is  equivalent  to  that  obtained  in  Table  1. 
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Languages 

MicroMotion  has  released 
MasterForth,  an  imple¬ 
mentation  of  Forth  in  the 
Forth-83  standard  dialect. 
It  runs  on  the  Macintosh, 
IBM  PC  line,  Apple  II  series, 
Commodore  64,  and  Z80 
CP/M  computers,  and  pro¬ 
grams  written  in  Master¬ 
Forth  for  one  computer 
can  run  unchanged  on  all 
the  others.  The  product 
provides  a  complete  pro¬ 
gramming  environment, 
including  a  macro  assem¬ 
bler  and  a  full-file  inter¬ 
face.  Relocatable  utilities 
and  transient  definitions 
make  it  possible  to  run  sub¬ 
stantial  software  packages 
even  in  a  limited  memory 
environment.  The  string 
package,  screen  editor,  and 
resident  debugger  are  stan¬ 
dard  features.  Programs 
can  also  be  optimized  with 
the  optional  target  compil¬ 
er.  MasterForth  is  priced  at 
$100  — $125.  Reader  Service 
No.  16. 

MicroMotion 

8726  S.  Sepulveda  Blvd. 

#A171 

Los  Angeles,  CA  90045 
(213)  821-4340 

386/ASM  from  Phar  Lap 
Software  is  an  assembler/ 
linker  for  the  Intel  80386 
microprocessor  that  can  be 
used  to  create  applications 
for  the  80386  on  IBM  PC, 
VAX,  and  Unix  host  com¬ 
puter  systems.  A  simple  ex¬ 
tension  to  the  Microsoft 
.OBJ  file  format  has  been 
created  to  support  the 
80386;  it  allows  existing 
8086  compilers  to  be  up¬ 


graded  with  minimal  ef¬ 
fort  and  to  work  with  the 
linker  supplied  with  386/ 
ASM.  The  386/ ASM  package 
includes  the  80386  assem¬ 
bler,  the  80386  linker,  a  us¬ 
ers’  manual,  and  examples 
of  80386  assembly-lan¬ 
guage  programs.  It  is 
priced  at  $495  for  the  IBM 
PC  version  and  $4,995  for 
the  VAX/VMS  version.  Read¬ 
er  Service  No.  17. 

Phar  Lap  Software  Inc. 

60  Aberdeen  Ave. 
Cambridge,  MA  02138 
(617)  661-1510 

ExperTelligence  has  an¬ 
nounced  a  new  PROLOG  for 
the  Macintosh.  Exper-Pro- 
log  II  allows  you  to  load,  ex¬ 
ecute,  and  modify  PROLOG 
programs  interactively. 
The  interpreter  includes 
real  numbers,  string  ma¬ 
nipulations,  and  advanced 
process  control.  It’s  $495. 
Reader  Service  No.  18. 
ExperT  elligence 
559  San  Ysidro  Rd. 

Santa  Barbara,  CA  93108 
(805)  969-7874 

Smalltalk/V  from  Digitalk 
includes  graphical  icons 
and  fonts,  a  PROLOG  com¬ 
piler,  and  a  source-level  de¬ 
bugger.  The  language  is 
able  to  perform  object 
swapping  to  a  hard  disk  or 
a  RAM  disk  and  can  handle 
objects  up  to  32K  in  size.  It 
runs  on  the  IBM  PC/AT  and 
is  priced  at  $99.  Reader  Ser¬ 
vice  No.  19. 

Digitalk  Inc. 

5200  W.  Century  Blvd. 

Los  Angeles,  CA  90045 
(213)  645-1082 

Simulator-debuggers  are 
available  from  Mecklen¬ 
burg  Engineering  that  al¬ 
low  you  to  test  and  debug 
object  modules  for  8-bit  mi¬ 
croprocessors  on  an  IBM  PC. 
Versions  are  available  for 
the  63xx,  65xx,  68xx,  8085, 


8048,  and  Z80  processor 
lines.  The  simulators  read 
program  or  data  files  in 
hexadecimal  format  and 
allow  you  to  run,  trace,  sin¬ 
gle-step,  and  set  break¬ 
points.  Status  displays 
show  the  contents  of  mem¬ 
ory  and  registers  as  well  as 
disassembled  instructions. 
It's  priced  at  $75.  Reader 
Service  No.  20. 
Mecklenburg  Engineering 
P.O.  Box  744 
Chagrin  Falls,  OH  44022 
(216)  338-8379 

A  utility  program  called  EX- 
E2LNK  from  Lief  Ibsen  al¬ 
lows  you  to  use  assembly- 
language  modules  within 
programs  written  in  Logi¬ 
tech’s  Modula-2.  The  pro¬ 
gram  converts  standard, 
linked  object  modules  to 
the  .LNK  object  format.  It 
works  with  Logitech's  Ver¬ 
sions  1.10  and  2.0  compil¬ 
ers.  It  costs  DKK  550  ($60). 
Reader  Service  No.  21. 

Leif  Ibsen 
Blommevangen  15 
DK  -  2760  Maalov 
Denmark 

BES  Systems  has  released  a 
Modula-2  preprocessor 
that  allows  programmers 
to  define  and  use  macros  as 
well  as  include  files  and 
conditional  compilation. 
The  full  source  code,  writ¬ 
ten  in  Logitech’s  Modula-2/ 
86,  is  available  for  $69.95; 
the  compiled  utility  only  is 
priced  at  $44.95.  Reader 
Service  No.  22. 

BES  Systems 
P.O.  Box  270835 
Houston,  TX  77277 
(713)  528-7132 

Logical  Developments 

has  released  RF77,  a  pro¬ 
gram  that  translates  Ratfor 
code  into  standard  FOR¬ 
TRAN.  Ratfor  is  a  high-level 
structured  language  that 
eliminates  many  of  the 


strict  requirements  of  the 
FORTRAN-77  standard.  RF77 
creates  a  standard  MS-DOS 
ASCII  file  suitable  for  com¬ 
pilation  with  most  MS-DOS 
FORTRAN  compilers.  It’s 
$65.  Reader  Service  No  23. 
Logical  Developments 
P.O.  Box  55798 
Houston,  TX  77255 

Tools 

PopScreen  is  a  fast  screen 
generator  for  IBM  PCs  and 
compatibles  from  Baysoft 
that  lets  you  design  your 
displays  on  screen,  with 
easy  access  to  all  the  PC's 
character  graphics  fea¬ 
tures.  It  allows  quick  cre¬ 
ation  of  boxes,  block 
moves,  cursor  draws,  and 
individual  or  global  color 
changes.  PopScreen’s  com¬ 
pacted  display  data  struc¬ 
tures  can  be  written  as  as¬ 
sembly-language  source 
code,  in-line  code  for  Tur¬ 
bo  Pascal,  or  as  linkable 
.OBJ  code  for  other  linked 
languages.  Displays  can 
also  be  written  to  .COM  files 
to  be  used  in  batch  files  or 
called  from  DOS.  PopScreen 
costs  $39.95.  Reader  Service 
No.  24. 

BaySoft 
P.O.  Box  562 
Albany,  CA  94706 
(415)  527-6894 

Qlink  and  Qmake,  from 
Electrosoft  Corp.,  can  be 
used  to  maintain  software 
for  the  IBM  PC  and  compati¬ 
bles.  The  Qlink  linker  is 
fully  compatible  with  Mi¬ 
crosoft  LINK  and  operates 
about  ten  times  faster  for 
the  average  program.  It 
performs  the  initial  link  in 
a  way  very  much  like  the 
way  Microsoft  LINK  and 
others  do,  and  in  addition, 
it  builds  a  map  of  the  pro¬ 
gram.  Qlink  can  then  build 
a  new  executable  file  by  re¬ 
placing  changed  object 
modules  and  tracking  new 
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ones  instead  of  relinking 
the  entire  program. 
Qmake  is  similar  to  the 
Unix  make  utility.  It  fol¬ 
lows  a  map  of  the  program 
and  looks  at  the  file  genera¬ 
tion  times  to  tell  if  an  out¬ 
put  file  needs  to  be  con¬ 
structed  based  on  the 
component  source  files. 
Qmake  allows  a  single  exe¬ 
cuted  command  to  process 
all  the  files  that  need  to  be 
updated.  The  programs  are 
not  copy-protected.  Qlink 
costs  $250,  Qmake  costs 
$100,  and  a  package  con¬ 
taining  both  costs  $295. 
Reader  Service  No.  25. 
Electrosoft  Corp. 

3003  Washtennaw  Ave. 

Ste.  1 

Ann  Arbor,  MI  48104 
(313)  973-1229 

TDebug  PLUS,  from  Turbo- 


Power  Software,  allows 
Turbo  Pascal  program¬ 
mers  to  trace,  set  break¬ 
points,  and  examine  and 
set  variables  at  run  time  us¬ 
ing  the  symbolic  variables 
from  Pascal  source  code. 
TDebug  PLUS  automatically 
loads  Turbo  Pascal,  which 
operates  normally  for  edit¬ 
ing  and  compiling  the  pro¬ 
gram.  After  the  program 
has  compiled,  TDebug  PLUS 
takes  control.  The  source 
code  is  displayed  on  one 
half  of  the  screen,  and  the 
other  half  displays  the  de¬ 
bugging  commands  and  re¬ 
sponses.  TDebug  PLUS'S 
MAP  files  are  fully  compati¬ 
ble  with  many  external  as¬ 
sembly-language  debug¬ 
gers.  TDebug  runs  with 
Turbo  Pascal  3.0  and  costs 
$60.  Reader  Service  No.  26. 
TurboPower  Software 
3109  Scotts  Valley  Dr. 

Ste.  122 

Scotts  Valley,  CA  94066 


(408)  438-8608 

Artificial 

Intelligence 

A  fully  functional  LISP  li¬ 
brary  and  programming 
environment  for  the  C  lan¬ 
guage  is  now  available  for 
the  IBM  PC  line  and  either 
Microsoft  or  Lattice  com¬ 
pilers  from  Frederick  J. 
Drasch  Computer  Soft¬ 
ware.  Written  entirely  in 
C,  Clisp  is  Common  LISP- 
compatible  and  consists  of 
more  than  100  functions, 
including  all  LISP  primi¬ 
tives,  predicates  and  condi¬ 
tionals,  association  and 
property  lists,  symbolic 
pattern  matcher,  context- 
sensitive  database  and 
stack,  and  an  interpreter 
with  hooks  to  add  user- 
written  functions.  It  sells 
for  $189  (with  source  code). 
Reader  Service  No.  27. 
Frederick  J.  Drasch  Com¬ 
puter  Software 


RFD#1  Box  202 
Ashford,  CT  06278 
(203)  429-3817 

Gold  Hill  Computers  has 

introduced  the  GCLISP  386 
)  Developer  and  the  386 
HummingBoard  for  IBM 
PCs  and  compatibles.  The 
|  GCLISP  386  Developer  is  a 
powerful  Common  LISP  de¬ 
velopment  environment 
j  for  386-based  systems.  It 
[  addresses  up  to  15  mega- 
|  bytes  of  memory  and  in- 
|  eludes  a  large  memory  in¬ 
terpreter  and  compiler, 
editor,  tutorial,  and  on-line 
help  system  and  supports 
lexical  scoping,  packages, 
and  transcendental  func¬ 
tions.  The  386  Humming- 
Board  is  an  Intel  386-based 
plug-in  board  with  memo¬ 
ry  that  is  specifically  tai¬ 
lored  to  run  large  LISP  ap¬ 
plications  quickly.  Directly 
addressable  on-board 
memory  is  expandable  to 
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24  megabytes  with  1-mega¬ 
bit  DRAMs  (up  to  6  mega¬ 
bytes  with  256K  DRAMs). 
GCLISP  386  Developer  costs 
$1,195;  when  bundled  with 
the  HummingBoard,  it 
costs  $7,000.  Reader  Service 
No.  28. 

Gold  Hill  Computers 
163  Harvard  St. 

Cambridge,  MA  02139 
(617)  492-2071 

TEX  for  Micros 

Addison-Wesley  has  re¬ 
leased  a  complete  IBM  PC 
implementation  of  Donald 
Knuth’s  TEX  typesetting 
system.  MicroTEX  is  a 
"mark-up”  system,  mean¬ 
ing  that  users  add  special 
instructions  to  a  standard 
ASCII  file.  The  program 
then  creates  its  own  file 
that  can  be  used  to  preview 
the  typeset  text  on  the 


screen.  It  costs  $295  alone; 
with  an  Epson/IBM  print 
driver,  it  costs  $369;  and 
with  a  PostScript  driver,  it 
costs  $495.  Reader  Service 
No.  29. 

Addison-Wesley 
Publishing  Co. 

Jacob  Wy. 

Reading,  MA  01867 
(617)  944-3700 

FTL  Systems  has  unveiled 
MacTeX,  a  desktop  typeset¬ 
ting  software  package  for 
the  Macintosh.  MacTeX 
combines  TEX  with  the 
graphics  power  of  Post¬ 
Script.  It  offers  a  full  set  of 
professional  typesetting 
features  and  creates  cam- 
era-ready  typeset  docu¬ 
ments  on  most  PostScript- 
compatible  typesetters  and 
printers.  MacTeX  also  pro¬ 
vides  a  built-in,  multiwin¬ 
dow  text  editor  with 
MacWrite-type  functions. 
MacPaint  images  can  be 


imported  and  scaled,  and 
248  PostScript  commands 
are  supported.  A  preview 
mode  allows  for  on-screen 
WYSIWYG  viewing  of  the 
document  text.  MacTeX 
runs  on  the  Mac  Plus  and 
costs  $750.  Reader  Service 
No.  30. 

FTL  Systems  Inc. 

234  Eglinton  Ave.  E,  Ste.  205 
Toronto,  Ont. 

Canada  M4P  1K5 
(416)  487-2142 

For  the  Macintosh 

Peachtree  Technology 

has  released  its  first  prod¬ 
uct  for  the  Macintosh,  a  20- 
megabyte  hard-disk  drive 
called  the  S-20  Plus  that  is 
two  to  six  times  faster  than 
the  Apple  HD-20  drive.  The 
external  3.5-inch  drive  uses 
the  Mac  Plus  SCSI  port.  It 
costs  $1,395.  Reader  Service 
No.  31. 

Peachtree  Technology 
3120  Crossing  Pk. 


Norcross,  GA  30071 
(404)  662-5158 

The  TDBK-20+  from  MD- 
Ideas  is  a  tape  backup  unit 
that  lets  you  back  up  your 
Mac  Plus  hard  disk  quickly. 
The  TDBK-20+  utilizes  the 
SCSI  port  and  can  back  up 
22  megabytes  on  each  tape. 
It  can  back  up  and  restore 
virtually  any  Macintosh 
hard  disk  or  volume.  All 
data  is  read  and  verified  to 
ensure  reliability  and  in¬ 
tegrity  of  all  backups.  Even 
copy-protected  software, 
which  normally  can  be  in¬ 
stalled  on  a  hard  disk  only 
once,  can  be  properly  re¬ 
stored.  The  TDBK-20-F  re¬ 
quires  a  Macintosh 
equipped  with  a  SCSI  port 
and  costs  $1,095.  Reader 
Service  No.  32. 

MDIdeas  Inc. 

1111  Triton  Dr. 

Ste.  205 

Foster  City,  CA  94404 
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(415)  573-0580 

For  the  Amiga 

ENVISAGE  is  a  multimedia 
periodical  for  the  Amiga 
computer  from  Chestnut 
Computer  Graphics  and 
Sound.  Four  times  a  year, 
subscribers  receive  a  maga¬ 
zine,  a  stereo  cassette  tape, 
color  photos  of  Amiga 
graphics,  an  Amiga  disk, 
and  a  collection  of  product 
information  flyers  and  ad¬ 
vertisements  for  Amiga  re¬ 
lated  products.  They  also 
receive  access  to  a  comput¬ 
er  bulletin-board  system. 
An  annual  subscription  to 
ENVISAGE  costs  $60.  Reader 
Service  No.  33. 

Chestnut  Computer 
Graphics  and  Sound 
P.O.  Box  417 
Hatfield,  PA  19440 
(215)  855-0741 

A  512K  memory-expansion 
box  called  Alegra  is  avail¬ 
able  for  the  Amiga  from 
Access  Associates.  The 
unit  plugs  into  the  expan¬ 
sion  slot  and  consumes  less 
that  5  watts.  It  allows  for 
future  upgrades  to  2  mega¬ 
bytes  and  supports  the 
Amiga's  auto-configura¬ 


tion  architecture.  The 
price  is  $379  for  the  512K 
version.  Reader  Service  No. 
34. 

Access  Associates 
491  Aldo  Ave. 

Santa  Clara,  CA  95054 
(408)  727-0256 

For  the  Atari  ST 

A  multitasking  operating 
system  for  the  ST  is  avail¬ 
able  from  Beckmeyer  De¬ 
velopment  Tools.  Called 
Micro  RTX,  it  is  fully  com¬ 
patible  with  TOS  and  even 
runs  unmodified  TOS  pro¬ 
grams.  The  number  of  ac¬ 
tive  tasks  is  limited  only  by 
the  amount  of  available 
memory.  Micro  RTX  is 
priced  at  $69.95.  Reader 
Service  No.  35. 

Beckmeyer  Development 
Tools 

592  Jean  St.,  #304 
Oakland,  CA  94610 
(415)  658-5318 

Mach2  from  Palo  Alto 
Shipping,  is  a  multitasking 
Forth-83  development  sys¬ 
tem  for  the  Atari  ST.  Like 
other  implementations  of 
Forth,  Mach2  is  highly  in¬ 
teractive,  allowing  you  to 
experiment  with  the  ST 
without  going  through  the 
compile-link-execute  cycle. 
The  Mach2  package  in¬ 


cludes  an  integrated  GEM 
editor,  full  GEM  and  TOS 
support,  Motorola  assem¬ 
bler,  examples,  and  a  300- 
page  manual.  It  costs  $59.95. 
Reader  Service  No.  36. 

Palo  Alto  Shipping 
P.O.  Box  7430 
Menlo  Park,  CA  94062 
(415)  854-2749 
(800)  44-FORTH 

Miscellaneous 

SideTalk  from  Lattice  is  a 
package  of  telecommuni¬ 
cations  programs  for  the 
IBM  PC  plus  a  communica¬ 
tions  programming  lan¬ 
guage.  The  package  can  be 
used  as  a  memory-resident 
program  or  alone.  The 
price  is  $119.95.  Reader  Ser¬ 
vice  No.  37. 

Lattice  Inc. 

P.O.  Box  3072 
Glen  Ellyn,  IL  60138 
(312)  858-7950 

A  full  version  of  Unix  V  is 
available  for  the  IBM  PC/AT 
from  Microport  Systems. 
System  V/AT  contains  more 
than  200  utility  programs. 
The  implementation  in¬ 
cludes  a  virtual-screen 
windowing  system,  FOR¬ 
TRAN  and  C  compilers,  and 
a  symbolic  debugger.  The 
file  system  can  be  "hard¬ 
ened"  against  power  out¬ 


ages  through  special  disk 
software.  System  V/AT 
costs  $159  for  a  run-time 
package;  a  software  devel¬ 
opment  system  with  full 
language  support  costs 
$169;  and  a  site  license  for 
educational  institutions  is 
available  for  $800.  Reader 
Service  No.  38. 

Microport  Systems  Inc. 
10096  Soquel  Dr. 

Aptos,  CA  95003 
(408)  688-0286 

A  multitasking  kernel  for 
Z80,  NSC800,  and  HD64180 
microprocessors  is  avail¬ 
able  from  Echelon.  Called 
QUICK-TASK,  it  includes  full 
source  code.  The  kernel  is  a 
ROMable  code  segment  of 
less  than  4K  that  supports 
up  to  255  tasks  with  hard¬ 
ware  interrupt  support 
and  multiprocess  synchro¬ 
nization.  The  full  package 
costs  $249.  Reader  Service 
No.  39. 

Echelon  Inc. 

885  N.  San  Antonio  Rd. 

Los  Altos,  CA  94022 
(415)  948-3820 
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FORUM 


SWAINE'S  FLAMES 


Ray  Duncan,  Allen  Holub,  and  I 
flew  up  to  Redmond,  Washing¬ 
ton  in  October  for  a  Microsoft  semi¬ 
nar  on  languages.  Navigating  the 
halls,  we  had  to  dodge  the  pushcarts 
loaded  with  newly  arrived  80386  ma¬ 
chines.  There  was  an  AT  with  EGA  on 
every  desk.  A  four-building  network 
that  works.  Sixty  Sun  workstations. 
Yeah,  but  they  get  a  lot  of  rain. 

One  feature  of  the  seminar  was  a 
"Storm  the  Gates"  programming  con¬ 
test.  Frivolous  though  it  was,  1  must 
admit  that  it  was  also  a  good  show 
and  that  Bill  Gates  finished  w’ell 
ahead  of  all  challengers. 

Microsoft  is  concerned  just  now 
with  competition  of  a  more  commer¬ 
cial  sort  from  Borland  International. 
QuickBASIC,  Version  2,  recently  be¬ 
came  Microsoft  ’s  fastest-selling  prod¬ 
uct.  Microsoft  is  pushing  QU2,  its  shot 
at  Borland's  market,  like  no  other 
product  in  the  company’s  history. 

What  is  Borland's  market,  as  Micro¬ 
soft  sees  it?  Microsoft  language  mar¬ 
keting  manager  Rob  Dickerson 
polled  QuickBASIC  1.0  and  Turbo  Ras¬ 
cal  users.  In  each  case,  most  used  the 
product  at  work,  and  they  usually 
employed  it  for  data  management.  A 
picture  of  a  business  user  writing 
small  report  programs  suggests  itself. 

Well,  maybe.  Meanwhile  back  in 
Seotts  Valley,  Borland  has  listened  to 
its  market  and  released  a  new  version 
of  Turbo  Prolog.  Is  this  the  same  Bor¬ 
land  market?  Perhaps  a  BASIC  and  a 
Pascal  can  share  one  market,  but  who 
are  the  users  of  Turbo  Prolog,  and 
does  any  of  this  have  anything  to  say 
about  who  will  buy  a  Turbo  C  or 
QuickC? 

1  ask  that  question  because  Micro¬ 
soft  and  Borland  are  at  work  on  Tur¬ 
bolike  C  compilers.  Bill  Gates  said  at 
the  conference  that  he  wants  to  see 
Borland  bring  out  a  Turbo  C,  and  I'm 
sure  that  Phillipe  Kahn  will  l>e  sent 
one  of  the  first  beta  copies  of  QuickC. 
One  market  for  QuickC  could  be  Win¬ 
dows  developers  looking  for  a  fast 
prototyping  tool.  I'm  sure  that  either 


company  could  do  well  with  a  Turbo¬ 
like  C  compiler,  but  1  can't  believe  that 
the  audience  is  Turbo  Pascal 
programmers. 

(Another  product  that  may  make 
Windows  development  more  appeal¬ 
ing  is  a  third-party  34010  graphics 
board  that  will  be  announced  shortly 
after  my  deadline  for  this  column.) 

One  of  the  most  demanding  mar¬ 
kets  for  Microsoft’s  C  compilers  is  Mi¬ 
crosoft,  and  one  of  the  most  impor¬ 
tant  projects  underway  at  Microsoft 
just  now  is  the  work  on  optimization. 
Since  Microsoft  does  all  its  program¬ 
ming  in  C  and  assembly  language 
now,  optimizing  its  own  C  compilers 
should  result  in  immediate  improve¬ 
ments  across  its  entire  product  line. 

W'hat  makes  serious  optimization 
promising  is  the  80386  chip,  as  global 
dataflow  analysis  has  until  now 
proved  too  demanding  for  micropro¬ 
cessor  power.  What’s  scary  for  Micro¬ 
soft  is  a  new  kind  of  competition.  Rob 
Dickerson  admits  to  Ixjing  worried 
about  the  minicomputer  compiler 
vendors  who  already  have  powerful 
optimizing  compilers.  Some  of  these 
will  surely  survive  the  radical  para¬ 
digm  shift  into  the  microcomputer 
market  and  make  life  interesting  for 
microcomputer  confpiler  vendors. 

It's  not  clear  whether  Microsoft  is 
worried  by  operating  system  com¬ 
petitors  in  the  386  environment. 
Xenix-386  is  out,  albeit  with  a  286  ker¬ 
nel,  and  non-Unix  types  may  be  will¬ 
ing  to  wait  for  an  MS-DOS,  But  The 
Software  Link  of  Atlanta  is  promising 
to  deliver  a  native-mode  multitasking 


operating  system  for  the  386  that  will 
be  compatible  with  and  replace  DOS. 
And  DRI  keeps  polishing  its  Concur¬ 
rent  DOS  for  PC  machines — the  ver¬ 
sion  now  in  beta  is  getting  good 
marks.  Well,  we'll  see. 

On  the  flight  to  Redmond  1  worked 
a  crossword  puzzle.  One  clue  was 
"one  who  takes  drugs."  The  answer: 
addict.  Yes,  it's  heartening  to  see  even 
crossword  puzzle  writers  getting  in 
on  the  act  and  analyzing  the  drug 
problem  as  thoroughly  as  Congress 
and  the  television  networks  have. 

My  cousin  Corbett  thinks  DDJ 
ought  to  join  the  campaign.  Addic¬ 
tion,  he  says,  is  a  serious  problem 
among  programmers,  and  its 
spreading  rapidly.  Corbett  has 
shown  me  frightening  statistics  on 
the  number  of  programmers  who 
only  get  up  from  their  keyboards 
during  the  compile  phase  and  urges 
me  to  consider  what  will  happen  to 
these  code  junkies  when  they  get 
their  hands  on  386  machines.  Labora¬ 
tory  pigeons  on  a  killer  reinforce¬ 
ment  schedule.  Gruesome. 

I  d  been  wondering  for  months 
what  was  behind  Fast  Willie's  editori¬ 
al  in  PC  Tech  Journal  begging  Intel  to 
hold  off  on  releasing  the  386.  Now  1 
understand:  Willie  was  doing  his  bit 
to  fight  programming  addiction. 

Corbett,  who  abhors  mice  and  win¬ 
dows,  spent  some  time  recently  pro¬ 
gramming  in  Smalltalk  and  conclud¬ 
ed  that  it’s  nonaddictive.  He  is 
currently  negotiating  with  a  soft¬ 
ware  vendor  to  develop  a  rehabilitat¬ 
ing  object-oriented  programming  en¬ 
vironment,  the  first  version  of  which 
will  be  called  MethodOne. 


Michael  Swaine 
editor-in-chief 
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Functions,  MS-DOS,  43 1 , 435-437 

General  First-Order  Sorting  Algorithm,  A,  615-617,  641-642 
Generic  C  routines,  creating  through  preprocessor,  804 
Graphics 

controllers,  for  IBM  PC,  743-748,  764 
primitives,  features  of  82786  and  34010,  743-748,  764 
line  drawing  function,  330,  350-352 
on  Macintosh,  752-758,  776-784 
use  of  cubic  splines  in,  609-614,  637-640 
Great  CRC  Mystery,  The,  92-97,  121-124 

Ham,  Michael,  516-521,  510-51 1,  720-724 
Hamilton,  Dennis  E.,  98-101,  125-126 

Hamming  code,  error  detection/correction  with,  392-394, 417-418 
Hahn,  Steve,  545-567, 585-587 
Hardenberg,  Hal,  8 

Hardware  reviews,  turbo  boards  for  IBM  FC,  624-627,  643-647 
Hardware 

manipulation  of  IBM  PCs,  471-476,  504-509 
graphics  chips,  743-748,  764 

High-Speed  Thrills:  A  Review  of  Eight  Turbo  Boards  for  the  IBM  PC, 
624-627,  643-647 

Holub,  Allen,  10-14,46-^0,  88-91,  1 14-120,  163-167,  188-196, 
239-240,  261-263,  388-391, 410-416, 455-460, 486^190, 
534-535,  538-544,  574-584,  605-628, 634-636, 675, 

679-681,  702-710, 737-742, 759-763 
How  to  Fix  Line  Glitches,  392-394,  417-418 
Human  Interface  Design:  From  the  Outside  In,  320-324 
Human  Interface  Design:  Jef  Raskin  Interview,  325-329 

IBM  PC 

and  compatibles,  operating  system  for,  806-814,  826-842 
graphics,  147-148,  149-151 
graphics  controllers  for,  743-748,  764 
Modula-2  compilers  for,  694-70 1 
programs  for,  648-633,  659-661 
Turbo  boards  for,  624-627,  643-647 
use  of  Enhanced  Graphics  Adapter  with,  330,  350-352 
video  display  memory,  315-319,  348-349 
window  manager  for,  364-367,  368-370 
IBM  PC/AT,  180-183,  207-213 

processing  speed  of,  624-627,  643-647 
In  Search  of  a  Sine,  8 1 5-8 1 7 
In-line  assembly,  in  Turbo  Pascal,  717-719,  713-715 
Inference  engine,  as  part  of  PROLOG,  618-623 
Inference  engine,  micro-PROLOG  version  of,  241-252,  264-268 
Interface,  Forth  to  PCs  BIOS  and  BDOS,  471^176,  504-509 
Interpreter,  PROLOG,  241-252,  264-268 
Interpreter,  in  Forth  implementation,  467-470,  493-503,  628-630 
Interviews,  Jef  Raskin,  325-329 

Jones,  Do-While,  102-108,  127-134 

Katz,  Howard,  749-751,  765-775 
King,  Steve,  624-627,  643-647 

Learning  Ada  on  a  Micro,  102-108,  127-134 
Lindley,  Craig  A.,  471^76,  504-509 


Local  modules,  in  Modula-2,  856-858,  849-853 

Machine  code,  generation  of  by  68000  assembler,  258-261,  270-272 
Macintosh,  615-617,  641-642 

dissolve  routine  for,  752-758,  776-784 
screen-image  program  for,  749-751,  765-775 
Macros,  in  Tele  OS,  806-814,  826-842 
Mandelbrot  Program  for  the  Macintosh,  A,  749-751,  765-775 
Mandelbrot  set,  in  screen-image  program,  749-75 1 , 765-775 
Manipulating  Path  Names,  6-7 
Manual-install  version  of  Z-System,  818-823 
Marasco,  Joe,  168-174,  197-203,273-296,  392-394,417^18 
MASM,  assembler  for  PC,  659-661, 648-633 
Master  environment  block 

MS-DOS,  changing  from  program,  854-855,  845-848 
in  MS-DOS,  modification  of,  717-719,  713-715 
Math  functions 

in  assembler,  815-817 
in  BASIC,  815-817 
on  NS320XX,  815-817 

Matrix  management,  in  Turbo  Pascal,  785-789,  790-793 
Mclvor,  Robert  A.,  615-617,  641-642 
McNiemey,  Ed,  743-748,  764 
Memory 

management,  in  MS-DOS,  471-476,  504-509 
maps,  of  Z-system  versions,  818-823 
models,  for  C  compiler  users,  545-567,  585-587 
test,  for  68000-based  systems,  654-658,  662-663 
on  82786  and  34010, 743-748,  764 
Menu  modification  without  program  editing,  849-853,  856-858 
Micro  PROLOG,  241-252,  264-268 
Modeling  a  System  in  PROLOG ,  245-257 
Modifying  MS-DOS  master  environment  block,  713-715,  717-719 
Modula-2,  111-113,  134-136,  432,438^140,591-593,588-590, 
588-589,  694-701, 785-789,  790-793,  849-853,  856-858 
porting  among  systems,  331-339,  353-359 
top-down  or  bottom-up  design,  258-261,  270-272 
X68000  Cross  Assembler,  258-261,  270-272 
Modula  2  Compilers  for  the  IBM  PC,  694-701 
Modules,  implementation,  in  68K  Crows  Assembler,  331-339, 
353-359 

Monochrome  display,  dissolving  bit-mapped  graphics  on,  752-758, 
776-784 

More,  file-browsing  utility,  679-681,  702-710 
Morton,  Mike,  752-758,  776-784 

MS  DOS,  1 14-120,  299-300, 297-298, 435-437, 431, 471^76, 
504-509,  531-532, 545-567,  585-587,  618-623,  624-627, 
643-647,  659-661, 648-653,  854-855,  845-848 
C  compilers  for,  545-567,  585-587 
execution  speed,  180-183,  207-213 
functions,  43 1 , 435-437 

master  environment  block,  713-715, 717-719,  845-848, 
854—855 

memory  management  in,  471-476,  504-509 
PROLOG  implementation,  618-623 
shell,  10-14,46-60,  88-91,  114,  120,  163-167,  188-196, 
239-240, 261-263 

turbo  boards  for  IBM  PC,  624-627,  643-647 
utility,  297-298,  299-300 
MuLISP,  241-252, 264-268 
Multitasking  Kernel,  A,  806-814,  842 

Multitasking  kernel,  with  68000  context  switchers,  26-32,  62-63 
Multitasking,  in  Turbo  Pascal,  175-176,  204-206 

Naming,  in  Forth,  720-724 

Nelson,  Ross,  682-688 

New  Issues  in  PC  Graphics,  743-748,  764 

NS32000,  square  root,  224-225,  214 

NS320XX,  689-693, 71 1-712,  815-817 

Operating  system 

design,  806-814,  826-842 


68K  kernel  as,  26-32,  62-63 
for  IBM  PC  and  compatibles,  806-814,  826-842 
Osborne  1, 255-257 

Outline  processors,  use  of  in  programming,  720-724 

Overview  of  the  DOD  Ada  Software  Repository,  109-1 10,  127-134 

Park,  Jack,  253-254,  269 

Pascal,  98-101,  125-126, 432, 438-440,  588-590,  588-589,  591-593, 
785-789.  790-793 
dialect  translation  of,  184-186 
Pattern  matching  in  parallel  processing,  178-179 
Pattern-matching  routines,  for  more  utility  679-681,  702-710 
PC-DOS,  180-183,  207-213 

PC/Forth  interface,  to  expanded  memory  subsystem,  512-515, 
568-569 

PL/68K  C  Becomes  68000  Assembly  Language,  15-25,  61 

PL/68K,  as  new  way  of  using  C,  15-25, 61 

Polynomial  arithmetic,  Modula-2,  92-97,  121-124 

Portability,  of  PL/68K,  15-25,  61 

PowerN  function,  98-101,  125-126 

Problems  of  Parallelism,  The  178-179 

Procedural  parameters,  in  Turbo  Pascal,  856-858,  849-853 

Procedures,  simulated  overload  in  Pascal  or  Modula-2,  438-440, 432 

Procedures,  sorting,  in  68000  assembler,  258-261,  270-272 

PROLOG 

implementations,  in  MS-DOS,  618-623 
modeling  software  system  with,  255-257 
Program  conversion,  from  8-bit  to  16-bit,  689-693,  71 1-712 
Programming 

environment,  concept  of  241-252,  264-268 
languages,  Turbo  Prolog  and  PROLOG,  618-623 
tools,  Tele  as  set  of,  806-814,  826-842 
Programming  on  the  80386,  682-688 
Programs 

32000  cross  assembler,  824-825,  843-844 

Ada,  109-110,  127-134 

and  AZ-terminated  files,  605-608,  634-636 

C  compilers,  545-567,  585-587 

cubic  spline  for  Unix,  609-614,  637-640 

cypher  shell,  340-345,  360-363 

data-segment  extender  in  Turbo  Pascal,  785-789,  790-793 

diagnostic,  for  memory  errors,  654-658,  662-663 

directory  traversal,  605-608,  634-636 

dissolve  routine  for  Macintosh,  752-758,  776-784 

Draw  Poker,  102-108,  127-134 

dumb-terminal  emulator,  398-399,  419-430 

game  of  LIFE,  253-254,  269 

general-purpose  sort  utility,  388-391, 410-416 

IBM  PC  graphics,  147-148,  149-151 

in  C,  to  change  master  environment  block,  845-848,  854—855 

initializer  for  mnemonic  look-up  table,  331-339,  353-359 

make  utility,  239-240, 261-263 

math  functions  on  NS320xx,  815-817 

MS-DOS  utility,  299-300,  297-298 

multitasking  Turbo  Pascal,  175-176, 204-206 

Pascal  dialect  translator,  184-186 

prototyping,  320 

pseudorandom  number  generator,  1 1 1-113,  134-136 
screen  images  of  Mandelbrot  set,  749-75 1 ,  765-775 
set/examine  switch  character,  239-240,  261-263 
small  macro  assembler  COM,  854—855,  845-848 
software  design  tools,  320-324 
sort,  error  in,  742 

translator  between  8-bit  and  16-bit  MPUs,  689-693,  711-712 
variable  metric  minimizer,  168-174,  197-203,  273-296 
VDISK,  problems  with,  648-633,  659-661 
window  manager  for  IBM  PC,  364-367,  368-370 
windows  with  Forth  on  IBM  PC,  471-476,  504-509 
word  processor  in  SwyftCard,  395-396 
user  interface  for  Apple  lie,  lie,  395-396 
Protocols 

B,  in  CompuServe,  398-399, 419-430 
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XMODEM  (Christensen)  file  transmission,  92-97,  121-124 
file-transfer,  398-399,  419-430 
Pseudo  operations,  in  PL/68K,  15-25,  61 
Pseudorandom  number  generator,  111-113,  134-136,  533 
Public-domain  software,  109-110,  127-134 
Public-domain  software,  metric  minimizer,  168-174,  197-203, 
273-2% 

Queues,  in  task  scheduler,  806-814,  826-842 

Radix  sort,  algorithm,  use  on  microcomputers,  615-617,  641-642 
Radix  sort,  compared  to  shell  sort,  615-617,  641-642 
RAFOS  float,  Forth-controlled  lab  instrument,  467-470,  493-503, 
628-630 

Random  engine,  752-758,  776-784 
Raskin,  Jef  -  interview,  325-329 

Raskin,  Jef,  designer  of  user  interface  for  Apple  lie,  lie,  395-396 

Ream,  Edward  K.,  15-25,  61 

Redirection,  in  MS  DOS  shell,  239-240,  261-263 

Relph,  Richard,  545-567,  585-587 

Right  to  Assemble,  The,  224-225,  214,  371-372, 451^52,  483-485, 
532-533,  570-573,  603-604,  631-632,  662-663,  654-658, 
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Ritter,  Terry,  92-97,  121-124 

ROM  routines,  use  in  screen-image  program,  749-751, 765-775 

Rodman,  Richard,  824-825,  843-844 

Routines 

68000.  299-300,  297-298 

8086  binary-to  decimal  ASCU  conversion,  297-298,  299-300 

assembler,  in  Turbo  Pascal,  713-715,  717-719 

for  AVL  package,  538-544,  574-584,  675 

for  B  file-transfer  protocol,  398-399,  419-430 

generic,  in  Modula-2,  588-590,  591-593 

generic  C,  creating  through  preprocessor,  804 

generic,  in  Ada,  588-590,  591-593 

pattern-matching,  for  more  utility,  679-681,  702-710 

random  number  generator,  533 

square  root  calculation,  603-604,  631-632 

square  root  calculation  224—225,  214 

start-up,  command-line,  and  trace,  41-46,  64-72,  136-146, 

215-223 

string  comparison,  8086  and  68000,  854-855,  845-848 
syntax  analysis  in  68000  assembler,  258-261,  270-272 
tree-printing,  455-460,  486-490 
Unix-like  shell,  163-167,  188-196 
Rules  of  inference,  241-252,  264-268 
Run-time  library,  in  Tele  OS,  806-814,  826-842 

Screen-image  program,  for  Macintosh,  749-751,  765-775 
Scacehitti,  Fred  A.,  340-345,  360-363 
Series  32000  Cross  Assembler,  824-825,  843-844 
Sets,  in  C,  737-742, 759-763 

Shammas,  Namir  Clement,  438^140, 432,  591-593,  588-590, 

591-593,  694-701,  790-793, 785-789,  856-858,  849-853, 
790-793 

Shaw,  George  W.,  Ill ,  461^66, 491^192 
Shell 

sort,  compared  to  radix  sort,  615-617,  641-642 
for  MS-DOS,  10-14,46-60,  88-91,  1 14,120 
Simon,  Morris,  818-823 

Simple  Multitasking  Operating  System  for  Real-Time  Applications,  A, 
26-32,  62-63 

Simple  Plots  with  the  Enhanced  Graphics  Adapter .  604,  633 
Simulator,  8080  for  68000, 41-46,  64-72,  136-146,  215-223 
Small  C,  340-345,  360-363 

Small  macro  assembler  COM  program,  854-855,  845-848 
Softky,  Sheldon  D.,  245-257 
Software  reviews 

C  compilers  for  MS-DOS,  545-567,  585-587 
Microsoft  C  compiler  4.0,  737-742,  759-763 
Modula-2  compilers  for  IBM  PC,  694-701 
Turbo  Prolog,  programming  language,  618-623 


environment  for  Apple  He,  lie,  395-396 
program  design  tool,  320-324 
Sorens,  Michael  J.,  184-186 
Sort  Program,  error  in,  742 

Sort,  general-purpose  sorting  utility,  388-391,  410-416 
Source  code  correction,  311,  346-347 
Speeding  MS-DOS  Execution,  180-183,  207-213 
Spline  utility,  for  Unix,  609-614,  637-640 
Square  root,  calculation  of,  451^152,  483-485,  532-533,  570-573, 
603-604,  631-632,  736 
Steinman,  Jan  W.,  654-658  662-663 
String  compares,  on  8086,  713-715,  717-719 
String-comparison  routines,  8086  and  68000-based,  845-848, 
854-855 

Structured  Programming,  432,  438-440,  516-521,  588-590, 

591-593,  720-724,  785-789,  790-793,  804,  849-853,  856-858 
Subroutines 

Turbo  Pascal,  175-176,  204-206 
MS-DOS  shell,  88-91,  1 14,120 
opcode  simulation,  41-46,  64-72,  136-146,  215-223 
Swaine,  Michael,  178-179,  618-623 
SwyftCard 

user  interface  for  Apple  He, He,  395-396 
Jef  Raskin's  New  User  Interface,  395-396 
System  Extension  Word  Set,  in  Forth  standard,  461-466, 491-492 
Systems,  SIMTEL  20,  109-1 10,  127-134 
Systolic  array,  as  cellular  automaton,  253-254,  269 

TNZ:  An  8-bit  to  16-bit  Translator,  689-693,  711-712 
Task  scheduler,  part  of  multitasking  OS  for  IBM  PC,  806-814, 
826-842 

Telecommunications,  error  checking  in,  392-394,  417-418 
Telecommunications,  file-transfer  protocols  in,  398-399, 419-430 
Text-searching  algorithm,  in  8086  assembly  language,  717-719, 
713-715 

Thomas,  John  A.,  385-387, 409 
Thomas,  Levi,  395-396,  419-430 

Top-down  or  bottom-up  design,  in  Modula-2,  258-261,  270-272 
Translator,  for  8-bit  to  16-bit  programs,  689-693,  71 1-712 
Traverse  algorithms,  455-460,  486-490 
Tree-printing  routines,  455-460,  486-490 
Trojan  horse  programs,  73,  74-76 

Turbo  Extender,  data-segment  extender  for  Turbo  Pascal,  785-789, 
790-793 

Turbo  Pascal,  92-97,  121-124,  175-176,  204-206,  713-715, 
717-719,  849-853, 

856-858 

driver,  98-101,  125-126 
Turbo  Prolog,  618-623 

compared  with  PROLOG,  618-623 
Turbo  boards,  for  IBM  PC,  624-627,  643-647 
Turner,  Nicholas,  26-32,  62-63,  398-399, 419-430,  371-372 

Unix,  609-614,  637-640 

current  shell  level,  315-319,  348-349 
User  interface  design,  320-324,  325-329 

Variable  Metric  Minimizer,  A,  168-174,  197-203,  273-296 
VDISK,  PC/AT  program,  problems  with,  659-661,  648-633 
VMEbus  hardware,  on  68K  multitasking  kernel,  26-32,  62-63 
Viewpoint 

Inefficient  C,  8 

What's  Wrong  with  C,  673-675 
Viles,  Fred,  545-567, 585-587 
Virtual  memory,  on  80386,  682-688 
Virtual-display  environment,  on  82786,  743-748,  764 

Walker,  Bill,  1 1 1-1 13,  134-136 
Weather  prediction,  in  systolic  array,  253-254,  269 
Weissman,  Gregg,  180-183,  207-213 
Wilcox,  Alan  D.,  33-40 

Wildcard  file-name  expansion,  in  assembler,  845-848,  854-855 


Window  manager  for  IBM  PC,  364-367,  368-370 
Windows 

hardware,  in  graphics  chips,  743-748,  764 
in  M2SDS  compiler,  694-70 1 
in  screen  images  for  Mac,  749-751,  765-775 
use  of  with  Forth,  471-476, 504-509 
Worm,  memory-test  program,  654-658,  662-663 

X68000  Cross  Assembler 

in  Modula-2,  258-26 1 , 270-272 
op  codes  for,  331-339,  353—359 
XMODEM,  92-97,  121-124 

Z-com,  auto-install  version  of  Z-system,  818-823 
Z-system,  818-823 

Z80,  340-345,  360-363,  689-693,  71 1-712 
code,  use  of  in  Z-System,  8 1 8-823 
system,  615-617,  641-642 
ZCPR3  and  ZRDOS,  elements  of  Z-System,  818-823 
AZ-terminated  files,  605-608,  634-636 
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Software  Availability 

All  the  listings  that  appeared  in  the  1986  issues  of  Dr.  Dobb's  Journal  are  available  on 
disk,  except  for  the  C  Chest  Column  listings  in  the  January  through  March  issues.  They 
have  been  combined  and  incorporated  into  a  book  called  On  Command:  Writing  a  Unix- 
Like  Shell  for  MS-DOS,  by  Allen  Holub.  This  book  is  also  available  from  M&T 
Publishing.  (See  our  other  products  listed  in  the  back  of  this  volume.) 

The  1986  listings  are  available  on  one  of  three  disks:  January  through  April,  May  through 
August,  and  September  through  December.  They  are  available  in  the  following  formats: 
MS-DOS,  Macintosh,  or  CP/M.  For  CP/M  disks,  please  specify:  Apple,  Osborne, 
Kaypro,  Zenith  Z-100  DS/DD,  or  8"  SS/SD. 

To  order  1986  listings  disks  send  a  check,  money  order,  or  credit  card  number  with 
expiration  date,  at  $14.95  per  disk,  to 

1986  Listings  Disk 
M&T  Books 
501  Galveston  Dr. 

Redwood  City,  CA  94063 

Please  specify  which  disk  you  want,  as  well  as  the  format.  If  you  are  a  California  resident, 
you  must  include  the  appropriate  sales  tax. 


Other  Software  Tools 

from  Dr.  Dobb’s  Journal  and  M&T  Publishing 


Dr.  Dobb’s  Toolbook  of  C  Item  #005  $29.95 

From  Dr.  Dobb’s  and  Brady  Communications,  this  book  includes  a  comprehensive  library  of  valuable  C 
code.  Dr.  Dobb’s  most  popular  articles  on  C  are  updated  and  reprinted  here,  along  with  new  C  programming 
tools.  This  book  includes  a  complete  C  compiler,  an  assembler,  text  processing  programs,  and  more! 


The  Small-C  Handbook  by  James  Hendrix  Item  #006  $17.95 

The  Small-C  Handbook  with  MS/PC-DOS  Addendum  Item  #006A  $22.95 

Also  from  Dr.  Dobb’s  and  Brady  Communications,  the  handbook  is  a  valuable  companion  to  the  Small-C 
compiler,  described  below.  The  book  explains  the  language  and  the  compiler  and  contains  entire  source 
listings  of  the  compiler  and  its  library  of  arithmetic  and  logical  routines. 


Small-C  Compiler  Item  #007  $19.95 

Like  a  home  study  course  in  compiler  design,  the  Small-C  Compiler  and  The  Small-C  Handbook  (above) 
provide  all  you  need  to  learn  how  compilers  are  contracted,  as  well  as  teaching  the  C  language  at  its  most 
fundamental  level.  Full  source  code  is  included  on  disk  in  both  CP/M  and  MS/PC-DOS  versions. 


Small  Tools:  Programs  or  Text  Processing  Item  #010A  $29.95 

This  package  of  text  processing  programs  written  in  Small-C  is  designed  to  perform  specific,  modular 
functions  on  text  files.  Source  code  only  is  included.  Small  Tools  is  available  in  both  CP/M  and  MS/PC- 
DOS  versions  and  includes  complete  documentation. 


Small-Mac:  An  Assembler  for  Small-C  Item  #012A  $29.95 

Small-Mac  is  a  macro  assembler  designed  to  stress  simplicity,  portability,  adaptability,  and  educational 
value.  Small-Mac  is  available  for  CP/M  systems  only  and  includes  source  code  on  disk  with  complete 
documentation. 


On  Command:  Writing  a  Unix-Like  Shell  for  MS-DOS  Item  #1 63  $39.95 

Learn  how  to  write  shells  applicable  to  MS-DOS,  as  well  as  to  most  other  programming  environments. 
This  book  and  disk  include  a  full  description  of  a  Unix-like  shell,  complete  C  source  code,  a  thorough 
discussion  of  low-level  DOS  interfacing  and  significant  examples  of  C  programming  at  the  system  level. 
All  source  code  is  included  on  disk. 

/util:  A  Unix-like  Utility  package  for  MS-DOS  Item  #161  $29.95 

This  collection  of  utilities  is  intended  to  be  accessed  through  SH  but  can  be  used  separately.  It  contains 
programs  and  subroutines  that,  when  coupled  with  SH,  create  a  fully  functional  Unix-like  environment.  The 
package  includes  a  disk  with  full  C  source  code  and  documentation  in  a  Unix-style  manual. 


Taming  MS-DOS  Item  #060  $19.95  With  Disk  Item  #061  $34.95 

Taming  MS-DOS  takes  you  beyond  the  basics,  picking  up  where  your  DOS  manual  leaves  off.  You'll  learn 
how  to  create  a  memory-resident  clock,  how  to  rename  subdirectories  and  change  file  attributes,  how  to 
create  configurable  AUTOEXEC.BAT  files,  and  how  to  customize  CONFIG.SYS  and  use  ANSI.SYS  to 
change  the  appearance  of  DOS.  You'll  also  find  extensive  batch  file  coverage  with  example  routines  that  use 
redirection  operators,  filters,  and  pipes  and  ready-to-use  assembly-language  programs  that  enhance  DOS. 
Full  source  code  is  included  on  disk. 


Tele  Operating  System  Toolkit 

This  task  scheduling  algorithm  drives  the  Tele  Operating  System  and  is  composed  of  several  components. 
When  integrated  they  form  an  independent  operating  system  for  any  8086-based  machine.  Tele  has  also  been 
designed  for  compatibility  with  MS-DOS,  Unix,  and  the  MOSI  standard.  The  main  compon  it.  The 
System  Kernel,  is  available  now.  Future  components  of  the  toolkit  will  include  Console,  File,  and  Index 
systems. 


SK:  The  System  Kernel  Item  #090  $49.95 

The  System  Kernel  contains  an  initialization  module,  general-purpose  utility  functions, 
and  a  real-time  task  management  system.  The  kernel  provides  MS-DOS  applications  with 
multitasking  capabilities.  The  System  Kernel  is  required  by  all  other  components.  All 
source  code  is  included  on  disk  in  MS-DOS  format. 

DS:  The  Display  Driver  Item  #091  $39.95 

This  component  contains  BIOS  level  drivers  for  a  memory-mapped  display,  window 
management  support  and  communication  coordination  between  the  operator  and  tasks  in  a 
multitasking  environment.  Available  March  1987.  All  source  code  is  included  on  disk  in 
MS-DOS  format. 

FS:  The  File  System  Item  #092  $39.95 

The  File  System  supports  MS-DOS  disk  file  structures  and  serial  communication 
channels.  Available  May  1987.  All  source  code  is  included  on  disk  in  MS-DOS  format. 

XS:  The  Index  System  Item  #093  $39.95 

The  Index  System  implements  a  tree-structured  free-form  database.  Available  June  1987. 

All  source  code  is  included  on  disk  in  MS-DOS  format. 

Dr.  Dobb’s  Z80  Toolbook  Item  #022  $25  With  Disk  Item#022A  $40 

This  book  contains  everything  users  need  to  write  their  own  Z80  assembly-language  programs,  including  a 
method  of  designing  programs  and  coding  them  in  assembly  language  and  a  complete,  integrated  toolkit  of 
subroutines.  All  the  software  in  the  book  is  available  on  disk. 

Dr.  Dobb’s  Toolbook  of  Forth  Item  #  030  $22.95  With  Disk  Item  #031  $39.95 

This  comprehensive  collection  of  useful  Forth  programs  and  tutorials  contains  expanded  versions  of  DDT  s 
best  Forth  articles  and  other  material,  including  practical  code  and  in-depth  discussions  of  advanced  Forth 
topics.  The  screens  in  the  book  are  also  available  on  disk  as  ASCII  files  in  the  following  formats:  MS/PC- 
DOS,  Apple  II,  Macintosh,  CP/M. 


Dr.  Dobb’s  Toolbook  of 68000  Programming  Item  #  040  $29.95 

From  Dr.  Dobb’s  and  Brady  Communications,  this  collection  of  practical  programming  tips  and  tools  for 
the  68000  family  contains  the  best  68000  articles  reprinted  from  Dr.  Dobb’ s  along  with  much  new 
material.  The  book  contains  many  useful  applications  and  examples.  The  software  in  the  book  is  also 
available  on  disk  in  the  following  formats:  MS/PC-DOS,  Macintosh,  CP/M  8",  Osborne,  Amiga,  Atari 
520ST. 


The  Turbo  Pascal  Toolbook  Item  #080  $25.95  With  Disk  Item  #081  $45.95 

This  book  contains  routines  and  sample  programs  to  make  your  programming  easier  and  more  powerful. 
You'll  find  an  extensive  library  of  low-level  routines;  external  sorting  and  searching  tools;  window 
management;  artificial  intelligence  techniques;  mathematical  expression  parsers,  including  two  routines  that 
convert  mathematical  expressions  into  RPN  tokens;  and  a  smart  statistical  regression  model  finder.  More 
than  800K  of  source  code  is  available  on  disk  for  MS-DOS  systems. 


Statistical  Toolbox  for  Turbo  Pascal  Item  #050  $69.95 

Two  statistical  packages  in  one!  A  library  disk  and  reference  manual  that  includes  statistical  distribution 
functions,  random  number  generation,  basic  descriptive  statistics,  parametric  and  nonparametric  statistical 
testing,  bivariate  linear  regression, and  multiple  and  polynomial  regression.  The  demonstration  disk  and 
manual  incorporate  these  library  routines  into  a  fully  functioning  statistical  program.  For  IBM  PCs  and 
compatibles. 

Turbo  Advantage  Item  #070  $49.95 

A  library  of  more  than  200  routines,  with  source  code  sample  programs,  and  documentation.  Routines  are 
organized  and  documented  under  the  following  categories:  bit  manipulation,  file  management,  MS-DOS 
support,  string  operations,  arithmetic  calculations,  data  compression,  differential  equations,  Fourier  analysis 
and  synthesis,  and  much  more!  Source  code  is  included.  For  MS/PC-DOS  systems. 

Turbo  Advantage:  Complex  Item  #071  $89.95 

This  library  provides  the  Turbo  Pascal  code  for  digital  filters,  boundary-value  solutions,  vector  and  matrix 
calculations  with  complex  integers  and  variables,  Fourier  transforms,  and  calculations  of  convolution  and 
correlation  functions.  Some  of  the  Turbo  Advantage :  Complex  routines  are  most  effectively  used  with 
Turbo  Advantage.  Source  code  and  documentation  included. 


Turbo  Advantage:  Display  Item  #072  $69.95 

Turbo  Advantage:  Display  includes  an  easy-to-use  form  processor  and  30  Turbo  Pascal  procedures  and 
functions  to  facilitate  linking  created  forms  to  your  program.  Full  source  code  and  documentation  are 
included.  Some  of  the  Turbo  Advantage  routines  are  necessary  to  compile  Turbo  Advantage:  Display. 


Dr.  Dobb’s  Listings  on  Disk  $14.95 
1987 

As  a  useful  adjunct  to  the  magazine.  Dr.  Dobb’s  offers  the  convenience  of  selected  listings  on  disk.  Listings 
from  1987  are  available  by  month  in  the  following  formats:  MS/PC-DOS,  Macintosh,  and  Kaypro.  Please 
specify  the  monthly  issue  from  which  you'd  like  the  listings. 

1986 

Listings  for  1986  are  available  on  one  of  three  disks:  January  through  April,  May  through  August,  and 
September  through  December.  The  1986  listings  are  available  in  MS/PC-DOS,  Macintosh,  and  CP/M 
formats.  For  CP/M  disks  please  specify  Apple,  Osborne,  Kaypro,  Zenith  Z-100  DS/DD,  8"  SS/SD. 

Dr.  Dobb’s  Journal  of  Software  Tools,  1-Year  Subscription  Item  #001  $25 


To  order  any  of  these  products,  send  your  payment  along  with  $2.25  per  item  for  shipping 
to  M&T  Publishing  Inc.,  501  Galveston  Dr.,  Redwood  City,  CA  94063.  When  ordering 
disks,  please  indicate  format. 


The  Dr.  Dobb's  Series 

Volume  1 

Chronicles  the  advent  of  the  microcomputer  era  in  1976.  Always  pertinent  for  bit 
crunching  and  byte  saving,  home-brew  computer  projects,  and  the  technical  history  of 
home  computing.  Topics  include:  Tiny  basic,  the  first  words  on  CP/M,  Speech 
Synthesis,  Floating,  Point  Routines,  6502  Disassembler  for  the  Apple,  and  much  more. 

Volume  2 

The  small  computer  emerges  as  a  powerful  tool  for  the  modern  age  in  these  issues  from 
1977.  Topics  include:  Lawrence  Livermore  Lab’s  basic,  Dr.  Starkweather’s  pilot, 
Using  a  Modem,  String  Handling  Techniques,  Ciphers,  Turtle  Graphics,  micro  util¬ 
ities. 

Volume  3 

Explores  the  foundations  of  the  mass  market  computer  industry  in  1978.  Topics 
include:  Programming  in  basic,  pilot,  and  Pascal,  RAM  Memory  Testers,  Apple 
utility  programs,  S-100  Bus  Standard,  strubal,  A  Structured  basic  Compiler. 

Volume  4 

Heralds  the  widespread  acceptance  of  the  microcomputer  in  America.  Innovative 
ideas  and  articles  guide  the  reader  through  the  age  of  discovery  in  1979.  Topics  include: 
Selecting  Business  Software,  Microcomputer  Speech  and  Music,  Information  Net¬ 
works,  interfacing  techniques. 

Volume  5 

Focuses  on  the  technological  promise  of  the  modern  microcomputer  and  the  creative 
challenge  facing  programmers  in  1980.  Topics  include:  The  revolutionary  impact  of 
CP/M,C  programming  and  the  UNIX  operating  systems,  survey  of  computer  net¬ 
works,  software  portability,  introduction  to  Forth,  compiler  writing. 

Volume  6 

The  microcomputer  enters  the  mainstream — these  issues  assess  the  revolutionary 
impact  of  microcomputers  on  the  individual  and  on  our  society  in  1981.  Topics 
include:  Computer  Conferencing,  The  Power  of  Forth,  8-  and  16-Bit  Technology, 
Rubik’s  Cube  Simulator,  An  Adventure  Game  Development  System. 

Volume  7 

Examines  the  potential  of  powerful  16-bit  micros  including  the  birth  of  the  IBM  PC  in 
1982.  Topics  include:  In-depth  coverage  of  Forth,  68000,  8088  programming,  C 
software  tools,  utilities  for  CP/M  including  a  spelling  checker,  using  bulletin  boards, 
and  more. 

Volume  8 

DDJ  turns  pro.  Some  of  the  most  powerful,  professional  programmer’s  tools  ever 
published  in  a  magazine  are  in  this  volume,  including  Small-C,  the  RED  editor,  and  an 
Ada  subset. 

Volume  9 

Shaping  things  to  come.  In  1984  DDJ  examined  new  programming  environments 
PROLOG,  expert  systems,  Modula-2,  and  Pascal.  Other  topics  include  GREP,  Unix 
internals,  and  two  encryptions  systems. 

,  Volume  10 

The  year  of  living  dangerously.  In  1985  DDJ  added  more  memory,  a  SCSI  port,  and  a 
hard  disk  to  the  MacinTosh;  challenged  the  Unix  establishment  with  plans  for  a  free 
Unix;  and  asked  hard  questions  about  privacy  and  control  in  the  Information  Age. 
Includes  software  tools  in  C,  Modula-2,  Forth,  Pascal,  assembly  language,  and  Prolog. 

t  Volume  1 1 

The  promise  of  power.  Desktop  computers  began  to  rival  minis  and  mainframes  in 
power,  DDJ  covered  the  changes  with  issues  on  the  68000,  parallel,  processing, 
artificial  intelligence,  the  80386  and  multitasking.  DDJ  also  supported  the  new  chips 
with  assemblers,  translators  and  other  development  tools. 
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